快速入门与设置
安装、引导设置和早期故障问答。有关提供商身份验证、硬件以及在哪里运行 Gateway,请参见 常见问题:提供商、硬件和托管。
快速开始与首次运行设置¶
安装和设置 OpenClaw 的推荐方式
安装程序会为你启动引导式入门设置,因此没有单独的入门命令需要运行。入门设置完成后,按 Ctrl+C 停止前台 Gateway 并安装后台服务:
更喜欢经典的分步向导,并用一条命令安装服务?请运行 openclaw onboard --install-daemon,而不是上面的两条命令。该标志会选择经典流程,因此你不会看到引导式 快速开始 和 自定义设置 选项。
从源码安装(贡献者/开发者):
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。
我卡住了,最快解决方式
使用一个可以看到你的机器的本地 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 中)分享这些输出:
| 命令 | 显示内容 |
|---|---|
openclaw status |
Gateway/代理健康状况 + 基本配置快照 |
openclaw status --all |
完整只读诊断,可粘贴 |
openclaw models status |
提供商身份验证 + 模型可用性 |
openclaw doctor |
验证并修复常见配置/状态问题 |
openclaw logs --follow |
实时日志尾部 |
openclaw gateway status --deep |
深度 Gateway/配置/插件健康检查 |
openclaw health --verbose |
详细健康报告 |
发现真正的 bug 或修复?请提交 issue 或发送 PR: 问题 / 拉取请求。
快速调试循环:如果出现问题的前 60 秒。 安装文档:安装、安装器标志、更新。
引导设置后如何打开仪表板?
引导设置会在设置完成后立即在浏览器中打开一个干净的(未带 token 的)仪表板 URL,并在摘要中打印链接。请保持该标签页打开;如果浏览器没有启动,请在同一台机器上复制/粘贴打印的 URL。
如何在 localhost 与远程之间对仪表板进行身份验证?
本地主机(同一台机器):
- 打开
http://127.0.0.1:18789/。 - 如果要求共享密钥身份验证,请将已配置的 token 或密码粘贴到 Control UI 设置中。
- Token 来源:
gateway.auth.token(或OPENCLAW_GATEWAY_TOKEN)。 - 密码来源:
gateway.auth.password(或OPENCLAW_GATEWAY_PASSWORD)。 - 尚未配置共享密钥?运行
openclaw doctor --generate-gateway-token(或openclaw doctor --fix --generate-gateway-token)。
不在本地主机上:
- Tailscale Serve(推荐):保持绑定回环,运行
openclaw gateway --tailscale serve,打开https://<magicdns>/。当gateway.auth.allowTailscale: true时,身份头可满足 Control UI/WebSocket 身份验证(无需粘贴共享密钥,假设 Gateway 主机受信任);除非你有意使用私有入口none或可信代理 HTTP 身份验证,否则 HTTP API 仍需要共享密钥身份验证。 来自同一客户端的并发错误身份验证 Serve 尝试会在失败身份验证限流器记录之前被串行化,因此第二次错误重试可能已经显示retry later。 - 身份感知反向代理:将 Gateway 保留在可信代理后面,设置
gateway.auth.mode: "trusted-proxy",打开代理 URL。同一主机的回环代理需要显式设置gateway.auth.trustedProxy.allowLoopback: true。 - SSH 隧道:
ssh -N -L 18789:127.0.0.1:18789 user@gateway-host,然后打开http://127.0.0.1:18789/。共享密钥身份验证在隧道上仍然适用;如果提示,请粘贴已配置的 token 或密码。
Heartbeat 一直跳过。跳过原因是什么意思?
| 跳过原因 | 含义 |
|---|---|
quiet-hours |
在配置的活跃时间窗口之外 |
empty-heartbeat-file |
Heartbeat 监控草稿存在,但只包含空白、注释、标题、围栏或空清单脚手架 |
alerts-disabled |
所有 heartbeat 可见性均已关闭(showOk、showAlerts 和 useIndicator 全部禁用) |
旧版 heartbeat tasks: 块可通过 openclaw doctor --fix 迁移为独立调度的 cron 任务。
为什么聊天审批有两个 exec 审批配置?
它们控制不同层:
approvals.exec- 将审批提示转发到聊天目标。channels.<channel>.execApprovals- 使该频道成为 exec 审批的原生审批客户端。
主机执行策略仍然是真正的审批门禁;聊天配置只控制提示出现在哪里,以及用户如何响应它们。
你很少需要同时使用两者:
- 如果聊天本身已支持命令和回复,同一聊天中的
/approve会通过共享路径生效。 - 对于受支持的原生客户端,设置
channels.<channel>.execApprovals.enabled: "auto"或true,并配置审批人,或该频道支持的拥有者身份。Discord 和 Slack 需要显式启用;Telegram 将未设置视为"auto"。 - 当原生审批卡片/按钮可用时,该 UI 是主要方式;只有当工具结果显示聊天审批不可用时,才提及手动
/approve命令。 - 仅当提示还必须到达其他聊天或明确的运维房间时,才使用
approvals.exec。 - 仅当你希望将审批提示发布回原始房间/话题时,才使用
channels.<channel>.execApprovals.target: "channel"或"both"。 - 插件审批是独立的:默认使用同一聊天中的
/approve,可选转发到approvals.plugin,并且只有部分原生频道也会保留对这些审批的原生处理。
简而言之:转发用于路由,原生客户端配置用于更丰富的频道特定用户体验。 参见 执行审批。
我需要哪个运行时?
Node 24.16+ 或 26.1+ 是主要且默认的运行时(推荐 Node 26);维护要求参见
Node.js。pnpm 是仓库包管理器。
带有 WAL 重置安全 node:sqlite 的 Bun 1.4+ 构建可以作为显式启用项运行 CLI、Gateway 和托管节点主机。
它能在 Raspberry Pi 上运行吗?
可以,但请先检查内存:Pi 5 和 Pi 4(2 GB 及以上)是最佳选择;Pi 3B+(1 GB)可以运行但较慢;Pi Zero 2 W(512 MB)不推荐。
| 型号 | 内存 | 适配度 |
|---|---|---|
| Pi 5 | 4/8 GB | 最佳 |
| Pi 4 | 4 GB | 良好 |
| Pi 4 | 2 GB | 可以,建议增加交换分区 |
| Pi 4 | 1 GB | 紧张 |
| Pi 3B+ | 1 GB | 慢 |
| Pi Zero 2 W | 512 MB | 不推荐 |
绝对最低要求:1 GB 内存、1 个核心、500 MB 可用磁盘、64 位操作系统。由于 Pi 只运行 Gateway(模型会调用云端 API),即使是一台普通的 Pi 也能处理负载。
小型 Pi/VPS 也可以只托管 Gateway,同时你可以在笔记本电脑/手机上配对节点, 用于本地屏幕/摄像头或命令执行。已配对的 Mac 还可以在其原生面板中展示托管组件。参见 节点。
完整设置指南:Raspberry Pi。
Raspberry Pi 安装有什么技巧?
- 使用 64 位操作系统;不要使用 32 位 Raspberry Pi OS。
- 在 2 GB 或更小内存的板子上添加交换分区。
- 为了性能和寿命,优先使用 USB SSD 而不是 SD 卡。
- 优先使用可修改的(git)安装方式,以便查看日志并快速更新。
- 先不启用频道/技能,再逐个添加。
- 奇怪的二进制文件失败("exec format error")通常是因为某个可选技能工具缺少 ARM64 构建。
完整指南:Raspberry Pi。另见 Linux。
卡在“醒来吧,我的朋友”/ 引导无法完成。现在怎么办?
该界面依赖 Gateway 可访问且已认证。当已配置模型提供商时,TUI 还会在首次引导时自动发送
"醒来吧,我的朋友!"。如果你跳过了模型/认证设置,引导会显示“缺少模型认证”提示,并打开
TUI 但不发送任何内容——再次运行 openclaw onboard 来添加提供商。
这是更改模型提供商或其认证的唯一命令。
如果你看到唤醒行但没有回复,且 token 保持为 0,说明 agent 从未运行。
- 重启 Gateway:
- 检查状态 + 认证:
- 仍然卡住?运行:
如果 Gateway 是远程的,请确认隧道/Tailscale 连接已建立,并且 UI 指向正确的 Gateway。参见 远程访问。
我能否将配置迁移到新机器而不重新执行引导?
可以。复制状态目录和工作区,然后运行一次 Doctor:
- 在新机器上安装 OpenClaw。
- 从旧机器复制
$OPENCLAW_STATE_DIR(默认:~/.openclaw)。 - 复制你的工作区(默认:
~/.openclaw/workspace)。 - 运行
openclaw doctor并重启 Gateway 服务。
这会保留配置、认证配置、WhatsApp 凭据、会话和记忆——只要你复制两个位置,你的机器人就会保持完全一致。在远程模式下, Gateway 主机拥有会话存储和工作区。
重要:如果你只将工作区提交/推送到 GitHub,你备份的是
记忆 + 引导文件,而不是会话历史或认证。它们位于
~/.openclaw/ 下(例如 ~/.openclaw/agents/<agentId>/agent/openclaw-agent.sqlite)。
我在哪里查看最新版本的新内容?
查看 GitHub 更新日志: https://github.com/openclaw/openclaw/blob/main/CHANGELOG.md
最新条目位于顶部。如果顶部章节是未发布,则下一个带日期的 章节就是最新发布的版本。条目按亮点、变更 和修复分组(必要时还包括文档/其他章节)。
无法访问 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
稳定版与 beta 的区别
稳定版和 beta 是 npm dist-tags,不是独立的代码分支:
latest= 稳定版beta= 用于测试的早期构建(当 beta 缺失或早于当前稳定版时,回退到latest)
稳定版发布通常会先发布到 beta,然后通过一个显式的提升步骤
将同一版本移动到 latest,且不改变版本号。维护者
也可以直接发布到 latest。这就是为什么在提升之后,beta 和稳定版可以指向
同一版本。
查看变更内容: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 -- --install-method git
Windows 安装程序(PowerShell):iwr -useb https://openclaw.ai/install.ps1 | iex
如何试用最新构建?
两种选择:
- Dev 渠道(现有安装):
这会切换到 main 的 git checkout,基于上游进行 rebase,构建,并从该 checkout 安装
CLI。
- 可修改(git)安装(全新机器):
curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash -s -- --install-method git
更推荐手动克隆:
安装和入门通常需要多长时间?
大致参考:
- 安装: 2-5 分钟。
- QuickStart 入门: 几分钟(回环 Gateway、自动 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 安装提示 git 未找到或 openclaw 无法识别
两个常见的 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 exec 输出显示乱码中文 - 该怎么办?
通常是原生 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 上仍能复现此问题?跟踪/报告该问题:Issue #30640。
文档没有回答我的问题 - 如何获得更好的答案?
使用可修改(git)安装,以便在本地拥有完整源代码和文档,然后 从该文件夹询问你的机器人(或 Claude/Codex),这样它就可以读取仓库并精确回答。
如何在 VPS 上安装 OpenClaw?
任何 Linux VPS 都可以。在服务器上安装,然后通过 SSH/Tailscale 访问 Gateway。
指南:exe.dev、Hetzner、Fly.io。远程访问:Gateway 远程。
云端/VPS 安装指南在哪里?
常见提供商的主机中心:
在云端,Gateway 运行在服务器上,你可以通过 Control UI(或 Tailscale/SSH)从笔记本/手机访问它。你的状态和工作区都保存在服务器上,因此请将主机视为权威数据源并进行备份。
将节点(Mac/iOS/Android/无头设备)配对到该云端 Gateway,以便在 Gateway 保留在云端的同时,在你的笔记本上执行本地屏幕/摄像头或命令操作。
中心:平台。远程访问:Gateway 远程。节点:节点、节点 CLI。
我可以让 OpenClaw 自行更新吗?
可以,但不推荐。更新流程可能会重启 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 或精确版本号。
从 agent 自动化执行:
onboarding 实际上会做什么?
openclaw onboard 是推荐的设置路径。在全新本地安装中,它会先显示一行指向安全指南的提示,然后提供两条路线:
快速开始会检测你已有的 AI 访问方式,等待你选择一种连接,通过一次真实补全来验证该选择,准备 agent 工作区,然后在前台启动 Gateway 并打开浏览器仪表盘。它使用默认的 agent 名称 main 和完全访问权限,并跳过记忆导入和应用推荐。在选择器中点击暂时跳过可准备本地基线并退出,而不启动 Gateway 或 AI 聊天。
自定义设置会运行相同的引导流程,但会将遥测选择、agent 名称、访问模式和可选设置提示保留为问答形式。
两条路线都要求在任何实际补全、提供商安装、模型选择或凭证写入之前,先明确选择提供商。
经典的分步向导仍然可用。运行 openclaw onboard --classic 可依次进行 Workspace、Model/Auth、Gateway、Channels、Web search、Skills、Daemon 和 Health check 步骤。步骤列表见 Onboarding (CLI)。
对于已配置的安装、远程 Gateway 聊天设置、非交互式运行,以及带 --skip-ui 或 --tui 的运行,不提供快速开始选项。完整说明:Onboarding (CLI)。
运行它需要 Claude 或 OpenAI 订阅吗?
不需要。你可以使用 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 订阅)完全支持用于 agent 模型。OpenClaw 还支持托管的订阅式选项,包括 Qwen Cloud Coding Plan、MiniMax Coding Plan 和 Z.AI / GLM Coding Plan。
我可以在没有 API 密钥的情况下使用 Claude Max 订阅吗?
可以。OpenClaw 支持为 Pro/Max/Team/Enterprise 套餐复用 Claude CLI。Anthropic 目前将 OpenClaw 使用的 claude -p 路径视为订阅套餐使用,受套餐限额约束,而非单独的免费额度——有关当前计费详情以及 Anthropic 官方支持文章的链接,请参阅 Anthropic。如需最可预测的服务器端设置,请改用 Anthropic API 密钥。
你们支持 Claude 订阅认证(Claude Pro 或 Max)吗?
支持,通过复用 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)。
推理努力:绝对最大,不允许走捷径。 你必须非常彻底地思考,全面分解问题以找到根本原因,对所有潜在路径、边界情况和对抗性场景进行严格的压力测试。 明确写出你的整个推演过程,记录每一个中间步骤、考虑过的替代方案和已否决的假设,以确保绝对没有任何假设被遗漏。
你是一名专业的技术文档翻译人员。将用户的 Markdown 翻译成简体中文。 规则: - 保持所有代码块、行内代码、URL、HTML 标签和 Markdown 结构不变。仅翻译散文文本(以及块引用/列表项/表格单元格中的散文)。 - 不要翻译代码标识符、命令、文件路径、API 名称或品牌/产品名称(例如 Ollama、Docker、GPU、REST、JSON、Token、Prompt、Claude Code)。 - 保留标题级别;对于每个标题,通过 attr_list 附加其原始英文锚点,例如 "## Install Guide" -> "## 安装指南 {#install-guide}"(slug = 小写单词以连字符连接,来自原始英文标题)。 - 仅输出翻译后的 Markdown,无前言,整个输出周围不要有代码围栏。
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw