常见问题：首次运行设置

使用能够查看你的机器的本地 AI 智能体。大多数“遇到问题”的情况都是远程助手无法检查的 本地配置或环境问题，因此这种方式比在 Discord 中提问更有效。

• Claude Code：https://www.anthropic.com/claude-code/
• OpenAI Codex：https://openai.com/codex/

通过可修改的（git）安装方式向智能体提供完整的源代码检出，使其能够读取 代码和文档，并针对你所运行的确切版本进行分析：

curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash -s -- --install-method git

让智能体逐步规划并监督修复过程，然后仅执行必要的命令——较小的差异更容易审计。

寻求帮助时（在 Discord 或 GitHub issue 中），请分享以下输出：

发现了真正的 bug 或修复方案？提交 issue 或 PR： Issues / Pull requests。

快速调试流程：出现故障时的最初六十秒。 安装文档：安装、安装程序标志、更新。

在任务模式下，截止时间戳仅在一次真正的 Heartbeat 运行完成后才会向前推进。 被跳过的运行不会将任务标记为已完成。

文档：Heartbeat、自动化。

curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bashopenclaw onboard --install-daemon

从源代码安装（贡献者/开发人员）：

git clone https://github.com/openclaw/openclaw.gitcd openclawpnpm installpnpm buildpnpm ui:buildopenclaw onboard

尚未全局安装？请改为运行 pnpm openclaw onboard。如果缺少 Control UI 资源， 新手引导会尝试自行构建，并在失败时回退到 pnpm ui:build。

设置完成后，新手引导会立即在浏览器中打开一个干净的（不含令牌的）仪表板 URL， 并在摘要中输出该链接。请保持该标签页打开；如果浏览器未启动， 请在同一台机器上复制并粘贴输出的 URL。

Localhost（同一台机器）：

• 打开 http://127.0.0.1:18789/。
• 如果系统要求使用共享密钥进行身份验证，请将已配置的令牌或密码粘贴到 Control UI 设置中。
• 令牌来源：gateway.auth.token（或 OPENCLAW_GATEWAY_TOKEN）。
• 密码来源：gateway.auth.password（或 OPENCLAW_GATEWAY_PASSWORD）。
• 尚未配置共享密钥？运行 openclaw doctor --generate-gateway-token（或 openclaw doctor --fix --generate-gateway-token）。

不在 localhost 上：

• Tailscale Serve（推荐）：保持绑定到 local loopback，运行 openclaw gateway --tailscale serve，然后打开 https://<magicdns>/。使用 gateway.auth.allowTailscale: true 时，身份标头可满足 Control UI/WebSocket 身份验证要求（无需粘贴共享密钥，前提是 Gateway 网关主机可信）；HTTP API 仍需要共享密钥身份验证，除非你有意使用私有入口 none 或可信代理 HTTP 身份验证。 来自同一客户端的并发错误身份验证 Serve 尝试会先被串行处理，再由身份验证失败限制器记录，因此第二次错误重试可能已经显示 retry later。
• Tailnet 绑定：运行 openclaw gateway --bind tailnet --token "<token>"（或配置密码身份验证），打开 http://<tailscale-ip>:18789/，然后在仪表板设置中粘贴匹配的共享密钥。
• 感知身份的反向代理：将 Gateway 网关置于可信代理之后，设置 gateway.auth.mode: "trusted-proxy"，然后打开代理 URL。同主机的 local loopback 代理需要显式设置 gateway.auth.trustedProxy.allowLoopback: true。
• SSH 隧道：运行 ssh -N -L 18789:127.0.0.1:18789 user@gateway-host，然后打开 http://127.0.0.1:18789/。通过隧道时仍需共享密钥身份验证；如果出现提示，请粘贴已配置的令牌或密码。

有关绑定模式和身份验证的详细信息，请参阅仪表板和Web 界面。

它们控制不同的层：

• approvals.exec——将审批提示转发到聊天目标。
• channels.<channel>.execApprovals——使该渠道成为 Exec 审批的原生审批客户端。

主机 Exec 策略仍然是真正的审批关卡；聊天配置只控制提示出现的位置以及用户如何响应。

通常不需要同时使用两者：

