首次安装 OpenClaw 时卡在“wake up my friend”或仪表盘打不开？优先用 openclaw status、openclaw models status 和 openclaw doctor 排查本地配置与环境问题。推荐从 git（hackable）安装，以便 AI 工具读取源码辅助调试。Gateway 需 Node >= 22，不支持 Bun。仪表盘默认端口 18789，同机访问直接用 http://127.0.0.1:18789/，远程需配置 Tailscale、SSH 隧道或可信代理。

OpenClaw 首次安装与配置常见问题排查指南

快速开始与首次运行设置

卡住了，最快的方法是什么？

用能看到你机器的本地 AI 智能体。这比在 Discord 里问有效得多，因为大多数卡住案例都是本地配置或环境问题，远程无法查看。

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

这些工具能读取仓库、运行命令、检查日志。通过 hackable（git）安装提供完整源码：

curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method git

这样 OpenClaw 会从 git 检出安装，智能体能阅读代码和文档。后续可以重新运行安装器（不加 --install-method git）切回稳定版。

提示：让智能体先制定修复计划，再逐条执行命令。

发现 bug 或修复方案，请提交 GitHub Issue 或 PR：

• https://github.com/openclaw/openclaw/issues
• https://github.com/openclaw/openclaw/pulls

求助时先运行以下命令并分享输出：

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。

快速调试循环：前 60 秒排查步骤。
安装文档：安装、安装器参数、更新。

Heartbeat 持续跳过，跳过原因是什么意思？

常见跳过的原因：

• quiet-hours：不在配置的活动时间窗口内。
• empty-heartbeat-file：HEARTBEAT.md 存在但只包含空白或仅含标题的骨架。
• no-tasks-due：HEARTBEAT.md 任务模式已启用，但所有任务间隔还未到期。
• alerts-disabled：所有 heartbeat 可见性都被禁用（showOk、showAlerts 和 useIndicator 均为关闭）。

在任务模式下，到期时间戳只在真实 heartbeat 运行完成后才推进。跳过的运行不会标记任务已完成。

文档：Heartbeat、自动化。

推荐的安装和设置方式是什么？

推荐从源码运行并使用 onboard：

curl -fsSL https://openclaw.ai/install.sh | bash
openclaw onboard --install-daemon

向导也能自动构建 UI 资源。Onboarding 后，Gateway 默认运行在端口 18789。

从源码（贡献者/开发者）：

git clone https://github.com/openclaw/openclaw.git
cd openclaw
pnpm install
pnpm build
pnpm ui:build
openclaw onboard

如果还没有全局安装，用 pnpm openclaw onboard 运行。

Onboard 后如何打开仪表盘？

向导会在 onboard 完成后自动用浏览器打开一个干净的（不含令牌的）仪表盘 URL，并在摘要中打印链接。保留那个标签页；如果没有启动，在同一台机器上复制/粘贴打印的 URL。

在 localhost 和远程时如何认证仪表盘？

同机 localhost：

• 打开 http://127.0.0.1:18789/。
• 如果要求共享密钥认证，在 Control UI 设置中粘贴配置的 token 或 password。
• Token 来源：gateway.auth.token（或 OPENCLAW_GATEWAY_TOKEN）。
• Password 来源：gateway.auth.password（或 OPENCLAW_GATEWAY_PASSWORD）。
• 如果还没有配置共享密钥，用 openclaw doctor --generate-gateway-token 生成一个 token。

不在 localhost：

• Tailscale Serve（推荐）：保持绑定回环，运行 openclaw gateway --tailscale serve，打开 https://<magicdns>/。如果 gateway.auth.allowTailscale 为 true，身份头信息满足 Control UI/WebSocket 认证（无需粘贴共享密钥，假定受信任的 Gateway 主机）；HTTP API 仍需要共享密钥认证，除非你特意使用 private-ingress none 或 trusted-proxy HTTP 认证。同一客户端并发的不良 Serve 认证尝试会在失败限速器记录之前被序列化，所以第二次重试可能会直接显示 retry later。
• Tailnet 绑定：运行 openclaw gateway --bind tailnet --token "<token>"（或配置 password 认证），打开 http://<tailscale-ip>:18789/，然后在仪表盘设置中粘贴匹配的共享密钥。
• 身份感知反向代理：将 Gateway 放在可信代理后，配置 gateway.auth.mode: "trusted-proxy"，然后打开代理 URL。同机回环代理需要显式设置 gateway.auth.trustedProxy.allowLoopback = true。
• SSH 隧道：ssh -N -L 18789:127.0.0.1:18789 user@host，然后打开 http://127.0.0.1:18789/。隧道上仍适用共享密钥认证；提示时粘贴配置的 token 或 password。

