快速开始与设置

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

安装程序会直接引导你完成设置流程，因此无需再单独运行 onboarding 命令。当引导流程结束后，按 Ctrl+C 停止前台 Gateway，然后安装后台服务：

openclaw gateway install

更喜欢经典的分步向导，并希望一条命令同时完成服务安装？直接运行 openclaw onboard --install-daemon，无需再执行上面两条命令。该标志会选择经典流程，因此你不会看到引导式 Quick start（快速开始）和 Custom setup（自定义设置）这样的选择。

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

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

尚未进行全局安装？请改为运行 pnpm openclaw onboard。如果缺少 Control UI 资源，引导流程会尝试自行构建，必要时回退到 pnpm ui:build。

• 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

请代理逐步规划并监督修复过程，然后只执行必要的命令——更小的 diff 更容易审计。

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

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

快速调试循环：如果出现问题，最初的 60 秒。 安装文档：安装、安装器标志、更新。

引导流程在设置完成后会立即在浏览器中打开一个干净的（不含令牌的）仪表盘 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（推荐）：保持绑定 loopback，运行 openclaw gateway --tailscale serve，打开 https://<magicdns>/。设置 gateway.auth.allowTailscale: true 后，身份头即可满足 Control UI/WebSocket 认证（无需粘贴共享密钥，但假定网关主机可信）；HTTP API 仍需要共享密钥认证，除非你特意使用 private-ingress none 或 trusted-proxy HTTP 认证。 来自同一客户端的并发错误认证 Serve 尝试会在失败认证限制器记录之前被串行化，因此第二次错误重试就可能显示 retry later。
• 感知身份的反向代理：将 Gateway 放在受信任的代理后面，设置 gateway.auth.mode: "trusted-proxy"，然后打开代理 URL。同一主机上的 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/。共享密钥认证在隧道上仍然有效；如果提示，请粘贴配置好的令牌或密码。

有关绑定模式和认证详情，请参阅 Dashboard 和 Web 界面。

较旧的心跳 tasks: 配置块会通过 openclaw doctor --fix 迁移为独立调度的 cron 任务。

文档：Heartbeat、Automation。

它们控制的是不同层面：

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

Stable 和 beta 是 npm dist-tags，并非独立的代码分支：

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

稳定版通常先发布到 beta，然后通过显式的提升步骤将该版本提升到 latest，版本号不变。 维护者也可以直接发布到 latest。这就是为什么提升后 beta 和 stable 可能指向同一版本。

查看变更内容：CHANGELOG.md。

有关一键安装命令以及 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）：iwr -useb https://openclaw.ai/install.ps1 | iex

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

两种方式：

1. Dev 渠道（现有安装）：

openclaw update --channel dev

这会切换到 main 的 git checkout，基于上游进行 rebase，然后构建并从该 checkout 安装 CLI。

1. 可修改式（git）安装（新机器）：

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

更喜欢手动克隆：

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

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

大致参考：

• 安装： 2-5 分钟。
• QuickStart 初始化： 几分钟（回环网关、自动 Token、默认工作区）。
• 高级/完整初始化： 如果提供商登录、渠道配对、守护进程安装、网络下载或技能需要额外设置，所需时间会更长。

向导会预先显示此时间线。可跳过可选步骤，稍后使用 openclaw configure 再回来配置。

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

使用 --verbose 重新运行：

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

install.ps1 没有专用的 verbose 开关；请改用 Set-PSDebug -Trace 1 / -Trace 0 包裹运行。完整标志参考：安装程序标志。

两个常见的 Windows 问题：

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

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

2) 安装后无法识别 openclaw

• 你的 npm 全局 bin 文件夹不在 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）安装，这样你就可以在本地获得完整源代码和文档，然后在该文件夹中向你的机器人（或 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 即可。

包含常见提供商的托管中心：

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

在云端，Gateway 运行在服务器上，你可以通过 Control UI（或 Tailscale/SSH）从笔记本电脑/手机访问它。你的状态 + 工作区保存在服务器上，因此请将主机视为唯一事实来源并做好备份。

将节点（Mac/iOS/Android/headless）配对到该云 Gateway，即可在 Gateway 保持云端运行的同时，在你的笔记本电脑上执行本地屏幕/相机或命令。

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

可以，但不推荐。更新流程可能会重启 Gateway（中断当前会话），可能需要干净的 git checkout，并且可能会提示确认。更安全的做法是由操作员从 shell 运行更新。

openclaw update
openclaw update status
openclaw update --channel beta
openclaw update --tag 2026.9.3
openclaw update --no-restart

--channel 接受 stable、extended-stable、beta 或 dev。--tag 接受 npm dist-tag 或精确版本号。

通过智能体自动化：

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

文档：更新、更新指南。

openclaw onboard 是推荐的设置路径。在全新的本地安装中，它会先显示一行指向安全指南的提示，然后提供两条路径：

• 快速开始会检测你已有的 AI 访问方式，等待你选择一种连接，通过一次真实的补全来验证该选择，准备智能体工作区，然后在前台启动 Gateway 并打开浏览器仪表盘。它使用默认智能体名称 main 和完全访问权限，并跳过记忆导入和应用推荐。在选择器中选择暂时跳过即可准备本地基线并退出，而不会启动 Gateway 或 AI 聊天。
• 自定义设置运行相同的引导流程，但会将遥测选择、智能体名称、访问模式以及可选设置提示保留为问答形式。

两条路径都要求先明确选择提供商，然后才会进行任何实际补全、提供商安装、模型选择或凭据写入。

经典的逐步向导仍然可用。运行 openclaw onboard --classic 可查看其 Workspace、Model/Auth、Gateway、Channels、Web search、Skills、Daemon 和 Health check 步骤。步骤列表见 Onboarding (CLI)。

对于已配置的安装、远程 Gateway 聊天设置、非交互式运行，或使用 --skip-ui 或 --tui 的运行，不提供快速开始选项。 完整说明：Onboarding (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)、本地模型、模型。

可以。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 认证仍然是一条受支持的 token 路径，但 OpenClaw 更倾向于在可用时复用 Claude CLI 和 claude -p。对于生产环境或多用户工作负载，Anthropic API 密钥仍然是更安全、更可预测的选择。其他订阅式托管选项：OpenAI、Qwen Cloud、MiniMax、Z.AI (GLM)。