• 如果聊天已支持命令和回复，同一聊天中的 /approve 可通过共享路径工作。
• 当受支持的原生渠道能够安全推断审批人时，如果 channels.<channel>.execApprovals.enabled 未设置或为 "auto"，OpenClaw 会自动启用私信优先的原生审批。
• 当原生审批卡片/按钮可用时，该 UI 是主要方式；仅当工具结果表明聊天审批不可用时，才提及手动 /approve 命令。
• 仅当提示还必须发送到其他聊天或明确指定的运维房间时，才使用 approvals.exec。
• 仅当你希望将审批提示发回原始房间/主题时，才使用 channels.<channel>.execApprovals.target: "channel" 或 "both"。
• 插件审批彼此独立：默认使用同一聊天中的 /approve，可选择通过 approvals.plugin 转发，并且只有部分原生渠道也会为此保留原生处理方式。

简而言之：转发用于路由，原生客户端配置用于提供更丰富的渠道专属用户体验。 请参阅 Exec 审批。

需要 Node 22.22.3+、24.15+ 或 25.9+（推荐 Node 24）。pnpm 是仓库的包管理器。 Bun 可以安装依赖项并运行包脚本，但无法运行 OpenClaw CLI 或 Gateway 网关，因为它缺少 node:sqlite。

可以，但请先检查 RAM：Pi 5 和 Pi 4（2 GB+）最合适；Pi 3B+（1 GB）可以运行，但速度较慢；不推荐 Pi Zero 2 W（512 MB）。

绝对最低要求：1 GB RAM、1 个核心、500 MB 可用磁盘空间、64 位操作系统。由于 Pi 只运行 Gateway 网关（模型会调用云 API），即使配置一般的 Pi 也能应对这种负载。

小型 Pi/VPS 也可以仅托管 Gateway 网关，同时在笔记本电脑/手机上配对节点， 以使用本地屏幕、摄像头、画布或执行命令。请参阅节点。

完整设置演练：Raspberry Pi。

• 使用 64 位操作系统；不要使用 32 位 Raspberry Pi OS。
• 在 2 GB 或更小的开发板上添加交换空间。
• 为提升性能和使用寿命，优先使用 USB SSD，而不是 SD 卡。
• 优先使用可修改的（git）安装方式，以便查看日志并快速更新。
• 开始时不要启用渠道/Skills，之后逐个添加。
• 异常的二进制文件错误（“exec format error”）通常是因为某个可选 Skills 工具缺少 ARM64 构建版本。

完整指南：Raspberry Pi。另请参阅 Linux。

该界面依赖 Gateway 网关可访问且已通过身份验证。当配置了模型提供商时，TUI 还会在首次孵化时 自动发送“Wake up, my friend!”。如果跳过了模型/身份验证设置，新手引导会显示 “Model auth missing”提示，并在不发送任何内容的情况下打开 TUI——请使用 openclaw configure --section model 添加提供商。如果看到唤醒消息但没有回复，且令牌数始终为 0，则智能体从未运行。

1. 重启 Gateway 网关：

openclaw gateway restart

2. 检查状态和身份验证：

openclaw statusopenclaw models statusopenclaw logs --follow

3. 仍然卡住？运行：

openclaw doctor

如果 Gateway 网关位于远程位置，请确认隧道/Tailscale 连接正常，并且 UI 指向正确的 Gateway 网关。请参阅远程访问。

可以。复制状态目录和工作区，然后运行一次 Doctor：

1. 在新机器上安装 OpenClaw。
2. 从旧机器复制 $OPENCLAW_STATE_DIR（默认：~/.openclaw）。
3. 复制你的工作区（默认：~/.openclaw/workspace）。
4. 运行 openclaw doctor，然后重启 Gateway 网关服务。

这会保留配置、身份验证配置文件、WhatsApp 凭据、会话和记忆——只要复制了两个位置， 你的 bot 就会保持完全相同。在远程模式下，Gateway 网关主机拥有会话存储和工作区。

**重要：**如果只将工作区提交/推送到 GitHub，则备份的是 记忆 + 引导文件，而不是会话历史记录或身份验证信息。后两者位于 ~/.openclaw/ 下（例如 ~/.openclaw/agents/<agentId>/agent/openclaw-agent.sqlite）。

相关内容：迁移、文件在磁盘上的存储位置、 Agent 工作区、Doctor、 远程模式。

查看 GitHub 更新日志： https://github.com/openclaw/openclaw/blob/main/CHANGELOG.md

最新条目位于顶部。如果顶部章节是 Unreleased，则下一个带日期的章节是最新发布版本。 条目分为亮点、变更和修复（必要时还包括文档/其他章节）。