详见仪表盘和Web 界面了解绑定模式和认证细节。

为什么聊天审批有两个执行审批配置？

它们控制不同层面：

• approvals.exec：将审批提示转发到聊天目标。
• channels.<channel>.execApprovals：使那个渠道充当执行审批的原生审批客户端。

主机执行策略仍是真正的审批网关。聊天配置只控制审批提示显示在哪里以及人们如何回应。

大多数情况下不需要两者都配：

• 如果聊天已支持命令和回复，同聊天 /approve 通过共享路径工作。
• 如果支持的原生渠道能安全推断批准者，OpenClaw 现在会在 channels.<channel>.execApprovals.enabled 未设置或为 "auto" 时自动启用 DM 优先原生审批。
• 当原生审批卡片/按钮可用时，优先使用原生 UI；智能体只应在工具结果说聊天审批不可用或手动审批是唯一路径时才包含手动 /approve 命令。
• 只在需要将提示转发到其他聊天或专门的 ops 房间时使用 approvals.exec。
• 只在明确希望审批提示发回原始房间/主题时使用 channels.<channel>.execApprovals.target: "channel" 或 "both"。
• 插件审批是单独的：默认使用同聊天 /approve，可选 approvals.plugin 转发，只有部分原生渠道在之上保持插件审批原生处理。

简而言之：转发用于路由，原生客户端配置用于更丰富的渠道特定用户体验。 详见执行审批。

需要什么运行时？

Node >= 22 是必需的。推荐用 pnpm。Gateway 不推荐用 Bun。

能在 Raspberry Pi 上运行吗？

能。Gateway 很轻量——文档列出个人使用需要 512MB-1GB RAM、1 核心、约 500MB 磁盘，并指出 Raspberry Pi 4 可以运行。

如果想要额外余量（日志、媒体、其他服务），推荐 2GB，但这不是硬性最低要求。

提示：小型 Pi/VPS 可以托管 Gateway，你可以在笔记本/手机上配对节点以获得本地屏幕/摄像头/画布或命令执行。详见节点。

Raspberry Pi 安装有什么提示？

简而言之：可以工作，但可能遇到粗糙边缘。

• 使用 64 位操作系统，保持 Node >= 22。
• 优先选择 hackable（git）安装，以便查看日志和快速更新。
• 先不配置渠道/技能，然后逐个添加。
• 如果遇到奇怪的二进制问题，通常是 ARM 兼容性 问题。

文档：Linux、安装。

卡在“wake up my friend” / onboarding 无法孵化怎么办？

那个画面依赖 Gateway 可达且已认证。TUI 也会在首次孵化时自动发送“Wake up, my friend!”。如果你看到那一行但没有回复且 token 数保持为 0，说明智能体从未运行。

1. 重启 Gateway：

openclaw gateway restart

2. 检查状态和认证：

openclaw status
openclaw models status
openclaw logs --follow

3. 如果仍然卡住，运行：

openclaw doctor

如果 Gateway 是远程的，确保隧道/Tailscale 连接正常，并且 UI 指向正确的 Gateway。参见远程访问。

能否把安装迁移到新机器（如 Mac mini）而不重新做 onboarding？

能。复制状态目录和工作区，然后运行一次 Doctor。只要复制两个位置，你的机器人就能保持“完全相同”（记忆、会话历史、认证、渠道状态）：

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

这样保留了配置、认证配置文件、WhatsApp 凭据、会话和记忆。如果处于远程模式，记住 Gateway 主机拥有会话存储和工作区。

