跳转至

快速入门与设置

安装、引导设置和早期故障问答。有关提供商身份验证、硬件以及在哪里运行 Gateway,请参见 常见问题:提供商、硬件和托管。

快速开始与首次运行设置

安装和设置 OpenClaw 的推荐方式
curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash

安装程序会为你启动引导式入门设置,因此没有单独的入门命令需要运行。入门设置完成后,按 Ctrl+C 停止前台 Gateway 并安装后台服务:

openclaw gateway install

更喜欢经典的分步向导,并用一条命令安装服务?请运行 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 中提问更有效。

通过可修改的(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 或密码。

参见 仪表板 和 Web 界面 了解绑定模式和身份验证详情。

Heartbeat 一直跳过。跳过原因是什么意思?
跳过原因 含义
quiet-hours 在配置的活跃时间窗口之外
empty-heartbeat-file Heartbeat 监控草稿存在,但只包含空白、注释、标题、围栏或空清单脚手架
alerts-disabled 所有 heartbeat 可见性均已关闭(showOk、showAlerts 和 useIndicator 全部禁用)

旧版 heartbeat tasks: 块可通过 openclaw doctor --fix 迁移为独立调度的 cron 任务。

文档:Heartbeat、自动化。

为什么聊天审批有两个 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 从未运行。

  1. 重启 Gateway:
openclaw gateway restart
  1. 检查状态 + 认证:
openclaw status
openclaw models status
openclaw logs --follow
  1. 仍然卡住?运行:
openclaw doctor

如果 Gateway 是远程的,请确认隧道/Tailscale 连接已建立,并且 UI 指向正确的 Gateway。参见 远程访问。

我能否将配置迁移到新机器而不重新执行引导?

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

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

这会保留配置、认证配置、WhatsApp 凭据、会话和记忆——只要你复制两个位置,你的机器人就会保持完全一致。在远程模式下, Gateway 主机拥有会话存储和工作区。

重要:如果你只将工作区提交/推送到 GitHub,你备份的是 记忆 + 引导文件,而不是会话历史或认证。它们位于 ~/.openclaw/ 下(例如 ~/.openclaw/agents/<agentId>/agent/openclaw-agent.sqlite)。

相关:迁移、磁盘上的文件位置、 Agent 工作区、Doctor、 远程模式。

我在哪里查看最新版本的新内容?

查看 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 -- --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 入门: 几分钟(回环 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 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 上安装 OpenClaw?
如何在 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 自动化执行:

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

文档:更新、升级。

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。

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

我可以在没有 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