某些 Comcast/Xfinity 连接会通过 Xfinity Advanced Security 错误地屏蔽 docs.openclaw.ai。 请将其禁用或将 docs.openclaw.ai 加入允许列表，然后重试。请帮助我们 解除屏蔽：https://spa.xfinity.com/check_url_status。

仍然被屏蔽？GitHub 上提供了文档镜像： https://github.com/openclaw/openclaw/tree/main/docs

稳定版和测试版是 npm dist-tag，而不是独立的代码分支：

• latest = 稳定版
• beta = 用于测试的早期构建版本（当测试版缺失或早于当前稳定版本时，回退到 latest）

稳定版本通常会先发布到 beta，然后通过明确的推广步骤 将同一版本移至 latest，而不更改版本号。维护者 也可以直接发布到 latest。因此，推广后测试版和稳定版可能指向 同一版本。

查看变更内容：CHANGELOG.md。

有关一行安装命令以及 beta 和 dev 之间的区别，请参阅下一个折叠面板。

测试版使用 npm dist-tag beta（推广后可能与 latest 相同）。 开发版是不断更新的 main 最新提交（git）；发布到 npm 时使用 dist-tag dev。

一行安装命令（macOS/Linux）：

curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash -s -- --beta

curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash -s -- --install-method git

Windows 安装程序（PowerShell）：iwr -useb https://openclaw.ai/install.ps1 | iex

更多详情：开发频道和安装程序标志。

有两种方式：

1. 开发频道（现有安装）：

openclaw update --channel dev

这会切换到 main 的 git 检出，在上游分支上执行变基、构建， 并从该检出安装 CLI。

2. 可修改的（git）安装（全新计算机）：

curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash -s -- --install-method git

建议手动克隆：

git clone https://github.com/openclaw/openclaw.gitcd openclawpnpm installpnpm build

文档：更新、开发频道、安装。

大致参考：

• **安装：**2-5 分钟。
• **快速开始新手引导：**几分钟（local loopback Gateway 网关、自动令牌、默认工作区）。
• **高级/完整新手引导：**如果提供商登录、渠道配对、守护进程安装、网络下载或 Skills 需要额外设置，则耗时更长。

向导会预先显示这一时间安排。可以跳过可选步骤，之后使用 openclaw configure 返回继续设置。

卡住了？请参阅上方的我卡住了。

使用 --verbose 重新运行：

curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash -s -- --verbosecurl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash -s -- --beta --verbosecurl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash -s -- --install-method git --verbose

install.ps1 没有专用的详细输出开关；请改用 Set-PSDebug -Trace 1 / -Trace 0 包装它。完整标志参考：安装程序标志。

Windows 上常见的两个问题：

1) npm 错误 spawn git / 找不到 git

• 安装 Git for Windows，确保 git 位于 PATH 中。
• 关闭并重新打开 PowerShell，然后重新运行安装程序。

2) 安装后无法识别 openclaw

• 你的 npm 全局二进制文件夹不在 PATH 中。
• 检查该文件夹：npm config get prefix。
• 将该目录添加到你的用户 PATH（无需添加 \bin 后缀；在大多数系统上，该目录为 %AppData%\npm）。
• 关闭并重新打开 PowerShell。

更喜欢桌面应用？请使用 Windows Hub。对于仅使用终端的设置，PowerShell 安装程序和 WSL2 Gateway 网关路径均受支持。文档：Windows。

这通常是原生 Windows shell 的控制台代码页不匹配所致。

症状：system.run/exec 输出中的中文显示为乱码；同一命令 在其他终端配置中显示正常。

PowerShell 中的解决方法：

chcp 65001[Console]::InputEncoding = [System.Text.UTF8Encoding]::new($false)[Console]::OutputEncoding = [System.Text.UTF8Encoding]::new($false)$OutputEncoding = [System.Text.UTF8Encoding]::new($false)

然后重启 Gateway 网关并重试：

openclaw gateway restart

在最新版 OpenClaw 上仍能复现？请跟踪或报告：Issue #30640。

使用可修改的（git）安装，以便在本地获取完整源代码和文档，然后 在该文件夹中询问你的 Bot（或 Claude/Codex），这样它就能读取仓库并给出准确答案。

curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash -s -- --install-method git

更多详情：安装和安装程序标志。