重要：如果你只把工作区提交/推送到 GitHub，你备份了记忆 + 启动文件，但不是会话历史或认证。它们存放在 ~/.openclaw/ 下（例如 ~/.openclaw/agents/<agentId>/sessions/）。

相关：迁移、磁盘文件位置、智能体工作区、Doctor、远程模式。

在哪里查看最新版本的更新内容？

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

最新条目在最上面。如果顶部部分标记为 Unreleased，下一个有日期的部分是最近发布的版本。条目按 Highlights、Changes 和 Fixes 分组（必要时还有 docs/other 部分）。

无法访问 docs.openclaw.ai（SSL 错误）

部分 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

stable 和 beta 有什么区别？

Stable 和 beta 是 npm dist-tags，不是独立的代码线：

• latest = 稳定版
• beta = 用于测试的早期构建

通常，稳定版先作为 beta 发布，然后经历一个显式的升级步骤将该版本移入 latest。维护者也可以在需要时直接发布到 latest。所以 beta 和 stable 在升级后可以指向同一个版本。

查看变更：https://github.com/openclaw/openclaw/blob/main/CHANGELOG.md

关于安装一行命令以及 beta 和 dev 的区别，见下面的折叠项。

怎么安装 beta 版本？beta 和 dev 有什么区别？

Beta 是 npm dist-tag beta（升级后可能等于 latest）。 Dev 是 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）： https://openclaw.ai/install.ps1

更多细节：开发渠道和安装器参数。

怎么尝试最新代码？

两种方式：

1. Dev 渠道（git 检出）：

openclaw update --channel dev

这会切换到 main 分支并从源码更新。

2. Hackable 安装（从安装器网站）：

curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method git

这会给你一个本地仓库，可以编辑，然后通过 git 更新。

如果你更喜欢手动克隆：

git clone https://github.com/openclaw/openclaw.git
cd openclaw
pnpm install
pnpm build

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

安装和 onboard 一般需要多久？

大致时间：

• 安装： 2-5 分钟
• Onboarding： 5-15 分钟，取决于配置了多少渠道/模型

如果卡住，使用安装器卡住和我卡住了中的快速调试循环。

安装器卡住？如何获取更多反馈？

用详细输出重新运行安装器：

curl -fsSL https://openclaw.ai/install.sh | bash -s -- --verbose

Beta 安装带详细输出：

curl -fsSL https://openclaw.ai/install.sh | bash -s -- --beta --verbose

Hackable（git）安装：

curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method git --verbose

Windows（PowerShell）等效：

