跳到主要内容

帮助

常见问题

针对实际设置（本地开发、VPS、多智能体、OAuth/API 密钥、模型故障转移）的快速答案和深度故障排除。关于运行时诊断，请参阅 故障排除。关于完整的配置参考，请参阅 配置。

术语约定：Agent → 智能体（agent），Channel → 频道（channel），Gateway → 网关（Gateway）。

目录​

如果出现问题，前 60 秒​

  1. 快速状态（首先检查）

    复制

    openclaw status

    快速本地摘要：操作系统 + 更新、网关/服务可达性、智能体/会话、提供商配置 + 运行时问题（当网关可达时）。

  2. 可粘贴的报告（可安全分享）

    复制

    openclaw status --all

    只读诊断，包含日志尾部（令牌已脱敏）。

  3. 守护进程 + 端口状态

    复制

    openclaw gateway status

    显示监督器运行时与 RPC 可达性、探测目标 URL，以及服务可能使用的配置。

  4. 深度探测

    复制

    openclaw status --deep

    运行网关健康检查 + 提供商探测（需要可达的网关）。参见 健康状态。

  5. 跟踪最新日志

    复制

    openclaw logs --follow

    如果 RPC 宕机，回退到：

    复制

    tail -f "$(ls -t /tmp/openclaw/openclaw-*.log | head -1)"

    文件日志与服务日志是分开的；参见 日志记录 和 故障排除。

  6. 运行医生（修复）

    复制

    openclaw doctor

    修复/迁移配置/状态 + 运行健康检查。参见 医生。

  7. 网关快照

    复制

    openclaw health --json
    openclaw health --verbose   # 显示目标 URL + 错误时的配置路径

    向正在运行的网关请求完整快照（仅限 WebSocket）。参见 健康状态。

快速入门和首次运行设置​

我被卡住了，最快摆脱困境的方法是什么​

使用一个能看到你机器的本地 AI 智能体。这比在 Discord 上提问有效得多，因为大多数“我被卡住了”的情况是本地配置或环境问题，远程助手无法检查。

这些工具可以读取仓库、运行命令、检查日志，并帮助修复机器级别的设置（PATH、服务、权限、认证文件）。通过可破解（git）安装方式，给它们完整的源代码检出：

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

这会从 git 检出安装 OpenClaw，这样智能体就能读取代码 + 文档，并推理你正在运行的确切版本。你以后随时可以通过重新运行不带 --install-method git 的安装程序切换回稳定版。提示：让智能体规划并监督修复（逐步进行），然后只执行必要的命令。这样可以使更改更小，更容易审核。如果你发现了真正的错误或修复，请提交 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）/智能体（agent）健康状态 + 基本配置的快速快照。
  • openclaw models status：检查提供商认证 + 模型可用性。
  • openclaw doctor：验证并修复常见的配置/状态问题。

其他有用的 CLI 检查：openclaw status --all, openclaw logs --follow, openclaw gateway status, openclaw health --verbose。快速调试循环：如果出现问题，前 60 秒。安装文档：安装, 安装程序标志, 更新。

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

仓库推荐从源代码运行并使用引导向导：

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

向导也可以自动构建 UI 资源。引导完成后，你通常在端口 18789 上运行网关。从源代码（贡献者/开发者）：

git clone https://github.com/openclaw/openclaw.git
cd openclaw
pnpm install
pnpm build
pnpm ui:build # 首次运行时自动安装 UI 依赖
openclaw onboard

如果你还没有全局安装，可以通过 pnpm openclaw onboard 运行。

完成引导后如何打开仪表板​

向导会在引导后立即用干净的（非令牌化的）仪表板 URL 打开你的浏览器，并在摘要中打印链接。保持该标签页打开；如果它没有启动，在同一台机器上复制/粘贴打印的 URL。

如何在本地主机与远程环境下验证仪表板（令牌）​

本地主机（同一台机器）：

  • 打开 http://127.0.0.1:18789/。
  • 如果要求认证，将 gateway.auth.token（或 OPENCLAW_GATEWAY_TOKEN）中的令牌粘贴到控制 UI 设置中。
  • 从网关主机检索：openclaw config get gateway.auth.token（或生成一个：openclaw doctor --generate-gateway-token）。

不在本地主机上：

  • Tailscale Serve（推荐）：保持绑定环回，运行 openclaw gateway --tailscale serve，打开 https:///。如果 gateway.auth.allowTailscale 是 true，身份标头满足控制 UI/WebSocket 认证（无需令牌，假设网关主机可信）；HTTP API 仍需要令牌/密码。
  • Tailnet 绑定：运行 openclaw gateway --bind tailnet --token ""，打开 http://<tailscale-ip>:18789/，在仪表板设置中粘贴令牌。
  • SSH 隧道：ssh -N -L 18789:127.0.0.1:18789 user@host 然后打开 http://127.0.0.1:18789/ 并在控制 UI 设置中粘贴令牌。

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

我需要什么运行时​

需要 Node >= 22。推荐使用 pnpm。不推荐将 Bun 用于网关。

它能在树莓派上运行吗​

是的。网关是轻量级的 - 文档列出 512MB-1GB 内存、1 核和大约 500MB 磁盘空间就足够个人使用，并指出树莓派 4 可以运行它。如果你想要额外的余量（日志、媒体、其他服务），推荐 2GB，但这不是硬性最低要求。提示：一个小型 Pi/VPS 可以托管网关，你可以在你的笔记本电脑/手机上配对节点以访问本地屏幕/摄像头/画布或执行命令。参见 节点。

树莓派安装有什么技巧吗​

简短版本：它能工作，但预计会有粗糙的边缘。

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

文档：Linux, 安装。

它卡在“醒来吧，我的朋友”/引导无法孵化。现在怎么办​

该屏幕依赖于网关可达且已认证。TUI 也会在首次孵化时自动发送“Wake up, my friend!”。如果你看到那一行没有回复且令牌保持为 0，说明智能体从未运行。

  1. 重启网关：
openclaw gateway restart
  1. 检查状态 + 认证：
openclaw status
openclaw models status
openclaw logs --follow
  1. 如果仍然挂起，运行：
openclaw doctor

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

我能将我的设置迁移到新机器（Mac mini）而无需重新引导吗​

是的。复制状态目录和工作区，然后运行一次 Doctor。这能让你的机器人“完全一样”（内存、会话历史、认证、频道状态），只要你复制两个位置：

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

这将保留配置、认证配置文件、WhatsApp 凭据、会话和内存。如果你处于远程模式，请记住网关主机拥有会话存储和工作区。重要：如果你只将工作区提交/推送到 GitHub，你备份的是内存 + 引导文件，但不是会话