• Linux 快速安装路径 + 服务安装：Linux。
• 完整演练：入门指南。
• 安装程序 + 更新：安装和更新。

任何 Linux VPS 都可以。请在服务器上安装，然后通过 SSH/Tailscale 访问 Gateway 网关。

指南：exe.dev、Hetzner、Fly.io。 远程访问：Gateway 网关远程访问。

汇集常见提供商的托管中心：

• VPS 托管（所有提供商集中在一处）
• Fly.io
• Hetzner
• exe.dev

在云端，Gateway 网关运行在服务器上，你可以从笔记本电脑/手机 通过 Control UI（或 Tailscale/SSH）进行访问。你的状态 + 工作区存储在服务器上，因此 应将该主机视为权威数据源并进行备份。

将节点（Mac/iOS/Android/无界面设备）与该云端 Gateway 网关配对，这样在 Gateway 网关保留在 云端的同时，可以使用笔记本电脑上的本地屏幕/摄像头/canvas 或执行命令。

中心：平台。远程访问：Gateway 网关远程访问。 节点：节点、节点 CLI。

可以，但不建议这样做。更新流程可能会重启 Gateway 网关（导致 活动会话断开），可能需要干净的 git 检出，并且可能提示确认。 由操作员通过 shell 执行更新更安全。

openclaw updateopenclaw update statusopenclaw update --channel stable|extended-stable|beta|devopenclaw update --tag <dist-tag|version>openclaw update --no-restart

通过智能体实现自动化：

openclaw update --yes --no-restartopenclaw gateway restart

文档：更新、更新 OpenClaw。

openclaw onboard 是推荐的设置路径。在本地模式下，它会引导完成：

1. 模型/身份验证 - 提供商 OAuth、API 密钥或手动身份验证（包括 LM Studio 等本地选项）；选择默认模型。
2. 工作区 - 位置 + 引导文件。
3. Gateway 网关 - 端口、绑定地址、身份验证模式、Tailscale 暴露。
4. 渠道 - 内置及官方插件聊天渠道：iMessage、Discord、Feishu、Google Chat、Mattermost、Microsoft Teams、QQ Bot、Signal、Slack、Telegram、WhatsApp 等。
5. 守护进程 - LaunchAgent（macOS）、systemd 用户单元（Linux/WSL2）或原生 Windows Scheduled Task。
6. 健康检查 - 启动 Gateway 网关并验证其正在运行。
7. Skills - 安装推荐的 Skills 和可选依赖项。

它会预先说明所需时长，并在配置的模型未知 或缺少身份验证时发出警告。完整说明：新手引导（CLI）。

不需要。可以使用 API 密钥（Anthropic/OpenAI/其他提供商）或仅限本地的模型 运行 OpenClaw，让你的数据保留在设备上。订阅（Claude Pro/Max、ChatGPT/Codex） 只是对这些提供商进行身份验证的可选方式。

对于 Anthropic：使用 API 密钥时采用标准的按用量付费；Claude CLI 会复用同一主机上现有的 Claude Code 登录。目前，Anthropic 将 Claude CLI 的非交互式 claude -p 路径视为 Agent SDK/编程式使用， 仍会计入你的订阅方案限额——在依赖订阅行为前，请查阅 Anthropic 当前的计费 文档。对于长期运行的 Gateway 网关主机和共享自动化，Anthropic API 密钥是更可预测的选择。

完全支持使用 OpenAI Codex OAuth（ChatGPT/Codex 订阅）对智能体模型进行身份验证。 OpenClaw 还支持托管式订阅选项，包括 Qwen Cloud Coding Plan、MiniMax Coding Plan 和 Z.AI / GLM Coding Plan。

文档：Anthropic、OpenAI、 Qwen Cloud、MiniMax、Z.AI (GLM)、 本地模型、Models。

可以。OpenClaw 支持为 Pro/Max/Team/Enterprise 方案复用 Claude CLI。Anthropic 目前将 OpenClaw 使用的 claude -p 路径视为受你的方案限额约束的订阅方案用量， 而非独立的免费额度——有关当前计费详情以及 Anthropic 官方支持文章的链接，请参阅 Anthropic。如需最可预测的服务器端设置，请改用 Anthropic API 密钥。

支持，通过复用 Claude CLI 实现。Anthropic 对 claude -p/Agent SDK 使用方式的计费处理 会随时间变化；在依赖特定计费行为前，请参阅 Anthropic， 了解当前状态以及带日期的 Anthropic 支持文章链接。

