@gguf/claw

--- summary: 关于 OpenClaw 安装、配置和使用的常见问题 title: 常见问题 x-i18n: generated_at: "2026-02-01T21:32:04Z" model: claude-opus-4-5 provider: pi source_hash: 5a611f2fda3325b1c7a9ec518616d87c78be41e2bfbe86244ae4f48af3815a26 source_path: help/faq.md workflow: 15 --- # 常见问题快速解答及针对实际部署场景（本地开发、VPS、多智能体、OAuth/API 密钥、模型故障转移）的深入故障排除。运行时诊断请参阅[故障排除](/gateway/troubleshooting)。完整配置参考请参阅[配置](/gateway/configuration)。 ## 目录 - [快速开始与首次运行设置](#quick-start-and-firstrun-setup) - [我卡住了，最快的排障方法是什么？](#im-stuck-whats-the-fastest-way-to-get-unstuck) - [安装和设置 OpenClaw 的推荐方式是什么？](#whats-the-recommended-way-to-install-and-set-up-openclaw) - [新手引导后如何打开仪表板？](#how-do-i-open-the-dashboard-after-onboarding) - [如何在本地和远程环境中验证仪表板（令牌）？](#how-do-i-authenticate-the-dashboard-token-on-localhost-vs-remote) - [我需要什么运行时？](#what-runtime-do-i-need) - [能在 Raspberry Pi 上运行吗？](#does-it-run-on-raspberry-pi) - [Raspberry Pi 安装有什么建议？](#any-tips-for-raspberry-pi-installs) - [卡在 "wake up my friend" / 新手引导无法启动，怎么办？](#it-is-stuck-on-wake-up-my-friend-onboarding-will-not-hatch-what-now) - [能否将我的设置迁移到新机器（Mac mini）而不重新进行新手引导？](#can-i-migrate-my-setup-to-a-new-machine-mac-mini-without-redoing-onboarding) - [在哪里查看最新版本的更新内容？](#where-do-i-see-whats-new-in-the-latest-version) - [无法访问 docs.openclaw.ai（SSL 错误），怎么办？](#i-cant-access-docsopenclawai-ssl-error-what-now) - [stable 和 beta 有什么区别？](#whats-the-difference-between-stable-and-beta) - [如何安装 beta 版本，beta 和 dev 有什么区别？](#how-do-i-install-the-beta-version-and-whats-the-difference-between-beta-and-dev) - [如何试用最新代码？](#how-do-i-try-the-latest-bits) - [安装和新手引导通常需要多长时间？](#how-long-does-install-and-onboarding-usually-take) - [安装程序卡住了？如何获取更多反馈？](#installer-stuck-how-do-i-get-more-feedback) - [Windows 安装提示找不到 git 或无法识别 openclaw](#windows-install-says-git-not-found-or-openclaw-not-recognized) - [文档没有解答我的问题——如何获得更好的答案？](#the-docs-didnt-answer-my-question-how-do-i-get-a-better-answer) - [如何在 Linux 上安装 OpenClaw？](#how-do-i-install-openclaw-on-linux) - [如何在 VPS 上安装 OpenClaw？](#how-do-i-install-openclaw-on-a-vps) - [云/VPS 安装指南在哪里？](#where-are-the-cloudvps-install-guides) - [可以让 OpenClaw 自行更新吗？](#can-i-ask-openclaw-to-update-itself) - [新手引导向导具体做了什么？](#what-does-the-onboarding-wizard-actually-do) - [运行 OpenClaw 需要 Claude 或 OpenAI 订阅吗？](#do-i-need-a-claude-or-openai-subscription-to-run-this) - [能否使用 Claude Max 订阅而不需要 API 密钥？](#can-i-use-claude-max-subscription-without-an-api-key) - [Anthropic "setup-token" 认证如何工作？](#how-does-anthropic-setuptoken-auth-work) - [在哪里获取 Anthropic setup-token？](#where-do-i-find-an-anthropic-setuptoken) - [是否支持 Claude 订阅认证（Claude Code OAuth）？](#do-you-support-claude-subscription-auth-claude-code-oauth) - [为什么我看到 `HTTP 429: rate_limit_error`（来自 Anthropic）？](#why-am-i-seeing-http-429-ratelimiterror-from-anthropic) - [支持 AWS Bedrock 吗？](#is-aws-bedrock-supported) - [Codex 认证如何工作？](#how-does-codex-auth-work) - [是否支持 OpenAI 订阅认证（Codex OAuth）？](#do-you-support-openai-subscription-auth-codex-oauth) - [如何设置 Gemini CLI OAuth？](#how-do-i-set-up-gemini-cli-oauth) - [本地模型适合日常聊天吗？](#is-a-local-model-ok-for-casual-chats) - [如何将托管模型流量限制在特定区域？](#how-do-i-keep-hosted-model-traffic-in-a-specific-region) - [我必须购买 Mac Mini 才能安装吗？](#do-i-have-to-buy-a-mac-mini-to-install-this) - [iMessage 支持需要 Mac mini 吗？](#do-i-need-a-mac-mini-for-imessage-support) - [如果我买了 Mac mini 运行 OpenClaw，能连接到我的 MacBook Pro 吗？](#if-i-buy-a-mac-mini-to-run-openclaw-can-i-connect-it-to-my-macbook-pro) - [可以使用 Bun 吗？](#can-i-use-bun) - [Telegram：`allowFrom` 填什么？](#telegram-what-goes-in-allowfrom) - [多人能否使用同一个 WhatsApp 号码配合不同的 OpenClaw 实例？](#can-multiple-people-use-one-whatsapp-number-with-different-openclaw-instances) - [能否同时运行一个“快速聊天”智能体和一个“用 Opus 编程”的智能体？](#can-i-run-a-fast-chat-agent-and-an-opus-for-coding-agent) - [Homebrew 在 Linux 上可用吗？](#does-homebrew-work-on-linux) - [可编辑（git）安装和 npm 安装有什么区别？](#whats-the-difference-between-the-hackable-git-install-and-npm-install) - [之后可以在 npm 和 git 安装之间切换吗？](#can-i-switch-between-npm-and-git-installs-later) - [应该在笔记本电脑还是 VPS 上运行 Gateway 网关？](#should-i-run-the-gateway-on-my-laptop-or-a-vps) - [在专用机器上运行 OpenClaw 有多重要？](#how-important-is-it-to-run-openclaw-on-a-dedicated-machine) - [VPS 的最低要求和推荐操作系统是什么？](#what-are-the-minimum-vps-requirements-and-recommended-os) - [可以在虚拟机中运行 OpenClaw 吗？有什么要求？](#can-i-run-openclaw-in-a-vm-and-what-are-the-requirements) - [什么是 OpenClaw？](#what-is-openclaw) - [用一段话描述 OpenClaw？](#what-is-openclaw-in-one-paragraph) - [价值主张是什么？](#whats-the-value-proposition) - [刚设置好，应该先做什么？](#i-just-set-it-up-what-should-i-do-first) - [OpenClaw 日常最常用的五个场景是什么？](#what-are-the-top-five-everyday-use-cases-for-openclaw) - [OpenClaw 能否帮助 SaaS 进行获客、外联、广告和博客？](#can-openclaw-help-with-lead-gen-outreach-ads-and-blogs-for-a-saas) - [相比 Claude Code，在 Web 开发方面有什么优势？](#what-are-the-advantages-vs-claude-code-for-web-development) - [Skills 与自动化](#skills-and-automation) - [如何自定义 Skills 而不弄脏仓库？](#how-do-i-customize-skills-without-keeping-the-repo-dirty) - [可以从自定义文件夹加载 Skills 吗？](#can-i-load-skills-from-a-custom-folder) - [如何为不同任务使用不同模型？](#how-can-i-use-different-models-for-different-tasks) - [机器人在执行繁重工作时卡住了，如何卸载任务？](#the-bot-freezes-while-doing-heavy-work-how-do-i-offload-that) - [定时任务或提醒没有触发，应该检查什么？](#cron-or-reminders-do-not-fire-what-should-i-check) - [如何在 Linux 上安装 Skills？](#how-do-i-install-skills-on-linux) - [OpenClaw 能否按计划或在后台持续运行任务？](#can-openclaw-run-tasks-on-a-schedule-or-continuously-in-the-background) - [能否从 Linux 运行仅限 Apple/macOS 的 Skills？](#can-i-run-applemacosonly-skills-from-linux) - [有 Notion 或 HeyGen 集成吗？](#do-you-have-a-notion-or-heygen-integration) - [如何安装用于浏览器接管的 Chrome 扩展？](#how-do-i-install-the-chrome-extension-for-browser-takeover) - [沙箱与记忆](#sandboxing-and-memory) - [有专门的沙箱文档吗？](#is-there-a-dedicated-sandboxing-doc) - [如何将主机文件夹绑定到沙箱中？](#how-do-i-bind-a-host-folder-into-the-sandbox) - [记忆是如何工作的？](#how-does-memory-work) - [记忆总是遗忘，如何让它持久保存？](#memory-keeps-forgetting-things-how-do-i-make-it-stick) - [记忆是否永久保留？有什么限制？](#does-memory-persist-forever-what-are-the-limits) - [语义记忆搜索需要 OpenAI API 密钥吗？](#does-semantic-memory-search-require-an-openai-api-key) - [磁盘上的文件位置](#where-things-live-on-disk) - [OpenClaw 使用的所有数据都保存在本地吗？](#is-all-data-used-with-openclaw-saved-locally) - [OpenClaw 将数据存储在哪里？](#where-does-openclaw-store-its-data) - [AGENTS.md / SOUL.md / USER.md / MEMORY.md 应该放在哪里？](#where-should-agentsmd-soulmd-usermd-memorymd-live) - [推荐的备份策略是什么？](#whats-the-recommended-backup-strategy) - [如何完全卸载 OpenClaw？](#how-do-i-completely-uninstall-openclaw) - [智能体可以在工作区外工作吗？](#can-agents-work-outside-the-workspace) - [我处于远程模式——会话存储在哪里？](#im-in-remote-mode-where-is-the-session-store) - [配置基础](#config-basics) - [配置文件是什么格式？在哪里？](#what-format-is-the-config-where-is-it) - [我设置了 `gateway.bind: "lan"`（或 `"tailnet"`），现在什么都监听不了 / UI 显示未授权](#i-set-gatewaybind-lan-or-tailnet-and-now-nothing-listens-the-ui-says-unauthorized) - [为什么现在在 localhost 也需要令牌？](#why-do-i-need-a-token-on-localhost-now) - [更改配置后需要重启吗？](#do-i-have-to-restart-after-changing-config) - [如何启用网络搜索（和网页抓取）？](#how-do-i-enable-web-search-and-web-fetch) - [config.apply 清空了我的配置，如何恢复和避免？](#configapply-wiped-my-config-how-do-i-recover-and-avoid-this) - [如何运行一个中心 Gateway 网关配合跨设备的专用工作节点？](#how-do-i-run-a-central-gateway-with-specialized-workers-across-devices) - [OpenClaw 浏览器可以无头运行吗？](#can-the-openclaw-browser-run-headless) - [如何使用 Brave 进行浏览器控制？](#how-do-i-use-brave-for-browser-control) - [远程 Gateway 网关与节点](#remote-gateways-nodes) - [命令如何在 Telegram、Gateway 网关和节点之间传播？](#how-do-commands-propagate-between-telegram-the-gateway-and-nodes) - [如果 Gateway 网关托管在远程，我的智能体如何访问我的电脑？](#how-can-my-agent-access-my-computer-if-the-gateway-is-hosted-remotely) - [Tailscale 已连接但收不到回复，怎么办？](#tailscale-is-connected-but-i-get-no-replies-what-now) - [两个 OpenClaw 实例（本地 + VPS）可以互相通信吗？](#can-two-openclaw-instances-talk-to-each-other-local-vps) - [多个智能体需要独立的 VPS 吗？](#do-i-need-separate-vpses-for-multiple-agents) - [在个人笔记本电脑上使用节点而不是从 VPS SSH 有什么好处？](#is-there-a-benefit-to-using-a-node-on-my-personal-laptop-instead-of-ssh-from-a-vps) - [节点会运行 Gateway 网关服务吗？](#do-nodes-run-a-gateway-service) - [有 API / RPC 方式来应用配置吗？](#is-there-an-api-rpc-way-to-apply-config) - [首次安装的最小“合理”配置是什么？](#whats-a-minimal-sane-config-for-a-first-install) - [如何在 VPS 上设置 Tailscale 并从 Mac 连接？](#how-do-i-set-up-tailscale-on-a-vps-and-connect-from-my-mac) - [如何将 Mac 节点连接到远程 Gateway 网关（Tailscale Serve）？](#how-do-i-connect-a-mac-node-to-a-remote-gateway-tailscale-serve) - [应该在第二台笔记本上安装还是只添加一个节点？](#should-i-install-on-a-second-laptop-or-just-add-a-node) - [环境变量和 .env 加载](#env-vars-and-env-loading) - [OpenClaw 如何加载环境变量？](#how-does-openclaw-load-environment-variables) - [“我通过服务启动了 Gateway 网关，但环境变量消失了。”怎么办？](#i-started-the-gateway-via-the-service-and-my-env-vars-disappeared-what-now) - [我设置了 `COPILOT_GITHUB_TOKEN`，但 models status 显示"Shell env: off"，为什么？](#i-set-copilotgithubtoken-but-models-status-shows-shell-env-off-why) - [会话与多聊天](#sessions-multiple-chats) - [如何开始一个新对话？](#how-do-i-start-a-fresh-conversation) - [如果我从不发送 `/new`，会话会自动重置吗？](#do-sessions-reset-automatically-if-i-never-send-new) - [能否创建一个 OpenClaw 实例团队——一个 CEO 和多个智能体？](#is-there-a-way-to-make-a-team-of-openclaw-instances-one-ceo-and-many-agents) - [为什么上下文在任务中途被截断了？如何防止？](#why-did-context-get-truncated-midtask-how-do-i-prevent-it) - [如何完全重置 OpenClaw 但保留安装？](#how-do-i-completely-reset-openclaw-but-keep-it-installed) - [我遇到了"context too large"错误——如何重置或压缩？](#im-getting-context-too-large-errors-how-do-i-reset-or-compact) - [为什么我看到"LLM request rejected: messages.N.content.X.tool_use.input: Field required"？](#why-am-i-seeing-llm-request-rejected-messagesncontentxtooluseinput-field-required) - [为什么每 30 分钟收到一次心跳消息？](#why-am-i-getting-heartbeat-messages-every-30-minutes) - [需要在 WhatsApp 群组中添加“机器人账号”吗？](#do-i-need-to-add-a-bot-account-to-a-whatsapp-group) - [如何获取 WhatsApp 群组的 JID？](#how-do-i-get-the-jid-of-a-whatsapp-group) - [为什么 OpenClaw 不在群组中回复？](#why-doesnt-openclaw-reply-in-a-group) - [群组/线程与私聊共享上下文吗？](#do-groupsthreads-share-context-with-dms) - [可以创建多少个工作区和智能体？](#how-many-workspaces-and-agents-can-i-create) - [可以同时运行多个机器人或聊天（Slack）吗？应该如何设置？](#can-i-run-multiple-bots-or-chats-at-the-same-time-slack-and-how-should-i-set-that-up) - [模型：默认值、选择、别名、切换](#models-defaults-selection-aliases-switching) - [什么是“默认模型”？](#what-is-the-default-model) - [推荐什么模型？](#what-model-do-you-recommend) - [如何在不清空配置的情况下切换模型？](#how-do-i-switch-models-without-wiping-my-config) - [可以使用自托管模型（llama.cpp、vLLM、Ollama）吗？](#can-i-use-selfhosted-models-llamacpp-vllm-ollama) - [OpenClaw、Flawd 和 Krill 使用什么模型？](#what-do-openclaw-flawd-and-krill-use-for-models) - [如何在运行中切换模型（无需重启）？](#how-do-i-switch-models-on-the-fly-without-restarting) - [能否日常任务用 GPT 5.2，编程用 Codex 5.2？](#can-i-use-gpt-52-for-daily-tasks-and-codex-52-for-coding) - [为什么我看到"Model … is not allowed"然后没有回复？](#why-do-i-see-model-is-not-allowed-and-then-no-reply) - [为什么我看到"Unknown model: minimax/MiniMax-M2.1"？](#why-do-i-see-unknown-model-minimaxminimaxm21) - [能否将 MiniMax 设为默认，复杂任务用 OpenAI？](#can-i-use-minimax-as-my-default-and-openai-for-complex-tasks) - [opus / sonnet / gpt 是内置快捷方式吗？](#are-opus-sonnet-gpt-builtin-shortcuts) - [如何定义/覆盖模型快捷方式（别名）？](#how-do-i-defineoverride-model-shortcuts-aliases) - [如何添加其他提供商（如 OpenRouter 或 Z.AI）的模型？](#how-do-i-add-models-from-other-providers-like-openrouter-or-zai) - [模型故障转移与"All models failed"](#model-failover-and-all-models-failed) - [故障转移是如何工作的？](#how-does-failover-work) - [这个错误是什么意思？](#what-does-this-error-mean) - [`No credentials found for profile "anthropic:default"` 的修复清单](#fix-checklist-for-no-credentials-found-for-profile-anthropicdefault) - [为什么还尝试了 Google Gemini 并且失败了？](#why-did-it-also-try-google-gemini-and-fail) - [认证配置文件：概念和管理方式](#auth-profiles-what-they-are-and-how-to-manage-them) - [什么是认证配置文件？](#what-is-an-auth-profile) - [典型的配置文件 ID 有哪些？](#what-are-typical-profile-ids) - [可以控制首先尝试哪个认证配置文件吗？](#can-i-control-which-auth-profile-is-tried-first) - [OAuth 与 API 密钥：有什么区别？](#oauth-vs-api-key-whats-the-difference) - [Gateway 网关：端口、“已在运行”和远程模式](#gateway-ports-already-running-and-remote-mode) - [Gateway 网关使用什么端口？](#what-port-does-the-gateway-use) - [为什么 `openclaw gateway status` 显示 `Runtime: running` 但 `RPC probe: failed`？](#why-does-openclaw-gateway-status-say-runtime-running-but-rpc-probe-failed) - [为什么 `openclaw gateway status` 显示 `Config (cli)` 和 `Config (service)` 不同？](#why-does-openclaw-gateway-status-show-config-cli-and-config-service-different) - ["another gateway instance is already listening"是什么意思？](#what-does-another-gateway-instance-is-already-listening-mean) - [如何以远程模式运行 OpenClaw（客户端连接到其他位置的 Gateway 网关）？](#how-do-i-run-openclaw-in-remote-mode-client-connects-to-a-gateway-elsewhere) - [控制 UI 显示"unauthorized"（或持续重连），怎么办？](#the-control-ui-says-unauthorized-or-keeps-reconnecting-what-now) - [我设置了 `gateway.bind: "tailnet"` 但无法绑定 / 什么都没监听](#i-set-gatewaybind-tailnet-but-it-cant-bind-nothing-listens) - [可以在同一主机上运行多个 Gateway 网关吗？](#can-i-run-multiple-gateways-on-the-same-host) - ["invalid handshake" / code 1008 是什么意思？](#what-does-invalid-handshake-code-1008-mean) - [日志与调试](#logging-and-debugging) - [日志在哪里？](#where-are-logs) - [如何启动/停止/重启 Gateway 网关服务？](#how-do-i-startstoprestart-the-gateway-service) - [我在 Windows 上关闭了终端——如何重启 OpenClaw？](#i-closed-my-terminal-on-windows-how-do-i-restart-openclaw) - [Gateway 网关已启动但回复始终不到达，应该检查什么？](#the-gateway-is-up-but-replies-never-arrive-what-should-i-check) - ["Disconnected from gateway: no reason"——怎么办？](#disconnected-from-gateway-no-reason-what-now) - [Telegram setMyCommands 因网络错误失败，应该检查什么？](#telegram-setmycommands-fails-with-network-errors-what-should-i-check) - [TUI 没有输出，应该检查什么？](#tui-shows-no-output-what-should-i-check) - [如何完全停止然后启动 Gateway 网关？](#how-do-i-completely-stop-then-start-the-gateway) - [通俗解释：`openclaw gateway restart` 与 `openclaw gateway`](#eli5-openclaw-gateway-restart-vs-openclaw-gateway) - [出现故障时获取更多详情的最快方法是什么？](#whats-the-fastest-way-to-get-more-details-when-something-fails) - [媒体与附件](#media-attachments) - [我的 Skills 生成了图片/PDF，但什么都没发送](#my-skill-generated-an-imagepdf-but-nothing-was-sent) - [安全与访问控制](#security-and-access-control) - [将 OpenClaw 暴露给入站私信安全吗？](#is-it-safe-to-expose-openclaw-to-inbound-dms) - [提示注入只对公开机器人有影响吗？](#is-prompt-injection-only-a-concern-for-public-bots) - [我的机器人应该有自己的邮箱、GitHub 账户或电话号码吗？](#should-my-bot-have-its-own-email-github-account-or-phone-number) - [我能让它自主管理我的短信吗？这安全吗？](#can-i-give-it-autonomy-over-my-text-messages-and-is-that-safe) - [个人助理任务可以使用更便宜的模型吗？](#can-i-use-cheaper-models-for-personal-assistant-tasks) - [我在 Telegram 中运行了 `/start` 但没收到配对码](#i-ran-start-in-telegram-but-didnt-get-a-pairing-code) - [WhatsApp：会给我的联系人发消息吗？配对如何工作？](#whatsapp-will-it-message-my-contacts-how-does-pairing-work) - [聊天命令、中止任务和“停不下来”](#chat-commands-aborting-tasks-and-it-wont-stop) - [如何阻止内部系统消息显示在聊天中？](#how-do-i-stop-internal-system-messages-from-showing-in-chat) - [如何停止/取消正在运行的任务？](#how-do-i-stopcancel-a-running-task) - [如何从 Telegram 发送 Discord 消息？（"Cross-context messaging denied"）](#how-do-i-send-a-discord-message-from-telegram-crosscontext-messaging-denied) - [为什么感觉机器人“忽略”了快速连发的消息？](#why-does-it-feel-like-the-bot-ignores-rapidfire-messages) ## 出问题后的最初六十秒 1. **快速状态（首先检查）** ```bash openclaw status ``` 快速本地摘要：操作系统 + 更新、Gateway 网关/服务可达性、智能体/会话、提供商配置 + 运行时问题（Gateway 网关可达时）。 2. **可粘贴的报告（可安全分享）** ```bash openclaw status --all ``` 只读诊断，附带日志尾部（令牌已脱敏）。 3. **守护进程 + 端口状态** ```bash openclaw gateway status ``` 显示 supervisor 运行状态与 RPC 可达性、探测目标 URL，以及服务可能使用的配置。 4. **深度探测** ```bash openclaw status --deep ``` 运行 Gateway 网关健康检查 + 提供商探测（需要可达的 Gateway 网关）。参阅[健康检查](/gateway/health)。 5. **跟踪最新日志** ```bash openclaw logs --follow ``` 如果 RPC 不可用，回退到： ```bash tail -f "$(ls -t /tmp/openclaw/openclaw-*.log | head -1)" ``` 文件日志与服务日志是分开的；参阅[日志](/logging)和[故障排除](/gateway/troubleshooting)。 6. **运行 doctor（修复）** ```bash openclaw doctor ``` 修复/迁移配置/状态 + 运行健康检查。参阅 [Doctor](/gateway/doctor)。 7. **Gateway 网关快照** ```bash openclaw health --json openclaw health --verbose # 出错时显示目标 URL + 配置路径 ``` 向运行中的 Gateway 网关请求完整快照（仅 WS）。参阅[健康检查](/gateway/health)。 ## 快速开始与首次运行设置 ### 我卡住了，最快的排障方法是什么使用能**看到你机器**的本地 AI 智能体。这比在 Discord 上提问有效得多，因为大多数“卡住了”的情况都是**本地配置或环境问题**，远程帮助者无法检查。 - **Claude Code**：https://www.anthropic.com/claude-code/ - **OpenAI Codex**：https://openai.com/codex/ 这些工具可以读取仓库、运行命令、检查日志，并帮助修复你的机器级别设置（PATH、服务、权限、认证文件）。通过可编辑（git）安装提供**完整源代码**： ```bash curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method git ``` 这会从 **git checkout** 安装 OpenClaw，这样智能体可以读取代码 + 文档，并推理你正在运行的确切版本。你可以随时通过不带 `--install-method git` 重新运行安装程序切回稳定版。提示：要求智能体**计划并监督**修复（逐步进行），然后只执行必要的命令。这样改动较小，更容易审查。如果你发现了真正的 bug 或修复方案，请提交 GitHub issue 或发送 PR： https://github.com/openclaw/openclaw/issues https://github.com/openclaw/openclaw/pulls 从以下命令开始（在寻求帮助时分享输出）： ```bash openclaw status openclaw models status openclaw doctor ``` 它们的作用： - `openclaw status`：Gateway 网关/智能体健康状况 + 基本配置的快速快照。 - `openclaw models status`：检查提供商认证 + 模型可用性。 - `openclaw doctor`：验证并修复常见的配置/状态问题。其他有用的 CLI 检查：`openclaw status --all`、`openclaw logs --follow`、 `openclaw gateway status`、`openclaw health --verbose`。快速调试流程：[出问题后的最初六十秒](#first-60-seconds-if-somethings-broken)。安装文档：[安装](/install)、[安装程序标志](/install/installer)、[更新](/install/updating)。 ### 安装和设置 OpenClaw 的推荐方式是什么仓库推荐从源码运行并使用新手引导向导： ```bash curl -fsSL https://openclaw.ai/install.sh | bash openclaw onboard --install-daemon ``` 向导还可以自动构建 UI 资源。新手引导后，通常在端口 **18789** 上运行 Gateway 网关。从源码安装（贡献者/开发者）： ```bash git clone https://github.com/openclaw/openclaw.git cd openclaw pnpm install pnpm build pnpm ui:build # 首次运行时自动安装 UI 依赖 openclaw onboard ``` 如果你还没有全局安装，通过 `pnpm openclaw onboard` 运行。 ### 新手引导后如何打开仪表板向导现在会在新手引导完成后立即使用带令牌的仪表板 URL 打开浏览器，并在摘要中打印完整链接（带令牌）。保持该标签页打开；如果没有自动启动，请在同一台机器上复制/粘贴打印的 URL。令牌保持在本地主机上——不会从浏览器获取任何内容。 ### 如何在本地和远程环境中验证仪表板令牌 **本地（同一台机器）：** - 打开 `http://127.0.0.1:18789/`。 - 如果要求认证，运行 `openclaw dashboard` 并使用带令牌的链接（`?token=...`）。 - 令牌与 `gateway.auth.token`（或 `OPENCLAW_GATEWAY_TOKEN`）的值相同，UI 在首次加载后会存储它。 **非本地环境：** - **Tailscale Serve**（推荐）：保持绑定 loopback，运行 `openclaw gateway --tailscale serve`，打开 `https://<magicdns>/`。如果 `gateway.auth.allowTailscale` 为 `true`，身份标头满足认证要求（无需令牌）。 - **Tailnet 绑定**：运行 `openclaw gateway --bind tailnet --token "<token>"`，打开 `http://<tailscale-ip>:18789/`，在仪表板设置中粘贴令牌。 - **SSH 隧道**：`ssh -N -L 18789:127.0.0.1:18789 user@host`，然后从 `openclaw dashboard` 打开 `http://127.0.0.1:18789/?token=...`。参阅[仪表板](/web/dashboard)和 [Web 界面](/web)了解绑定模式和认证详情。 ### 我需要什么运行时 Node **>= 22** 是必需的。推荐使用 `pnpm`。**不推荐**使用 Bun 运行 Gateway 网关。 ### 能在 Raspberry Pi 上运行吗可以。Gateway 网关是轻量级的——文档列出 **512MB-1GB RAM**、**1 核**和约 **500MB** 磁盘空间足够个人使用，并指出 **Raspberry Pi 4 可以运行**。如果你需要额外的余量（日志、媒体、其他服务），**推荐 2GB**，但这不是硬性最低要求。提示：小型 Pi/VPS 可以托管 Gateway 网关，你可以在笔记本/手机上配对**节点**以获取本地屏幕/摄像头/画布或命令执行能力。参阅[节点](/nodes)。 ### Raspberry Pi 安装有什么建议简短回答：可以运行，但预期会有一些粗糙之处。 - 使用 **64 位**操作系统并保持 Node >= 22。 - 优先选择**可编辑（git）安装**，以便查看日志和快速更新。 - 先不启用渠道/Skills，然后逐个添加。 - 如果遇到奇怪的二进制问题，通常是 **ARM 兼容性**问题。文档：[Linux](/platforms/linux)、[安装](/install)。 ### 卡在 wake up my friend / 新手引导无法启动，怎么办该界面依赖于 Gateway 网关可达且已认证。TUI 也会在首次启动时自动发送"Wake up, my friend!"。如果你看到该行但**没有回复**且令牌保持为 0，说明智能体从未运行。 1. 重启 Gateway 网关： ```bash openclaw gateway restart ``` 2. 检查状态和认证： ```bash openclaw status openclaw models status openclaw logs --follow ``` 3. 如果仍然挂起，运行： ```bash openclaw doctor ``` 如果 Gateway 网关在远程，确保隧道/Tailscale 连接正常，且 UI 指向正确的 Gateway 网关。参阅[远程访问](/gateway/remote)。 ### 能否将我的设置迁移到新机器（Mac mini）而不重新进行新手引导可以。复制**状态目录**和**工作区**，然后运行一次 Doctor。只要你同时复制**两个**位置，就能保持你的机器人“完全一样”（记忆、会话历史、认证和渠道状态）： 1. 在新机器上安装 OpenClaw。 2. 从旧机器复制 `$OPENCLAW_STATE_DIR`（默认：`~/.openclaw`）。 3. 复制你的工作区（默认：`~/.openclaw/workspace`）。 4. 运行 `openclaw doctor` 并重启 Gateway 网关服务。这会保留配置、认证配置文件、WhatsApp 凭据、会话和记忆。如果你处于远程模式，请记住 Gateway 网关主机拥有会话存储和工作区。 **重要：** 如果你只将工作区提交/推送到 GitHub，你只备份了**记忆 + 引导文件**，但**不包括**会话历史或认证。它们位于 `~/.openclaw/` 下（例如 `~/.openclaw/agents/<agentId>/sessions/`）。相关：[迁移](/install/migrating)、[磁盘上的文件位置](/help/faq#where-does-openclaw-store-its-data)、 [智能体工作区](/concepts/agent-workspace)、[Doctor](/gateway/doctor)、 [远程模式](/gateway/remote)。 ### 在哪里查看最新版本的更新内容查看 GitHub 变更日志： https://github.com/openclaw/openclaw/blob/main/CHANGELOG.md 最新条目在顶部。如果顶部部分标记为 **Unreleased**，则下一个带日期的部分是最新发布版本。条目按**亮点**、**变更**和**修复**分组（需要时还有文档/其他部分）。 ### 无法访问 docs.openclaw.ai（SSL 错误），怎么办一些 Comcast/Xfinity 连接通过 Xfinity Advanced Security 错误地拦截了 `docs.openclaw.ai`。禁用该功能或将 `docs.openclaw.ai` 加入白名单，然后重试。更多详情：[故障排除](/help/troubleshooting#docsopenclawai-shows-an-ssl-error-comcastxfinity)。请帮助我们在此处报告以解除封锁：https://spa.xfinity.com/check_url_status。如果仍然无法访问该网站，文档在 GitHub 上有镜像： https://github.com/openclaw/openclaw/tree/main/docs ### stable 和 beta 有什么区别 **Stable** 和 **beta** 是 **npm dist-tags**，不是独立的代码分支： - `latest` = stable - `beta` = 用于测试的早期构建我们将构建发布到 **beta**，测试后，一旦构建稳定，就会**将同一版本提升为 `latest`**。这就是为什么 beta 和 stable 可以指向**相同版本**。查看变更： https://github.com/openclaw/openclaw/blob/main/CHANGELOG.md ### 如何安装 beta 版本，beta 和 dev 有什么区别 **Beta** 是 npm dist-tag `beta`（可能与 `latest` 相同）。 **Dev** 是 `main` 的滚动头部（git）；发布时使用 npm dist-tag `dev`。一行命令（macOS/Linux）： ```bash curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash -s -- --beta ``` ```bash curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash -s -- --install-method git ``` Windows 安装程序（PowerShell）： https://openclaw.ai/install.ps1 更多详情：[开发渠道](/install/development-channels)和[安装程序标志](/install/installer)。 ### 安装和新手引导通常需要多长时间大致指南： - **安装：** 2-5 分钟 - **新手引导：** 5-15 分钟，取决于配置多少渠道/模型如果挂起，请参阅[安装程序卡住](/help/faq#installer-stuck-how-do-i-get-more-feedback)和[我卡住了](/help/faq#im-stuck--whats-the-fastest-way-to-get-unstuck)中的快速调试流程。 ### 如何试用最新代码两个选项： 1. **Dev 渠道（git checkout）：** ```bash openclaw update --channel dev ``` 这会切换到 `main` 分支并从源码更新。 2. **可编辑安装（从安装程序网站）：** ```bash curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method git ``` 这会给你一个可编辑的本地仓库，然后通过 git 更新。如果你更喜欢手动克隆，使用： ```bash git clone https://github.com/openclaw/openclaw.git cd openclaw pnpm install pnpm build ``` 文档：[更新](/cli/update)、[开发渠道](/install/development-channels)、 [安装](/install)。 ### 安装程序卡住了？如何获取更多反馈使用**详细输出**重新运行安装程序： ```bash curl -fsSL https://openclaw.ai/install.sh | bash -s -- --verbose ``` 带详细输出的 Beta 安装： ```bash curl -fsSL https://openclaw.ai/install.sh | bash -s -- --beta --verbose ``` 可编辑（git）安装： ```bash curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method git --verbose ``` 更多选项：[安装程序标志](/install/installer)。 ### Windows 安装提示找不到 git 或无法识别 openclaw 两个常见的 Windows 问题： **1) npm error spawn git / git not found** - 安装 **Git for Windows** 并确保 `git` 在你的 PATH 中。 - 关闭并重新打开 PowerShell，然后重新运行安装程序。 **2) openclaw is not recognized（安装后）** - 你的 npm 全局 bin 文件夹不在 PATH 中。 - 检查路径： ```powershell npm config get prefix ``` - 确保 `<prefix>\\bin` 在 PATH 中（在大多数系统上是 `%AppData%\\npm`）。 - 更新 PATH 后关闭并重新打开 PowerShell。如果你想要最顺畅的 Windows 设置，请使用 **WSL2** 而不是原生 Windows。文档：[Windows](/platforms/windows)。 ### 文档没有解答我的问题——如何获得更好的答案使用**可编辑（git）安装**，这样你在本地拥有完整的源码和文档，然后从该文件夹向你的机器人（或 Claude/Codex）提问，这样它可以读取仓库并精确回答。 ```bash curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method git ``` 更多详情：[安装](/install)和[安装程序标志](/install/installer)。 ### 如何在 Linux 上安装 OpenClaw 简短回答：按照 Linux 指南操作，然后运行新手引导向导。 - Linux 快速路径 + 服务安装：[Linux](/platforms/linux)。 - 完整指南：[入门](/start/getting-started)。 - 安装和更新：[安装与更新](/install/updating)。 ### 如何在 VPS 上安装 OpenClaw 任何 Linux VPS 都可以。在服务器上安装，然后使用 SSH/Tailscale 访问 Gateway 网关。指南：[exe.dev](/install/exe-dev)、[Hetzner](/install/hetzner)、[Fly.io](/install/fly)。远程访问：[Gateway 网关远程](/gateway/remote)。 ### 云/VPS 安装指南在哪里我们维护了一个**托管中心**，涵盖常见提供商。选择一个并按指南操作： - [VPS 托管](/vps)（所有提供商汇总） - [Fly.io](/install/fly) - [Hetzner](/install/hetzner) - [exe.dev](/install/exe-dev) 在云端的工作方式：**Gateway 网关运行在服务器上**，你通过控制 UI（或 Tailscale/SSH）从笔记本/手机访问。你的状态 + 工作区位于服务器上，因此将主机视为数据来源并做好备份。你可以将**节点**（Mac/iOS/Android/无头）配对到云端 Gateway 网关，以访问本地屏幕/摄像头/画布或在笔记本上执行命令，同时 Gateway 网关保持在云端。中心：[平台](/platforms)。远程访问：[Gateway 网关远程](/gateway/remote)。节点：[节点](/nodes)、[节点 CLI](/cli/nodes)。 ### 可以让 OpenClaw 自行更新吗简短回答：**可以，但不推荐**。更新流程可能重启 Gateway 网关（这会中断活跃会话），可能需要干净的 git checkout，并且可能提示确认。更安全的做法：作为运维人员从 shell 运行更新。使用 CLI： ```bash openclaw update openclaw update status openclaw update --channel stable|beta|dev openclaw update --tag <dist-tag|version> openclaw update --no-restart ``` 如果必须从智能体自动化： ```bash openclaw update --yes --no-restart openclaw gateway restart ``` 文档：[更新](/cli/update)、[更新指南](/install/updating)。 ### 新手引导向导具体做了什么 `openclaw onboard` 是推荐的设置路径。在**本地模式**下，它引导你完成： - **模型/认证设置**（推荐使用 Anthropic **setup-token** 进行 Claude 订阅，支持 OpenAI Codex OAuth，API 密钥可选，支持 LM Studio 本地模型） - **工作区**位置 + 引导文件 - **Gateway 网关设置**（绑定/端口/认证/tailscale） - **渠道**（WhatsApp、Telegram、Discord、Mattermost（插件）、Signal、iMessage） - **守护进程安装**（macOS 上的 LaunchAgent；Linux/WSL2 上的 systemd 用户单元） - **健康检查**和**Skills**选择如果你配置的模型未知或缺少认证，它还会发出警告。 ### 运行 OpenClaw 需要 Claude 或 OpenAI 订阅吗不需要。你可以使用 **API 密钥**（Anthropic/OpenAI/其他）或**纯本地模型**运行 OpenClaw，这样你的数据留在你的设备上。订阅（Claude Pro/Max 或 OpenAI Codex）是这些提供商的可选认证方式。文档：[Anthropic](/providers/anthropic)、[OpenAI](/providers/openai)、 [本地模型](/gateway/local-models)、[模型](/concepts/models)。 ### 能否使用 Claude Max 订阅而不需要 API 密钥可以。你可以使用 **setup-token** 代替 API 密钥进行认证。这是订阅路径。 Claude Pro/Max 订阅**不包含 API 密钥**，因此这是订阅账户的正确方式。重要提示：你必须向 Anthropic 确认此用法是否符合其订阅政策和条款。如果你想要最明确、受支持的方式，请使用 Anthropic API 密钥。 ### Anthropic setup-token 认证如何工作 `claude setup-token` 通过 Claude Code CLI 生成一个**令牌字符串**（在 Web 控制台中不可用）。你可以在**任何机器**上运行它。在向导中选择 **Anthropic token (paste setup-token)** 或使用 `openclaw models auth paste-token --provider anthropic` 粘贴。令牌作为 **anthropic** 提供商的认证配置文件存储，像 API 密钥一样使用（无自动刷新）。更多详情：[OAuth](/concepts/oauth)。 ### 在哪里获取 Anthropic setup-token 它**不在** Anthropic Console 中。setup-token 由 **Claude Code CLI** 在**任何机器**上生成： ```bash claude setup-token ``` 复制它打印的令牌，然后在向导中选择 **Anthropic token (paste setup-token)**。如果你想在 Gateway 网关主机上运行，使用 `openclaw models auth setup-token --provider anthropic`。如果你在其他地方运行了 `claude setup-token`，在 Gateway 网关主机上使用 `openclaw models auth paste-token --provider anthropic` 粘贴。参阅 [Anthropic](/providers/anthropic)。 ### 是否支持 Claude 订阅认证（Claude Pro/Max）是的——通过 **setup-token**。OpenClaw 不再复用 Claude Code CLI OAuth 令牌；请使用 setup-token 或 Anthropic API 密钥。在任何地方生成令牌并在 Gateway 网关主机上粘贴。参阅 [Anthropic](/providers/anthropic) 和 [OAuth](/concepts/oauth)。注意：Claude 订阅访问受 Anthropic 条款约束。对于生产或多用户工作负载，API 密钥通常是更安全的选择。 ### 为什么我看到 HTTP 429 rate_limit_error（来自 Anthropic）这意味着你当前窗口的 **Anthropic 配额/速率限制**已耗尽。如果你使用 **Claude 订阅**（setup-token 或 Claude Code OAuth），请等待窗口重置或升级你的计划。如果你使用 **Anthropic API 密钥**，请在 Anthropic Console 中检查使用量/计费并根据需要提高限制。提示：设置一个**备用模型**，这样 OpenClaw 在某个提供商被限速时仍能继续回复。参阅[模型](/cli/models)和 [OAuth](/concepts/oauth)。 ### 支持 AWS Bedrock 吗是的——通过 pi-ai 的 **Amazon Bedrock (Converse)** 提供商进行**手动配置**。你必须在 Gateway 网关主机上提供 AWS 凭据/区域，并在模型配置中添加 Bedrock 提供商条目。参阅 [Amazon Bedrock](/bedrock) 和[模型提供商](/providers/models)。如果你更喜欢托管密钥流程，在 Bedrock 前面使用兼容 OpenAI 的代理仍然是有效选项。 ### Codex 认证如何工作 OpenClaw 通过 OAuth（ChatGPT 登录）支持 **OpenAI Code (Codex)**。向导可以运行 OAuth 流程，并在适当时将默认模型设置为 `openai-codex/gpt-5.2`。参阅[模型提供商](/concepts/model-providers)和[向导](/start/wizard)。 ### 是否支持 OpenAI 订阅认证（Codex OAuth）是的。OpenClaw 完全支持 **OpenAI Code (Codex) 订阅 OAuth**。新手引导向导可以为你运行 OAuth 流程。参阅 [OAuth](/concepts/oauth)、[模型提供商](/concepts/model-providers)和[向导](/start/wizard)。 ### 如何设置 Gemini CLI OAuth Gemini CLI 使用**插件认证流程**，而不是 `openclaw.json` 中的 client id 或 secret。步骤： 1. 启用插件：`openclaw plugins enable google-gemini-cli-auth` 2. 登录：`openclaw models auth login --provider google-gemini-cli --set-default` 这会在 Gateway 网关主机上将 OAuth 令牌存储为认证配置文件。详情：[模型提供商](/concepts/model-providers)。 ### 本地模型适合日常聊天吗通常不适合。OpenClaw 需要大上下文 + 强安全性；小显卡会截断且泄漏。如果必须使用，请在本地运行你能运行的**最大** MiniMax M2.1 版本（LM Studio），参阅 [/gateway/local-models](/gateway/local-models)。较小/量化的模型会增加提示注入风险——参阅[安全](/gateway/security)。 ### 如何将托管模型流量限制在特定区域选择区域固定的端点。OpenRouter 为 MiniMax、Kimi 和 GLM 提供美国托管选项；选择美国托管变体以保持数据在区域内。你仍然可以通过使用 `models.mode: "merge"` 在这些旁边列出 Anthropic/OpenAI，这样故障转移保持可用，同时尊重你选择的区域提供商。 ### 我必须购买 Mac Mini 才能安装吗不需要。OpenClaw 运行在 macOS 或 Linux 上（Windows 通过 WSL2）。Mac mini 是可选的——有些人买一台作为常开主机，但小型 VPS、家庭服务器或 Raspberry Pi 级别的设备也可以。你只有在使用 **macOS 专用工具**时才需要 Mac。对于 iMessage，你可以将 Gateway 网关保持在 Linux 上，通过将 `channels.imessage.cliPath` 指向 SSH 包装器在任何 Mac 上运行 `imsg`。如果你需要其他 macOS 专用工具，在 Mac 上运行 Gateway 网关或配对一个 macOS 节点。文档：[iMessage](/channels/imessage)、[节点](/nodes)、[Mac 远程模式](/platforms/mac/remote)。 ### iMessage 支持需要 Mac mini 吗你需要**某台登录了 Messages 的 macOS 设备**。它**不一定**是 Mac mini——任何 Mac 都可以。OpenClaw 的 iMessage 集成在 macOS 上运行（BlueBubbles 或 `imsg`），而 Gateway 网关可以在其他地方运行。常见设置： - 在 Linux/VPS 上运行 Gateway 网关，将 `channels.imessage.cliPath` 指向在 Mac 上运行 `imsg` 的 SSH 包装器。 - 如果你想要最简单的单机设置，在 Mac 上运行所有组件。文档：[iMessage](/channels/imessage)、[BlueBubbles](/channels/bluebubbles)、 [Mac 远程模式](/platforms/mac/remote)。 ### 如果我买了 Mac mini 运行 OpenClaw，能连接到我的 MacBook Pro 吗可以。**Mac mini 可以运行 Gateway 网关**，你的 MacBook Pro 可以作为**节点**（伴随设备）连接。节点不运行 Gateway 网关——它们提供额外功能，如该设备上的屏幕/摄像头/画布和 `system.run`。常见模式： - Gateway 网关在 Mac mini 上（常开）。 - MacBook Pro 运行 macOS 应用或节点主机并配对到 Gateway 网关。 - 使用 `openclaw nodes status` / `openclaw nodes list` 查看它。文档：[节点](/nodes)、[节点 CLI](/cli/nodes)。 ### 可以使用 Bun 吗 Bun **不推荐**。我们观察到运行时 bug，特别是在 WhatsApp 和 Telegram 方面。使用 **Node** 以获得稳定的 Gateway 网关。如果你仍想尝试 Bun，请在没有 WhatsApp/Telegram 的非生产 Gateway 网关上进行。 ### Telegram：allowFrom 填什么 `channels.telegram.allowFrom` 是**人类发送者的 Telegram 用户 ID**（数字，推荐）或 `@username`。它不是机器人用户名。更安全的方式（无需第三方机器人）： - 给你的机器人发私信，然后运行 `openclaw logs --follow` 并读取 `from.id`。官方 Bot API： - 给你的机器人发私信，然后调用 `https://api.telegram.org/bot<bot_token>/getUpdates` 并读取 `message.from.id`。第三方（隐私性较低）： - 给 `@userinfobot` 或 `@getidsbot` 发私信。参阅 [/channels/telegram](/channels/telegram#access-control-dms--groups)。 ### 多人能否使用同一个 WhatsApp 号码配合不同的 OpenClaw 实例可以，通过**多智能体路由**。将每个发送者的 WhatsApp **私信**（peer `kind: "dm"`，发送者 E.164 格式如 `+15551234567`）绑定到不同的 `agentId`，这样每个人获得自己的工作区和会话存储。回复仍然来自**同一个 WhatsApp 账户**，且私信访问控制（`channels.whatsapp.dmPolicy` / `channels.whatsapp.allowFrom`）对每个 WhatsApp 账户是全局的。参阅[多智能体路由](/concepts/multi-agent)和 [WhatsApp](/channels/whatsapp)。 ### 能否同时运行一个“快速聊天”智能体和一个“用 Opus 编程”的智能体可以。使用多智能体路由：为每个智能体设置自己的默认模型，然后将入站路由（提供商账户或特定对等方）绑定到每个智能体。示例配置位于[多智能体路由](/concepts/multi-agent)。另参阅[模型](/concepts/models)和[配置](/gateway/configuration)。 ### Homebrew 在 Linux 上可用吗可以。Homebrew 支持 Linux（Linuxbrew）。快速设置： ```bash /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)" echo 'eval "$(/home/linuxbrew/.linuxbrew/bin/brew shellenv)"' >> ~/.profile eval "$(/home/linuxbrew/.linuxbrew/bin/brew shellenv)" brew install <formula> ``` 如果你通过 systemd 运行 OpenClaw，确保服务 PATH 包含 `/home/linuxbrew/.linuxbrew/bin`（或你的 brew 前缀），以便 `brew` 安装的工具在非登录 shell 中可解析。最近的构建还会在 Linux systemd 服务上自动添加常见的用户 bin 目录（例如 `~/.local/bin`、`~/.npm-global/bin`、`~/.local/share/pnpm`、`~/.bun/bin`），并在设置时尊重 `PNPM_HOME`、`NPM_CONFIG_PREFIX`、`BUN_INSTALL`、`VOLTA_HOME`、`ASDF_DATA_DIR`、`NVM_DIR` 和 `FNM_DIR`。 ### 可编辑（git）安装和 npm 安装有什么区别 - **可编辑（git）安装：** 完整源码 checkout，可编辑，最适合贡献者。你在本地运行构建并可以修补代码/文档。 - **npm 安装：** 全局 CLI 安装，无仓库，最适合“直接运行”。更新来自 npm dist-tags。文档：[入门](/start/getting-started)、[更新](/install/updating)。 ### 之后可以在 npm 和 git 安装之间切换吗可以。安装另一种方式，然后运行 Doctor 使 Gateway 网关服务指向新的入口点。这**不会删除你的数据**——它只改变 OpenClaw 代码的安装位置。你的状态（`~/.openclaw`）和工作区（`~/.openclaw/workspace`）保持不变。从 npm → git： ```bash git clone https://github.com/openclaw/openclaw.git cd openclaw pnpm install pnpm build openclaw doctor openclaw gateway restart ``` 从 git → npm： ```bash npm install -g openclaw@latest openclaw doctor openclaw gateway restart ``` Doctor 会检测 Gateway 网关服务入口点不匹配，并提供重写服务配置以匹配当前安装的选项（在自动化中使用 `--repair`）。备份提示：参阅[备份策略](/help/faq#whats-the-recommended-backup-strategy)。 ### 应该在笔记本电脑还是 VPS 上运行 Gateway 网关简短回答：**如果你想要 24/7 可靠性，使用 VPS**。如果你想要最低摩擦且能接受休眠/重启，在本地运行。 **笔记本（本地 Gateway 网关）** - **优点：** 无服务器成本，直接访问本地文件，实时浏览器窗口。 - **缺点：** 休眠/网络中断 = 断连，操作系统更新/重启会中断，必须保持唤醒。 **VPS / 云** - **优点：** 常开，网络稳定，无笔记本休眠问题，更容易保持运行。 - **缺点：** 通常无头运行（使用截图），仅远程文件访问，更新需要 SSH。 **OpenClaw 特定说明：** WhatsApp/Telegram/Slack/Mattermost（插件）/Discord 在 VPS 上都能正常工作。唯一的真正权衡是**无头浏览器**与可见窗口。参阅[浏览器](/tools/browser)。 **推荐默认值：** 如果之前遇到过 Gateway 网关断连，使用 VPS。当你正在积极使用 Mac 并且需要本地文件访问或可见浏览器的 UI 自动化时，本地运行很好。 ### 在专用机器上运行 OpenClaw 有多重要不是必需的，但**推荐用于可靠性和隔离**。 - **专用主机（VPS/Mac mini/Pi）：** 常开，更少的休眠/重启中断，更干净的权限，更容易保持运行。 - **共享的笔记本/台式机：** 完全适合测试和活跃使用，但当机器休眠或更新时预期会有暂停。如果你想要两全其美，将 Gateway 网关保持在专用主机上，并将笔记本配对为**节点**以获取本地屏幕/摄像头/执行工具。参阅[节点](/nodes)。安全指南请阅读[安全](/gateway/security)。 ### VPS 的最低要求和推荐操作系统是什么 OpenClaw 是轻量级的。对于基本的 Gateway 网关 + 一个聊天渠道： - **绝对最低：** 1 vCPU，1GB RAM，约 500MB 磁盘。 - **推荐：** 1-2 vCPU，2GB RAM 或更多以留有余量（日志、媒体、多渠道）。节点工具和浏览器自动化可能消耗较多资源。操作系统：使用 **Ubuntu LTS**（或任何现代 Debian/Ubuntu）。Linux 安装路径在那里测试得最充分。文档：[Linux](/platforms/linux)、[VPS 托管](/vps)。 ### 可以在虚拟机中运行 OpenClaw 吗？有什么要求可以。将虚拟机视为与 VPS 相同：它需要常开、可达，并有足够的 RAM 用于 Gateway 网关和你启用的任何渠道。基准指南： - **绝对最低：** 1 vCPU，1GB RAM。 - **推荐：** 2GB RAM 或更多，如果你运行多个渠道、浏览器自动化或媒体工具。 - **操作系统：** Ubuntu LTS 或其他现代 Debian/Ubuntu。如果你使用 Windows，**WSL2 是最简单的虚拟机式设置**，具有最佳的工具兼容性。参阅 [Windows](/platforms/windows)、[VPS 托管](/vps)。如果你在虚拟机中运行 macOS，参阅 [macOS VM](/install/macos-vm)。 ## 什么是 OpenClaw？ ### 用一段话描述 OpenClaw OpenClaw 是一个运行在你自己设备上的个人 AI 助手。它在你已经使用的消息平台上回复（WhatsApp、Telegram、Slack、Mattermost（插件）、Discord、Google Chat、Signal、iMessage、WebChat），还可以在支持的平台上进行语音和实时 Canvas。**Gateway 网关** 是常开的控制平面；助手是产品。 ### 价值主张是什么 OpenClaw 不是“只是一个 Claude 包装器”。它是一个**本地优先的控制平面**，让你在**自己的硬件**上运行强大的助手，可从你已经使用的聊天应用访问，具有有状态会话、记忆和工具——无需将工作流程的控制权交给托管 SaaS。亮点： - **你的设备，你的数据：** 在任何你想要的地方运行 Gateway 网关（Mac、Linux、VPS），并将工作区 + 会话历史保持在本地。 - **真实渠道，而非 Web 沙箱：** WhatsApp/Telegram/Slack/Discord/Signal/iMessage/等，加上支持平台上的移动语音和 Canvas。 - **模型无关：** 使用 Anthropic、OpenAI、MiniMax、OpenRouter 等，支持按智能体路由和故障转移。 - **纯本地选项：** 运行本地模型，让**所有数据都保留在你的设备上**。 - **多智能体路由：** 按渠道、账户或任务分配不同的智能体，每个都有自己的工作区和默认值。 - **开源且可编辑：** 无供应商锁定地检查、扩展和自托管。文档：[Gateway 网关](/gateway)、[渠道](/channels)、[多智能体](/concepts/multi-agent)、 [记忆](/concepts/memory)。 ### 刚设置好，应该先做什么好的入门项目： - 建一个网站（WordPress、Shopify 或简单的静态站点）。 - 做一个移动应用原型（大纲、界面、API 计划）。 - 整理文件和文件夹（清理、命名、打标签）。 - 连接 Gmail 并自动化摘要或跟进。它可以处理大型任务，但最好将其拆分为多个阶段，并使用子智能体进行并行工作。 ### OpenClaw 日常最常用的五个场景是什么日常收益通常包括： - **个人简报：** 收件箱、日历和你关心的新闻摘要。 - **研究和起草：** 快速研究、摘要以及邮件或文档的初稿。 - **提醒和跟进：** 定时任务或心跳驱动的提醒和检查清单。 - **浏览器自动化：** 填写表单、收集数据和重复性网页任务。 - **跨设备协调：** 从手机发送任务，让 Gateway 网关在服务器上运行，然后在聊天中获取结果。 ### OpenClaw 能否帮助 SaaS 进行获客、外联、广告和博客可以用于**调研、筛选和起草**。它可以扫描网站、建立候选名单、总结潜在客户，并撰写外联或广告文案草稿。对于**外联或广告投放**，请保持人工审核。避免垃圾邮件，遵守当地法律和平台政策，在发送之前审查所有内容。最安全的模式是让 OpenClaw 起草，由你批准。文档：[安全](/gateway/security)。 ### 相比 Claude Code，在 Web 开发方面有什么优势 OpenClaw 是一个**个人助手**和协调层，不是 IDE 替代品。使用 Claude Code 或 Codex 在仓库中进行最快的直接编码循环。当你需要持久记忆、跨设备访问和工具编排时，使用 OpenClaw。优势： - 跨会话的**持久记忆 + 工作区** - **多平台访问**（WhatsApp、Telegram、TUI、WebChat） - **工具编排**（浏览器、文件、调度、钩子） - **常开 Gateway 网关**（在 VPS 上运行，从任何地方交互） - 用于本地浏览器/屏幕/摄像头/执行的**节点** 展示：https://openclaw.ai/showcase ## Skills 与自动化 ### 如何自定义 Skills 而不弄脏仓库使用托管覆盖而不是编辑仓库副本。将你的更改放在 `~/.openclaw/skills/<name>/SKILL.md`（或通过 `~/.openclaw/openclaw.json` 中的 `skills.load.extraDirs` 添加文件夹）。优先级是 `<workspace>/skills` > `~/.openclaw/skills` > 内置，所以托管覆盖优先生效而不会修改 git。只有值得上游合并的编辑才应该放在仓库中并作为 PR 提交。 ### 可以从自定义文件夹加载 Skills 吗可以。通过 `~/.openclaw/openclaw.json` 中的 `skills.load.extraDirs` 添加额外目录（最低优先级）。默认优先级保持不变：`<workspace>/skills` → `~/.openclaw/skills` → 内置 → `skills.load.extraDirs`。`clawhub` 默认安装到 `./skills`，OpenClaw 将其视为 `<workspace>/skills`。 ### 如何为不同任务使用不同模型目前支持的模式有： - **定时任务**：隔离的任务可以为每个任务设置 `model` 覆盖。 - **子智能体**：将任务路由到具有不同默认模型的独立智能体。 - **按需切换**：使用 `/model` 随时切换当前会话模型。参阅[定时任务](/automation/cron-jobs)、[多智能体路由](/concepts/multi-agent)和[斜杠命令](/tools/slash-commands)。 ### 机器人在执行繁重工作时卡住了，如何卸载任务使用**子智能体**处理长时间或并行任务。子智能体在自己的会话中运行，返回摘要，并保持你的主聊天响应。要求你的机器人“为这个任务生成一个子智能体”或使用 `/subagents`。在聊天中使用 `/status` 查看 Gateway 网关当前正在做什么（以及是否忙碌）。令牌提示：长任务和子智能体都消耗令牌。如果关注成本，通过 `agents.defaults.subagents.model` 为子智能体设置更便宜的模型。文档：[子智能体](/tools/subagents)。 ### 定时任务或提醒没有触发，应该检查什么定时任务在 Gateway 网关进程内运行。如果 Gateway 网关没有持续运行，计划任务将不会运行。检查清单： - 确认 cron 已启用（`cron.enabled`）且未设置 `OPENCLAW_SKIP_CRON`。 - 检查 Gateway 网关是否 24/7 运行（无休眠/重启）。 - 验证任务的时区设置（`--tz` 与主机时区）。调试： ```bash openclaw cron run <jobId> --force openclaw cron runs --id <jobId> --limit 50 ``` 文档：[定时任务](/automation/cron-jobs)、[定时任务 vs 心跳](/automation/cron-vs-heartbeat)。 ### 如何在 Linux 上安装 Skills 使用 **ClawHub**（CLI）或将 Skills 放入你的工作区。macOS Skills UI 在 Linux 上不可用。浏览 Skills：https://clawhub.com。安装 ClawHub CLI（选择一个包管理器）： ```bash npm i -g clawhub ``` ```bash pnpm add -g clawhub ``` ### OpenClaw 能否按计划或在后台持续运行任务可以。使用 Gateway 网关调度器： - **定时任务**用于计划或重复任务（跨重启持久化）。 - **心跳**用于“主会话”定期检查。 - **隔离任务**用于自主智能体发布摘要或投递到聊天。文档：[定时任务](/automation/cron-jobs)、[定时任务 vs 心跳](/automation/cron-vs-heartbeat)、 [心跳](/gateway/heartbeat)。 **能否从 Linux 运行仅限 Apple/macOS 的 Skills** 不能直接运行。macOS Skills 受 `metadata.openclaw.os` 和所需二进制文件限制，Skills 只有在 **Gateway 网关主机**上符合条件时才会出现在系统提示中。在 Linux 上，`darwin` 专用 Skills（如 `apple-notes`、`apple-reminders`、`things-mac`）不会加载，除非你覆盖限制。你有三种支持的模式： **方案 A - 在 Mac 上运行 Gateway 网关（最简单）。** 在 macOS 二进制文件所在的地方运行 Gateway 网关，然后从 Linux 通过[远程模式](#how-do-i-run-openclaw-in-remote-mode-client-connects-to-a-gateway-elsewhere)或 Tailscale 连接。Skills 正常加载，因为 Gateway 网关主机是 macOS。 **方案 B - 使用 macOS 节点（无需 SSH）。** 在 Linux 上运行 Gateway 网关，配对一个 macOS 节点（菜单栏应用），并在 Mac 上将**节点运行命令**设置为“始终询问”或“始终允许”。当所需二进制文件存在于节点上时，OpenClaw 可以将 macOS 专用 Skills 视为符合条件。智能体通过 `nodes` 工具运行这些 Skills。如果你选择“始终询问”，在提示中批准“始终允许”会将该命令添加到允许列表。 **方案 C - 通过 SSH 代理 macOS 二进制文件（高级）。** 保持 Gateway 网关在 Linux 上，但使所需的 CLI 二进制文件解析为在 Mac 上运行的 SSH 包装器。然后覆盖 Skills 以允许 Linux 使其保持符合条件。 1. 为二进制文件创建 SSH 包装器（示例：`imsg`）： ```bash #!/usr/bin/env bash set -euo pipefail exec ssh -T user@mac-host /opt/homebrew/bin/imsg "$@" ``` 2. 将包装器放在 Linux 主机的 `PATH` 上（例如 `~/bin/imsg`）。 3. 覆盖 Skills 元数据（工作区或 `~/.openclaw/skills`）以允许 Linux： ```markdown --- name: imsg description: iMessage/SMS CLI for listing chats, history, watch, and sending. metadata: { "openclaw": { "os": ["darwin", "linux"], "requires": { "bins": ["imsg"] } } } --- ``` 4. 开始新会话以刷新 Skills 快照。对于 iMessage，你也可以将 `channels.imessage.cliPath` 指向 SSH 包装器（OpenClaw 只需要 stdio）。参阅 [iMessage](/channels/imessage)。 ### 有 Notion 或 HeyGen 集成吗目前没有内置集成。选项： - **自定义 Skills / 插件：** 最适合可靠的 API 访问（Notion/HeyGen 都有 API）。 - **浏览器自动化：** 无需编码但更慢且更脆弱。如果你想按客户保留上下文（代理工作流），一个简单的模式是： - 每个客户一个 Notion 页面（上下文 + 偏好 + 当前工作）。 - 在会话开始时要求智能体获取该页面。如果你想要原生集成，请提交功能请求或构建一个针对这些 API 的 Skills。安装 Skills： ```bash clawhub install <skill-slug> clawhub update --all ``` ClawHub 安装到当前目录下的 `./skills`（或回退到你配置的 OpenClaw 工作区）；OpenClaw 在下一个会话中将其视为 `<workspace>/skills`。对于跨智能体共享的 Skills，将它们放在 `~/.openclaw/skills/<name>/SKILL.md`。某些 Skills 期望通过 Homebrew 安装二进制文件；在 Linux 上意味着 Linuxbrew（参阅上面的 Homebrew Linux 常见问题条目）。参阅[Skills](/tools/skills)和 [ClawHub](/tools/clawhub)。 ### 如何安装用于浏览器接管的 Chrome 扩展使用内置安装程序，然后在 Chrome 中加载未打包的扩展： ```bash openclaw browser extension install openclaw browser extension path ``` 然后 Chrome → `chrome://extensions` → 启用“开发者模式” → “加载已解压的扩展程序” → 选择该文件夹。完整指南（包括远程 Gateway 网关 + 安全注意事项）：[Chrome 扩展](/tools/chrome-extension) 如果 Gateway 网关运行在与 Chrome 同一台机器上（默认设置），你通常**不需要**额外配置。如果 Gateway 网关运行在其他地方，在运行浏览器的机器上运行一个节点主机，以便 Gateway 网关可以代理浏览器操作。你仍然需要在要控制的标签页上点击扩展按钮（它不会自动附加）。 ## 沙箱与记忆 ### 有专门的沙箱文档吗有。参阅[沙箱](/gateway/sandboxing)。对于 Docker 特定设置（完整 Gateway 网关在 Docker 中或沙箱镜像），参阅 [Docker](/install/docker)。 **能否让私信保持私密，但群组用一个智能体公开沙箱隔离** 可以——如果你的私密流量是**私信**而公开流量是**群组**。使用 `agents.defaults.sandbox.mode: "non-main"`，这样群组/频道会话（非主键）在 Docker 中运行，而主私信会话保持在主机上。然后通过 `tools.sandbox.tools` 限制沙箱会话中可用的工具。设置指南 + 示例配置：[群组：个人私信 + 公开群组](/concepts/groups#pattern-personal-dms-public-groups-single-agent) 关键配置参考：[Gateway 网关配置](/gateway/configuration#agentsdefaultssandbox) ### 如何将主机文件夹绑定到沙箱中将 `agents.defaults.sandbox.docker.binds` 设置为 `["host:path:mode"]`（例如 `"/home/user/src:/src:ro"`）。全局 + 按智能体的绑定会合并；当 `scope: "shared"` 时按智能体的绑定会被忽略。对于敏感内容使用 `:ro`，并记住绑定会绕过沙箱文件系统隔离。参阅[沙箱](/gateway/sandboxing#custom-bind-mounts)和[沙箱 vs 工具策略 vs 提权](/gateway/sandbox-vs-tool-policy-vs-elevated#bind-mounts-security-quick-check)了解示例和安全注意事项。 ### 记忆是如何工作的 OpenClaw 记忆就是智能体工作区中的 Markdown 文件： - 每日笔记在 `memory/YYYY-MM-DD.md` - 精选的长期笔记在 `MEMORY.md`（仅限主/私密会话） OpenClaw 还会运行**静默的预压缩记忆刷新**，以提醒模型在自动压缩之前写入持久笔记。这只在工作区可写时运行（只读沙箱会跳过）。参阅[记忆](/concepts/memory)。 ### 记忆总是遗忘，如何让它持久保存要求机器人**将事实写入记忆**。长期笔记属于 `MEMORY.md`，短期上下文放入 `memory/YYYY-MM-DD.md`。这仍然是我们正在改进的领域。提醒模型存储记忆会有帮助；它会知道如何操作。如果它持续遗忘，验证 Gateway 网关每次运行时是否使用相同的工作区。文档：[记忆](/concepts/memory)、[智能体工作区](/concepts/agent-workspace)。 ### 语义记忆搜索需要 OpenAI API 密钥吗只有在使用 **OpenAI embeddings** 时才需要。Codex OAuth 覆盖 chat/completions 但**不**授予 embeddings 访问权限，因此**使用 Codex 登录（OAuth 或 Codex CLI 登录）**对语义记忆搜索没有帮助。OpenAI embeddings 仍然需要真正的 API 密钥（`OPENAI_API_KEY` 或 `models.providers.openai.apiKey`）。如果你没有明确设置提供商，OpenClaw 会在能解析 API 密钥（认证配置文件、`models.providers.*.apiKey` 或环境变量）时自动选择提供商。如果 OpenAI 密钥可解析则优先使用 OpenAI，否则如果 Gemini 密钥可解析则使用 Gemini。如果两个密钥都不可用，记忆搜索保持禁用直到你配置它。如果你配置了本地模型路径且存在，OpenClaw 优先使用 `local`。如果你更想保持本地运行，设置 `memorySearch.provider = "local"`（可选 `memorySearch.fallback = "none"`）。如果你想使用 Gemini embeddings，设置 `memorySearch.provider = "gemini"` 并提供 `GEMINI_API_KEY`（或 `memorySearch.remote.apiKey`）。我们支持 **OpenAI、Gemini 或本地** embedding 模型——参阅[记忆](/concepts/memory)了解设置详情。 ### 记忆是否永久保留？有什么限制记忆文件保存在磁盘上，持久存在直到你删除它们。限制是你的存储空间，而不是模型。**会话上下文**仍然受模型上下文窗口限制，所以长对话可能会压缩或截断。这就是记忆搜索存在的原因——它只将相关部分拉回上下文。文档：[记忆](/concepts/memory)、[上下文](/concepts/context)。 ## 磁盘上的文件位置 ### OpenClaw 使用的所有数据都保存在本地吗不是——**OpenClaw 的状态是本地的**，但**外部服务仍然会看到你发送给它们的内容**。 - **默认本地：** 会话、记忆文件、配置和工作区位于 Gateway 网关主机上（`~/.openclaw` + 你的工作区目录）。 - **必然远程：** 你发送给模型提供商（Anthropic/OpenAI/等）的消息会发送到它们的 API，聊天平台（WhatsApp/Telegram/Slack/等）在它们的服务器上存储消息数据。 - **你控制范围：** 使用本地模型可以将提示保留在你的机器上，但渠道流量仍然通过渠道的服务器。相关：[智能体工作区](/concepts/agent-workspace)、[记忆](/concepts/memory)。 ### OpenClaw 将数据存储在哪里所有内容位于 `$OPENCLAW_STATE_DIR`（默认：`~/.openclaw`）下： | 路径 | 用途 | | --------------------------------------------------------------- | ---------------------------------------------------- | | `$OPENCLAW_STATE_DIR/openclaw.json` | 主配置（JSON5） | | `$OPENCLAW_STATE_DIR/credentials/oauth.json` | 旧版 OAuth 导入（首次使用时复制到认证配置文件） | | `$OPENCLAW_STATE_DIR/agents/<agentId>/agent/auth-profiles.json` | 认证配置文件（OAuth + API 密钥） | | `$OPENCLAW_STATE_DIR/agents/<agentId>/agent/auth.json` | 运行时认证缓存（自动管理） | | `$OPENCLAW_STATE_DIR/credentials/` | 提供商状态（例如 `whatsapp/<accountId>/creds.json`） | | `$OPENCLAW_STATE_DIR/agents/` | 按智能体的状态（agentDir + 会话） | | `$OPENCLAW_STATE_DIR/agents/<agentId>/sessions/` | 对话历史和状态（按智能体） | | `$OPENCLAW_STATE_DIR/agents/<agentId>/sessions/sessions.json` | 会话元数据（按智能体） | 旧版单智能体路径：`~/.openclaw/agent/*`（通过 `openclaw doctor` 迁移）。你的**工作区**（AGENTS.md、记忆文件、Skills 等）是独立的，通过 `agents.defaults.workspace` 配置（默认：`~/.openclaw/workspace`）。 ### AGENTS.md / SOUL.md / USER.md / MEMORY.md 应该放在哪里这些文件位于**智能体工作区**中，而不是 `~/.openclaw`。 - **工作区（按智能体）**：`AGENTS.md`、`SOUL.md`、`IDENTITY.md`、`USER.md`、 `MEMORY.md`（或 `memory.md`）、`memory/YYYY-MM-DD.md`、可选的 `HEARTBEAT.md`。 - **状态目录（`~/.openclaw`）**：配置、凭据、认证配置文件、会话、日志和共享 Skills（`~/.openclaw/skills`）。默认工作区是 `~/.openclaw/workspace`，可通过以下方式配置： ```json5 { agents: { defaults: { workspace: "~/.openclaw/workspace" } }, } ``` 如果机器人在重启后“忘记”了内容，确认 Gateway 网关每次启动时都使用相同的工作区（记住：远程模式使用 **Gateway 网关主机的**工作区，而不是你本地笔记本的）。提示：如果你想要一个持久的行为或偏好，要求机器人**将其写入 AGENTS.md 或 MEMORY.md**，而不是依赖聊天历史。参阅[智能体工作区](/concepts/agent-workspace)和[记忆](/concepts/memory)。 ### 推荐的备份策略是什么将你的**智能体工作区**放入一个**私有** git 仓库，并备份到某个私有位置（例如 GitHub 私有仓库）。这会捕获记忆 + AGENTS/SOUL/USER 文件，让你以后可以恢复助手的“思维”。 **不要**提交 `~/.openclaw` 下的任何内容（凭据、会话、令牌）。如果你需要完整恢复，将工作区和状态目录分别备份（参阅上面的迁移问题）。文档：[智能体工作区](/concepts/agent-workspace)。 ### 如何完全卸载 OpenClaw 参阅专门指南：[卸载](/install/uninstall)。 ### 智能体可以在工作区外工作吗可以。工作区是**默认 cwd** 和记忆锚点，不是硬沙箱。相对路径在工作区内解析，但绝对路径可以访问其他主机位置，除非启用了沙箱。如果你需要隔离，使用 [`agents.defaults.sandbox`](/gateway/sandboxing) 或按智能体的沙箱设置。如果你希望某个仓库作为默认工作目录，将该智能体的 `workspace` 指向仓库根目录。OpenClaw 仓库只是源代码；除非你有意要让智能体在其中工作，否则保持工作区独立。示例（仓库作为默认 cwd）： ```json5 { agents: { defaults: { workspace: "~/Projects/my-repo", }, }, } ``` ### 我处于远程模式——会话存储在哪里会话状态归 **Gateway 网关主机**所有。如果你处于远程模式，你关心的会话存储在远程机器上，而不是你的本地笔记本上。参阅[会话管理](/concepts/session)。 ## 配置基础 ### 配置文件是什么格式？在哪里 OpenClaw 从 `$OPENCLAW_CONFIG_PATH`（默认：`~/.openclaw/openclaw.json`）读取可选的 **JSON5** 配置： ``` $OPENCLAW_CONFIG_PATH ``` 如果文件不存在，使用安全的默认值（包括默认工作区 `~/.openclaw/workspace`）。 ### 我设置了 gateway.bind: "lan"（或 "tailnet"），现在什么都监听不了 / UI 显示未授权非 local loopback 绑定**需要认证**。配置 `gateway.auth.mode` + `gateway.auth.token`（或使用 `OPENCLAW_GATEWAY_TOKEN`）。 ```json5 { gateway: { bind: "lan", auth: { mode: "token", token: "replace-me", }, }, } ``` 注意： - `gateway.remote.token` 仅用于**远程 CLI 调用**；它不启用本地 Gateway 网关认证。 - 控制 UI 通过 `connect.params.auth.token`（存储在应用/UI 设置中）进行认证。避免将令牌放在 URL 中。 ### 为什么现在在 localhost 也需要令牌向导默认生成 Gateway 网关令牌（即使在 local loopback 上），因此**本地 WS 客户端必须认证**。这阻止了其他本地进程调用 Gateway 网关。在控制 UI 设置（或你的客户端配置）中粘贴令牌以连接。如果你**确实**想要开放 local loopback，从配置中移除 `gateway.auth`。Doctor 可以随时为你生成令牌：`openclaw doctor --generate-gateway-token`。 ### 更改配置后需要重启吗 Gateway 网关监视配置文件并支持热重载： - `gateway.reload.mode: "hybrid"`（默认）：安全更改热应用，关键更改重启 - 也支持 `hot`、`restart`、`off` ### 如何启用网络搜索（和网页抓取） `web_fetch` 无需 API 密钥即可工作。`web_search` 需要 Brave Search API 密钥。**推荐：** 运行 `openclaw configure --section web` 将其存储在 `tools.web.search.apiKey` 中。环境变量替代方案：为 Gateway 网关进程设置 `BRAVE_API_KEY`。 ```json5 { tools: { web: { search: { enabled: true, apiKey: "BRAVE_API_KEY_HERE", maxResults: 5, }, fetch: { enabled: true, }, }, }, } ``` 注意： - 如果你使用允许列表，添加 `web_search`/`web_fetch` 或 `group:web`。 - `web_fetch` 默认启用（除非明确禁用）。 - 守护进程从 `~/.openclaw/.env`（或服务环境）读取环境变量。文档：[Web 工具](/tools/web)。 ### config.apply 清空了我的配置，如何恢复和避免 `config.apply` 替换**整个配置**。如果你发送部分对象，其他所有内容都会被移除。恢复： - 从备份恢复（git 或复制的 `~/.openclaw/openclaw.json`）。 - 如果没有备份，重新运行 `openclaw doctor` 并重新配置渠道/模型。 - 如果这是意外情况，提交 bug 并附上你最后已知的配置或任何备份。 - 本地编码智能体通常可以从日志或历史中重建工作配置。避免方法： - 对小更改使用 `openclaw config set`。 - 对交互式编辑使用 `openclaw configure`。文档：[Config](/cli/config)、[Configure](/cli/configure)、[Doctor](/gateway/doctor)。 ### 如何运行一个中心 Gateway 网关配合跨设备的专用工作节点常见模式是**一个 Gateway 网关**（例如 Raspberry Pi）加上**节点**和**智能体**： - **Gateway 网关（中心）：** 拥有渠道（Signal/WhatsApp）、路由和会话。 - **节点（设备）：** Mac/iOS/Android 作为外围设备连接，暴露本地工具（`system.run`、`canvas`、`camera`）。 - **智能体（工作者）：** 用于特殊角色的独立大脑/工作区（例如“Hetzner 运维”、“个人数据”）。 - **子智能体：** 需要并行处理时从主智能体生成后台工作。 - **TUI：** 连接到 Gateway 网关并切换智能体/会话。文档：[节点](/nodes)、[远程访问](/gateway/remote)、[多智能体路由](/concepts/multi-agent)、[子智能体](/tools/subagents)、[TUI](/tui)。 ### OpenClaw 浏览器可以无头运行吗可以。这是一个配置选项： ```json5 { browser: { headless: true }, agents: { defaults: { sandbox: { browser: { headless: true } }, }, }, } ``` 默认为 `false`（有头）。无头模式在某些网站上更容易触发反机器人检测。参阅[浏览器](/tools/browser)。无头模式使用**相同的 Chromium 引擎**，适用于大多数自动化（表单、点击、抓取、登录）。主要区别： - 没有可见的浏览器窗口（如果需要视觉效果使用截图）。 - 某些网站在无头模式下对自动化更严格（验证码、反机器人）。例如，X/Twitter 经常阻止无头会话。 ### 如何使用 Brave 进行浏览器控制将 `browser.executablePath` 设置为你的 Brave 二进制文件（或任何基于 Chromium 的浏览器）并重启 Gateway 网关。参阅[浏览器](/tools/browser#use-brave-or-another-chromium-based-browser)中的完整配置示例。 ## 远程 Gateway 网关与节点 ### 命令如何在 Telegram、Gateway 网关和节点之间传播 Telegram 消息由 **Gateway 网关** 处理。Gateway 网关运行智能体，只有在需要节点工具时才通过 **Gateway 网关 WebSocket** 调用节点： Telegram → Gateway 网关 → 智能体 → `node.*` → 节点 → Gateway 网关 → Telegram 节点不会看到入站提供商流量；它们只接收节点 RPC 调用。 ### 如果 Gateway 网关托管在远程，我的智能体如何访问我的电脑简短回答：**将你的电脑配对为节点**。Gateway 网关运行在其他地方，但它可以通过 Gateway 网关 WebSocket 在你的本地机器上调用 `node.*` 工具（屏幕、摄像头、系统）。典型设置： 1. 在常开主机（VPS/家庭服务器）上运行 Gateway 网关。 2. 将 Gateway 网关主机和你的电脑放在同一个 tailnet 上。 3. 确保 Gateway 网关 WS 可达（tailnet 绑定或 SSH 隧道）。 4. 在本地打开 macOS 应用并以**远程 over SSH** 模式连接（或直接 tailnet），使其可以注册为节点。 5. 在 Gateway 网关上批准节点： ```bash openclaw nodes pending openclaw nodes approve <requestId> ``` 不需要单独的 TCP 桥接；节点通过 Gateway 网关 WebSocket 连接。安全提醒：配对 macOS 节点允许在该机器上执行 `system.run`。只配对你信任的设备，并查阅[安全](/gateway/security)。文档：[节点](/nodes)、[Gateway 网关协议](/gateway/protocol)、[macOS 远程模式](/platforms/mac/remote)、[安全](/gateway/security)。 ### Tailscale 已连接但收不到回复，怎么办检查基础项： - Gateway 网关正在运行：`openclaw gateway status` - Gateway 网关健康：`openclaw status` - 渠道健康：`openclaw channels status` 然后验证认证和路由： - 如果你使用 Tailscale Serve，确保 `gateway.auth.allowTailscale` 设置正确。 - 如果你通过 SSH 隧道连接，确认本地隧道已启动并指向正确端口。 - 确认你的允许列表（私信或群组）包含你的账户。文档：[Tailscale](/gateway/tailscale)、[远程访问](/gateway/remote)、[渠道](/channels)。 ### 两个 OpenClaw 实例（本地 + VPS）可以互相通信吗可以。没有内置的“机器人对机器人”桥接，但你可以通过几种可靠的方式实现： **最简单：** 使用两个机器人都能访问的普通聊天渠道（Telegram/Slack/WhatsApp）。让机器人 A 给机器人 B 发消息，然后让机器人 B 正常回复。 **CLI 桥接（通用）：** 运行一个脚本调用另一个 Gateway 网关，使用 `openclaw agent --message ... --deliver`，定向到另一个机器人监听的聊天。如果一个机器人在远程 VPS 上，通过 SSH/Tailscale 将你的 CLI 指向该远程 Gateway 网关（参阅[远程访问](/gateway/remote)）。示例模式（从能到达目标 Gateway 网关的机器上运行）： ```bash openclaw agent --message "Hello from local bot" --deliver --channel telegram --reply-to <chat-id> ``` 提示：添加护栏防止两个机器人无限循环（仅提及、渠道允许列表或“不回复机器人消息”规则）。文档：[远程访问](/gateway/remote)、[Agent CLI](/cli/agent)