# install.ps1 目前没有专用的 -Verbose 标志。
Set-PSDebug -Trace 1
& ([scriptblock]::Create((iwr -useb https://openclaw.ai/install.ps1))) -NoOnboard
Set-PSDebug -Trace 0

更多选项：安装器参数。

Windows 安装提示 git 未找到或 openclaw 无法识别

两个常见 Windows 问题：

1) npm error spawn git / git not found

• 安装 Git for Windows 并确保 git 在 PATH 上。
• 关闭并重新打开 PowerShell，然后重新运行安装器。

2) 安装后 openclaw 无法识别

• npm 全局 bin 文件夹不在 PATH 上。
• 检查路径：

  npm config get prefix

• 将该目录添加到用户 PATH（Windows 上无需 \bin 后缀；大多数系统是 %AppData%\npm）。
• 更新 PATH 后关闭并重新打开 PowerShell。

如果想要最顺畅的 Windows 设置，使用 WSL2 代替原生 Windows。 文档：Windows。

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

文档没回答我的问题，如何获得更好的答案？

使用 hackable（git）安装，这样本地就有完整源码和文档，然后在该目录下向你的机器人（或 Claude/Codex）提问，使其能读取仓库并精确回答。

curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method git

更多细节：安装和安装器参数。

如何在 Linux 上安装 OpenClaw？

简而言之：遵循 Linux 指南，然后运行 onboard。

• Linux 快速路径 + 服务安装：Linux。
• 完整指南：入门。
• 安装器 + 更新：安装与更新。

如何在 VPS 上安装 OpenClaw？

任何 Linux VPS 都可以。在服务器上安装，然后用 SSH/Tailscale 连接到 Gateway。

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

云端/VPS 安装指南在哪里？

我们维护了一个托管中心，包含常见提供商。选择一个并按照指南操作：

• VPS 托管（所有提供商汇总）
• Fly.io
• Hetzner
• exe.dev

云端工作原理：Gateway 运行在服务器上，你通过 Control UI（或 Tailscale/SSH）从笔记本/手机访问。状态 + 工作区在服务器上，所以将主机视为唯一真相源并备份。

你可以将节点（Mac/iOS/Android/headless）配对到云端 Gateway，以访问本地屏幕/摄像头/画布或在笔记本上运行命令，同时将 Gateway 保留在云端。

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

可以让 OpenClaw 自己更新吗？

简而言之：可以，但不推荐。更新流可能重启 Gateway（会断开当前会话），可能需要干净的 git 检出，并且可能提示确认。更安全的方式：从 shell 作为操作者运行更新。

使用 CLI：

openclaw update
openclaw update status
openclaw update --channel stable|beta|dev
openclaw update --tag <dist-tag|version>
openclaw update --no-restart

如果必须从智能体自动化：

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

文档：更新、升级。

Onboarding 具体做了什么？

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

• 模型/认证设置（提供商 OAuth、API key、Anthropic setup-token，以及本地模型选项如 LM Studio）
• 工作区位置 + 引导文件
• Gateway 设置（绑定/端口/认证/tailscale）
• 渠道（WhatsApp、Telegram、Discord、Mattermost、Signal、iMessage，以及捆绑的渠道插件如 QQ Bot）
• 守护进程安装（macOS 上为 LaunchAgent，Linux/WSL2 上为 systemd user unit）
• 健康检查和技能选择

它还警告配置的模型是否未知或缺少认证。

认证与模型提供商常见问题

我需要 Claude 或 OpenAI 订阅才能运行吗？

不需要。你既可以使用 API key（Anthropic/OpenAI 等），也可以使用仅本地模型，这样数据留在设备上。订阅（Claude Pro/Max 或 OpenAI Codex）是可选的认证方式。

对于 OpenClaw 中的 Anthropic，实际区别是：

• Anthropic API key：正常的 Anthropic API 计费
• Claude CLI / OpenClaw 中的 Claude 订阅认证：Anthropic 工作人员告诉我们这种用法再次被允许，除非 Anthropic 发布新政策，否则 OpenClaw 将 claude -p 用法视为该集成已认可

对于长期运行的 Gateway 主机，Anthropic API key 仍然是更可预测的设置。OpenAI Codex OAuth 已明确支持用于像 OpenClaw 这样的外部工具。

OpenClaw 还支持其他托管订阅式选项，包括 Qwen Cloud Coding Plan、MiniMax Coding Plan 和 Z.AI / GLM Coding Plan。

文档：Anthropic、OpenAI、Qwen Cloud、MiniMax、GLM Models、本地模型、模型概念。

没有 API key 也能用 Claude Max 订阅吗？

能。

Anthropic 工作人员告诉我们 OpenClaw 风格的 Claude CLI 用法再次被允许，除非 Anthropic 发布新政策，否则 OpenClaw 将 Claude 订阅认证和 claude -p 用法视为该集成已认可。如果想要最可预测的服务端设置，改用 Anthropic API key。

你们支持 Claude 订阅认证（Claude Pro 或 Max）吗？

支持。

Anthropic 工作人员告诉我们这种用法再次被允许，除非 Anthropic 发布新政策，否则 OpenClaw 将 Claude CLI 复用和 claude -p 用法视为该集成已认可。

Anthropic setup-token 仍然是一个受支持的 OpenClaw token 路径，但 OpenClaw 现在在可用时优先使用 Claude CLI 复用和 claude -p。 对于生产或多用户工作负载，Anthropic API key 认证仍然是更安全、更可预测的选择。如果想要 OpenClaw 中其他订阅式托管选项，见 OpenAI、Qwen / Model Cloud、MiniMax 和 GLM Models。

为什么看到来自 Anthropic 的 HTTP 429 rate_limit_error？

这意味着你的 Anthropic quota/rate limit 在当前窗口已耗尽。如果你使用 Claude CLI，等待窗口重置或升级套餐。如果你使用 Anthropic API key，在 Anthropic Console 检查使用/账单并按需提高限制。

如果消息特别指出： Extra usage is required for long context requests，请求正在尝试使用 Anthropic 的 1M 上下文 beta（context1m: true）。只有当你的凭据有资格进行长上下文计费（API key 计费或启用了 Extra Usage 的 OpenClaw Claude-login 路径）时才能工作。

提示：设置一个回退模型，以便提供商被限速时 OpenClaw 能继续回复。 参见模型、OAuth和/gateway/troubleshooting#anthropic-429-extra-usage-required-for-long-context。

AWS Bedrock 支持吗？

支持。OpenClaw 内置了 Amazon Bedrock (Converse) 提供商。若有 AWS 环境标记，OpenClaw 可以自动发现流式/文本 Bedrock 目录并将其合并为隐式的 amazon-bedrock 提供商；否则可以显式启用 plugins.entries.amazon-bedrock.config.discovery.enabled 或添加手动提供商条目。参见 Amazon Bedrock 和模型提供商。如果更喜欢托管密钥流，在 Bedrock 前放置一个 OpenAI 兼容的代理也是有效的选项。

Codex 认证如何工作？

OpenClaw 支持通过 OAuth（ChatGPT 登录）OpenAI Code (Codex)。使用 openai/gpt-5.5 进行常见设置：ChatGPT/Codex 订阅认证加原生 Codex 应用服务器执行。openai-codex/gpt-* 模型引用是遗留配置，由 openclaw doctor --fix 修复。直接 OpenAI API-key 访问仍然可用于非智能体 OpenAI API 表面，以及通过有序的 openai-codex API-key 配置档案用于智能体模型。 参见模型提供商和Onboarding (CLI)。

为什么 OpenClaw 仍然提到 openai-codex？

openai-codex 是 ChatGPT/Codex OAuth 的提供商和认证配置档案 id。旧配置也将其用作模型前缀：

• openai/gpt-5.5 = ChatGPT/Codex 订阅认证带原生 Codex 运行时用于智能体轮次
• openai-codex/gpt-5.5 = 遗留模型路由，由 openclaw doctor --fix 修复
• openai/gpt-5.5 加上有序的 openai-codex API-key 配置档案 = 用于 OpenAI 智能体模型的 API-key 认证
• openai-codex:... = 认证配置档案 id，不是模型引用

如果希望直接 OpenAI Platform 账单/限制路径，设置 OPENAI_API_KEY。如果希望 ChatGPT/Codex 订阅认证，用 openclaw models auth login --provider openai-codex 登录。保持模型引用为 openai/gpt-5.5；openai-codex/* 模型引用是遗留配置，openclaw doctor --fix 会重写。

为什么 Codex OAuth 限制可能与 ChatGPT 网页不同？

Codex OAuth 使用 OpenAI 管理的、与套餐相关的配额窗口。实际上，这些限制可能与 ChatGPT 网站/应用体验不同，即使两者都绑定到同一个账户。

OpenClaw 可以在 openclaw models status 中显示当前可见的提供商使用/配额窗口，但它不会创造或规范化 ChatGPT 网页的权利为直接 API 访问。如果希望直接 OpenAI Platform 账单/限制路径，使用带 API key 的 openai/*。

你们支持 OpenAI 订阅认证（Codex OAuth）吗？

支持。OpenClaw 完全支持 OpenAI Code (Codex) subscription OAuth。OpenAI 明确允许在外部工具/工作流（如 OpenClaw）中使用订阅 OAuth。Onboarding 可以为你运行 OAuth 流。

参见 OAuth、模型提供商和 Onboarding (CLI)。

如何设置 Gemini CLI OAuth？

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-cli/gemini-3-flash-preview
5. 如果请求失败，在 Gateway 主机上设置 GOOGLE_CLOUD_PROJECT 或 GOOGLE_CLOUD_PROJECT_ID

这会在 Gateway 主机上的认证配置档案中存储 OAuth 令牌。详情：模型提供商。

本地模型适合闲聊吗？

通常不适合。OpenClaw 需要大上下文 + 强安全性；小卡片会截断和泄露。如果必须使用，运行本地能构建的最大模型（LM Studio）并参见 /gateway/local-models。更小/量化的模型增加提示注入风险——参见安全。

如何将托管模型流量限制在特定区域？

选择区域固定的端点。OpenRouter 暴露了美国托管的 MiniMax、Kimi 和 GLM 选项；选择美国托管变体以保持数据在区域内。可以通过使用 models.mode: "merge" 仍然列出 Anthropic/OpenAI，这样在尊重你选择的区域提供商的同时，回退保持可用。

我必须要买 Mac Mini 来安装吗？

不需要。OpenClaw 可以在 macOS 或 Linux（Windows 通过 WSL2）上运行。Mac mini 是可选的——有些人买来作为始终在线的宿主，但小型 VPS、家庭服务器或 Raspberry Pi 级别的设备也可以。

你只需要 Mac 用于 macOS 独占工具。对于 iMessage，使用 iMessage 配合 imsg，可在任何登录了 Messages 的 Mac 上运行。如果 Gateway 运行在 Linux 或其他地方，设置 channels.imessage.cliPath 为一个 SSH 包装器，在该 Mac 上运行 imsg。如果还想要其他 macOS 独占工具，在 Mac 上运行 Gateway 或配对 macOS 节点。

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

我需要 Mac mini 来支持 iMessage 吗？

你需要某个 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 来运行 OpenClaw，能不能连接到我的 MacBook Pro？

能。Mac mini 可以运行 Gateway，你的 MacBook Pro 可以连接为节点（伴侣设备）。节点不运行 Gateway——它们提供额外能力，如屏幕/摄像头/画布和该设备上的 system.run。

常见模式：

• Gateway 在 Mac mini 上（始终在线）。
• MacBook Pro 运行 macOS 应用或节点主机并配对到 Gateway。
• 用 openclaw nodes status / openclaw nodes list 查看。

文档：节点、节点 CLI。

可以用 Bun 吗？

不推荐 Bun。我们看到运行时错误，尤其是 WhatsApp 和 Telegram。稳定 Gateway 请使用 Node。

如果仍然想用 Bun 做实验，在非生产 Gateway 上运行，不要启用 WhatsApp/Telegram。

Telegram：allowFrom 里填什么？

channels.telegram.allowFrom 是人类发送者的 Telegram 用户 ID（数字）。不是机器人用户名。

设置只接收数字用户 ID。如果配置中已经有遗留的 @username 条目，openclaw doctor --fix 可以尝试解析它们。

更安全的方式（无需第三方机器人）：

• 给你的机器人发一条私信，然后运行 openclaw logs --follow 读取 from.id。

官方 Bot API：

• 给你的机器人发一条私信，然后调用 https://api.telegram.org/bot<bot_token>/getUpdates 读取 message.from.id。

第三方（隐私性较低）：

• 私信 @userinfobot 或 @getidsbot。

参见 /channels/telegram。

多个人能用同一个 WhatsApp 号码使用不同的 OpenClaw 实例吗？

能，通过多智能体路由。将每个发送者的 WhatsApp 私信（peer kind: "direct"，发送者 E.164 格式如 +15551234567）绑定到不同的 agentId，这样每个人获得自己的工作区和会话存储。回复仍然来自同一个 WhatsApp 账户，私信访问控制（channels.whatsapp.dmPolicy / channels.whatsapp.allowFrom）是每个 WhatsApp 账户全局的。参见多智能体路由和WhatsApp。

我能运行一个“快速聊天”智能体和一个“Opus 用于编程”智能体吗？

能。使用多智能体路由：给每个智能体分配自己的默认模型，然后将入站路由（提供商账户或特定对等方）绑定到每个智能体。示例配置在多智能体路由中。也参见模型和配置。

Homebrew 能在 Linux 上工作吗？

能。Homebrew 支持 Linux（Linuxbrew）。快速设置：

/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。

Hackable git 安装和 npm 安装有什么区别？

• Hackable (git) 安装： 完整源码检出，可编辑，最适合贡献者。你在本地构建，可以打补丁代码/文档。
• npm 安装： 全局 CLI 安装，没有仓库，最适合“直接运行”。更新来自 npm dist-tags。

文档：入门、更新。

以后能在 npm 和 git 安装之间切换吗？

能。当 OpenClaw 已安装时，使用 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 https://openclaw.ai/install.sh | bash -s -- --install-method git
curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method npm

备份提示：备份策略。

应该在笔记本电脑还是 VPS 上运行 Gateway？

简而言之：如果你需要 24/7 可靠性，用 VPS。如果希望最低摩擦且不介意休眠/重启，本地运行。

笔记本电脑（本地 Gateway）

• 好处： 无服务器成本，直接访问本地文件，实时浏览器窗口。
• 坏处： 休眠/网络断开 = 断开连接，操作系统更新/重启会导致中断，必须保持唤醒。

VPS / 云端

• 好处： 始终在线，网络稳定，没有笔记本电脑休眠问题，更容易保持运行。
• 坏处： 通常无头运行（使用截图），只有远程文件访问，必须 SSH 进行更新。

OpenClaw 特别说明： WhatsApp/Telegram/Slack/Mattermost/Discord 都可以在 VPS 上正常工作。唯一的真正权衡是无头浏览器 vs 可见窗口。参见浏览器。

推荐默认： 如果之前有过 Gateway 断连，用 VPS。当你在积极使用 Mac 并希望本地文件访问或使用可见浏览器的 UI 自动化时，本地也很好。

在专用机器上运行 OpenClaw 有多重要？

不是必需的，但推荐用于可靠性和隔离。

• 专用主机（VPS/Mac mini/Pi）： 始终在线，休眠/重启中断更少，权限更清晰，更容易保持运行。
• 共享笔记本/台式机： 对于测试和活跃使用完全没问题，但当机器休眠或更新时会暂停。

如果希望兼得两者，将 Gateway 放在专用主机上，将笔记本配对为节点用于本地屏幕/摄像头/执行工具。参见节点。 安全指导请阅读安全。

最低 VPS 要求和推荐操作系统是什么？

OpenClaw 很轻量。对于基础 Gateway + 一个聊天渠道：

• 绝对最低： 1 vCPU，1GB RAM，约 500MB 磁盘。
• 推荐： 1-2 vCPU，2GB RAM 或更多以获得余量（日志、媒体、多个渠道）。节点工具和浏览器自动化可能资源密集。

操作系统：使用 Ubuntu LTS（或任何现代 Debian/Ubuntu）。Linux 安装路径在它上面测试得最好。

文档：Linux、VPS 托管。

能在 VM 中运行 OpenClaw 吗？有什么要求？

能。将 VM 视为 VPS：需要始终开启、可达，并有足够 RAM 用于 Gateway 和任何启用的渠道。

基准指导：

• 绝对最低： 1 vCPU，1GB RAM。
• 推荐： 如果运行多个渠道、浏览器自动化或媒体工具，2GB RAM 或更多。
• 操作系统： Ubuntu LTS 或其他现代 Debian/Ubuntu。

如果在 Windows 上，WSL2 是最简单的 VM 式设置，工具兼容性最佳。参见 Windows、VPS 托管。如果在 VM 中运行 macOS，参见 macOS VM。

常见问题

安装完成后如何打开仪表盘？

Onboard 完成后，浏览器会自动打开 http://127.0.0.1:18789/。如果没打开，复制终端打印的 URL 在同一台机器上粘贴。远程访问需要配置 Tailscale、SSH 隧道或可信代理。

openclaw onboard 一直卡住怎么办？

先重启 Gateway：openclaw gateway restart，然后运行 openclaw status、openclaw models status 和 openclaw doctor 检查认证和连接。如果 Gateway 是远程的，确保隧道/Tailscale 连接正常。也可以加 --verbose 重新运行安装器查看详细输出。

相关

• 主 FAQ — 涵盖模型、会话、网关、安全等
• 安装概览
• 入门
• 故障排除