Anthropic setup-token 身份验证仍是受支持的令牌路径，但 OpenClaw 会优先使用 Claude CLI 复用和 claude -p（如可用）。对于生产环境或多用户 工作负载，Anthropic API key 仍是更安全、更可预测的选择。其他 订阅式托管选项：OpenAI、Qwen Cloud、 MiniMax、Z.AI (GLM)。

当前窗口内的 Anthropic 配额/速率限制已耗尽。在 Claude CLI 中，请等待窗口重置或升级你的方案。使用 Anthropic API key 时， 请在 Anthropic Console 中检查用量/账单，并根据需要提高限制。

如果消息明确为 Extra usage is required for long context requests， 则该请求正尝试使用 Anthropic 的 1M 上下文窗口（支持正式可用版 1M 的 Claude 4.x 模型，或旧版 params.context1m: true 配置），而你当前的凭据 不符合长上下文计费资格。

设置一个回退模型，这样当某个提供商受到速率限制时，OpenClaw 仍可继续回复。 请参阅模型、OAuth和 Anthropic 长上下文需要额外用量时出现 429。

是。OpenClaw 内置了 Amazon Bedrock (Converse) 提供商。存在 AWS 环境变量 标记（AWS_ACCESS_KEY_ID、AWS_PROFILE、AWS_BEARER_TOKEN_BEDROCK）时， OpenClaw 会自动启用隐式 Bedrock 提供商以发现模型；否则， 请设置 plugins.entries.amazon-bedrock.config.discovery.enabled: true 或添加手动 提供商条目。请参阅 Amazon Bedrock和模型提供商。 如果你偏好托管密钥流程，也仍可选择在 Bedrock 前使用兼容 OpenAI 的代理。

OpenClaw 通过 OAuth（登录 ChatGPT）支持 OpenAI Codex。在没有主模型的全新 设置中，会明确使用 openai/gpt-5.6-sol， 以进行 ChatGPT/Codex 订阅身份验证并通过原生 Codex app-server 执行。 重新进行身份验证会保留现有的显式模型，包括 openai/gpt-5.5。如果 Codex 工作区未提供 GPT-5.6，请显式选择 openai/gpt-5.5；OpenClaw 不会静默降级。旧版 带 Codex 前缀的模型引用属于旧版配置，会由 openclaw doctor --fix 修复。对于非智能体 OpenAI API 表面，仍可直接使用 OpenAI API key；通过一个有序的 openai API key 配置文件， 智能体模型也可使用该方式。请参阅模型提供商和 新手引导（CLI）。

openai 是 OpenAI API key 和 ChatGPT/Codex OAuth 当前共用的提供商及身份验证配置文件 ID——OpenAI Codex 已并入其中。你可能仍会在较旧的配置和迁移警告中看到旧版 openai-codex 前缀：

• openai/gpt-5.6-sol = 使用原生 Codex 运行时处理智能体轮次的全新 ChatGPT/Codex 订阅设置。
• openai/gpt-5.5 = 现有配置或无法访问 GPT-5.6 的账户可显式选择的受支持选项。
• 旧版 openai-codex/* 模型引用 = 由 openclaw doctor --fix 修复的旧版路由。
• openai/gpt-5.5 加上一个有序的 openai API key 配置文件 = OpenAI 智能体模型的 API key 身份验证。
• 旧版 openai-codex 身份验证配置文件 ID = 由 openclaw doctor --fix 迁移的旧版 ID。

想使用 OpenAI Platform 直接计费？设置 OPENAI_API_KEY。想使用 ChatGPT/Codex 订阅身份验证？运行 openclaw models auth login --provider openai。将 模型引用保留在规范的 openai/* 提供商下。全新的订阅 设置会明确使用 openai/gpt-5.6-sol；Doctor 会修复旧版带 Codex 前缀的 引用，但不会升级显式选择的 openai/gpt-5.5。

Codex OAuth 使用由 OpenAI 管理、取决于方案的配额窗口，即使使用同一账户， 也可能与 ChatGPT 网站/应用中的体验不同。

openclaw models status 会显示当前可见的提供商用量/配额窗口，但 不会虚构配额，也不会将 ChatGPT 网页版权益转化为直接 API 访问权限。若要使用 OpenAI Platform 的直接计费/限制路径，请使用 openai/* 和 API key。

是，完全支持。OpenAI 明确允许在 OpenClaw 等外部 工具/工作流中使用订阅 OAuth。新手引导可以为你运行 OAuth 流程。

请参阅 OAuth、模型提供商和新手引导（CLI）。

Gemini CLI 使用插件身份验证流程，而不是在 openclaw.json 中配置客户端 ID 或密钥。

1. 在本地安装 Gemini CLI，确保 gemini 位于 PATH 中：
   • Homebrew：brew install gemini-cli
   • npm：npm install -g @google/gemini-cli
2. 启用插件：openclaw plugins enable google
3. 登录：openclaw models auth login --provider google-gemini-cli --set-default
4. 登录后的默认模型：google/gemini-3.1-pro-preview（运行时 google-gemini-cli）
5. 登录后请求仍失败？请在 Gateway 网关主机上设置 GOOGLE_CLOUD_PROJECT 或 GOOGLE_CLOUD_PROJECT_ID，然后重试。

OAuth 令牌存储在 Gateway 网关主机的身份验证配置文件中。详情请参阅：Google、模型提供商。

通常不适合。OpenClaw 需要大上下文和强安全能力；小显存卡会截断上下文， 并绕过提供商端的安全过滤器。如果必须使用，请在本地运行你能承载的最大模型版本 （LM Studio）——请参阅本地模型。较小或量化的 模型会增加提示注入风险——请参阅安全性。

请选择锁定区域的端点。OpenRouter 为 MiniMax、Kimi 和 GLM 提供美国托管选项；请选择美国托管变体，以将数据保留在该区域内。你仍可通过 models.mode: "merge" 同时列出 Anthropic/OpenAI，这样既能遵循所选的区域化提供商， 又能保持回退可用。

不需要。OpenClaw 可运行于 macOS 或 Linux（Windows 通过 WSL2）。Mac mini 是常见的 常开主机选择，但小型 VPS、家庭服务器或 Raspberry Pi 级别的设备也可以。

只有使用 macOS 专属工具时才需要 Mac。对于 iMessage，请在任何已登录 Messages 的 Mac 上使用 iMessage和 imsg——如果 Gateway 网关运行在 Linux 或其他位置， 请将 channels.imessage.cliPath 设置为一个 SSH 包装器，以在该 Mac 上运行 imsg。对于其他 macOS 专属工具，请在 Mac 上运行 Gateway 网关，或配对一个 macOS 节点。

文档：iMessage、节点、Mac 远程模式。

你需要某台 macOS 设备登录 Messages——不一定是 Mac mini，任何 Mac 都可以。使用 iMessage和 imsg；Gateway 网关可以运行在该 Mac 上，也可以运行在其他位置并使用 SSH 包装器 cliPath。

常见设置：

• Gateway 网关运行在 Linux/VPS 上，将 channels.imessage.cliPath 设置为 SSH 包装器，以在已登录 Messages 的 Mac 上运行 imsg。
• 所有组件都运行在同一台 Mac 上，这是最简单的单机设置。

文档：iMessage、节点、Mac 远程模式。

可以。Mac mini 可以运行 Gateway 网关，你的 MacBook Pro 则作为节点 （配套设备）连接。节点不运行 Gateway 网关——它们会添加该设备上的 屏幕、摄像头、画布和 system.run 等能力。

常见模式：Gateway 网关运行在常开的 Mac mini 上；MacBook Pro 运行 macOS 应用或 节点主机，并与 Gateway 网关配对。使用 openclaw nodes status / openclaw nodes list 检查。

文档：节点、节点 CLI。

可以使用 Bun 安装依赖项或运行软件包脚本。OpenClaw CLI 和 Gateway 网关需要 Node，因为规范状态存储使用 node:sqlite；Bun 不 提供该 API。

channels.telegram.allowFrom 是人类发送者的 Telegram 用户 ID（数字）， 而不是 Bot 用户名。设置仅要求填写数字用户 ID；openclaw doctor --fix 可以尝试解析旧版 @username 条目。

更安全的方式（不使用第三方 Bot）：向你的 Bot 发送私信，运行 openclaw logs --follow，读取 from.id。

官方 Bot API：向你的 Bot 发送私信，调用 https://api.telegram.org/bot<bot_token>/getUpdates，读取 message.from.id。

第三方方式（隐私性较低）：向 @userinfobot 或 @getidsbot 发送私信。

请参阅 Telegram 访问控制。

可以，通过多智能体路由实现。将每个发送者的 WhatsApp 私信（peer: { kind: "direct", id: "+15551234567" }）绑定到不同的 agentId，让每个人都有自己的工作区和会话存储。回复仍来自同一个 WhatsApp 账户；私信访问控制（channels.whatsapp.dmPolicy / channels.whatsapp.allowFrom）在每个账户中是全局的。请参阅多智能体路由和 WhatsApp。

可以。使用多智能体路由：为每个智能体指定各自的默认模型，然后将入站 路由（提供商账户或特定对端）绑定到相应智能体。配置示例： 多智能体路由。另请参阅模型和 配置。

可以，通过 Linuxbrew：

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"echo 'eval "$(/home/linuxbrew/.linuxbrew/bin/brew shellenv)"' >> ~/.profileeval "$(/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 安装：**全局 CLI 安装，不含仓库，最适合“直接运行”。更新来自 npm dist-tags。

文档：入门指南、更新。

可以，在现有安装上使用 openclaw update --channel ... 即可。这不会 删除你的数据——只会更改 OpenClaw 代码的安装方式。状态（~/.openclaw）和 工作区（~/.openclaw/workspace）均保持不变。

从 npm 切换到 git：

openclaw update --channel dev

从 git 切换到 npm：

openclaw update --channel stable

添加 --dry-run 可先预览计划的模式切换。更新程序会运行 Doctor 后续操作、刷新目标频道的插件源，并重启 Gateway 网关， 除非传入 --no-restart。

安装程序也可以强制使用任一模式：

curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash -s -- --install-method gitcurl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash -s -- --install-method npm

备份提示：各项内容在磁盘上的存储位置。

需要全天候可靠运行？请使用 VPS。希望尽量省事，并且可以接受 休眠或重启造成的中断？请在本地运行。

笔记本电脑（本地 Gateway 网关）

• **优点：**无需服务器费用、可直接访问本地文件、拥有实时浏览器窗口。
• **缺点：**休眠或网络中断会使其断开连接、操作系统更新或重启会造成中断、设备必须保持唤醒。

VPS / 云端

• **优点：**持续在线、网络稳定、不会受笔记本电脑休眠影响、更容易保持运行。
• **缺点：**通常无界面（可使用截图）、只能远程访问文件、更新时需要使用 SSH。

WhatsApp/Telegram/Slack/Mattermost/Discord 都能在 VPS 上正常运行——真正需要 权衡的是无头浏览器与可见窗口。请参阅浏览器。

默认建议：如果之前遇到过 Gateway 网关断开连接，请使用 VPS；如果正在使用 Mac， 并需要访问本地文件或使用可见浏览器界面进行自动化，则本地运行非常合适。

这不是必需的，但为了可靠性和隔离性，建议这样做。

• **专用主机（VPS/Mac mini/Raspberry Pi）：**持续在线、较少受到休眠或重启中断、权限更清晰、更容易保持运行。
• **共享笔记本电脑/台式机：**适合测试和主动使用，但设备休眠或更新时会暂停运行。

兼顾两者优势的方法：将 Gateway 网关部署在专用主机上，并将笔记本电脑配对为 节点，以使用本地屏幕、摄像头和 Exec 工具。请参阅节点和安全性。

• **绝对最低要求：**1 个 vCPU、1 GB RAM、约 500 MB 磁盘空间。
• **推荐配置：**1-2 个 vCPU、2 GB+ RAM，以留出余量（用于日志、媒体、多个渠道）。节点工具和浏览器自动化可能消耗大量资源。

操作系统：Ubuntu LTS（或任何现代 Debian/Ubuntu）——这是经过最充分测试的 Linux 安装方式。

文档：Linux、VPS 托管。

可以。将虚拟机视同 VPS：它需要持续运行、可访问，并拥有足够的 RAM， 以供 Gateway 网关和启用的所有渠道使用。

• **绝对最低要求：**1 个 vCPU、1 GB RAM。
• **推荐配置：**如果使用多个渠道、浏览器自动化或媒体工具，建议配备 2 GB+ RAM。
• **操作系统：**Ubuntu LTS 或其他现代 Debian/Ubuntu。

在 Windows 上，可使用 Windows Hub 完成桌面设置，也可使用 WSL2 运行 Linux 风格的 Gateway 网关虚拟机， 以获得广泛的工具兼容性。请参阅 Windows、VPS 托管。 在虚拟机中运行 macOS：请参阅 macOS 虚拟机。