古法编程

Appearance

本页汇集了 OpenClaw 最常见的问题与解答，涵盖快速安装、引导步骤、模型认证（Anthropic/OpenAI/Gemini）、多 Agent 路由、WhatsApp/Telegram 配置、VPS 部署和 Windows 常见坑。遇到问题先查这里，大概率一分钟内就能找到答案。

常见问题（FAQ） ​

快速解答加深度故障排查，覆盖本地开发、VPS、多 agent、OAuth/API Key、模型降级等真实场景。运行时诊断详见故障排查，完整配置参考见配置文档。

出问题了先做这 7 步 ​

  1. 快速状态检查（第一步）

    bash
    openclaw status

    本地快速摘要：系统 + 更新、gateway/服务可达性、agent/会话、提供商配置 + 运行时问题（gateway 可达时）。

  2. 可分享的诊断报告

    bash
    openclaw status --all

    只读诊断，自动脱敏 token，可安全分享给别人排查。

  3. daemon + 端口状态

    bash
    openclaw gateway status

    显示监督进程运行状态 vs RPC 可达性、探测目标 URL、以及服务可能使用的配置。

  4. 深度探测

    bash
    openclaw status --deep

    运行实时 gateway 健康探测，包括支持的渠道探测（需要可达的 gateway）。

  5. 追踪最新日志

    bash
    openclaw logs --follow

    如果 RPC 挂了，回退到：

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

  6. 运行 doctor（自动修复）

    bash
    openclaw doctor

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

  7. Gateway 快照

    bash
    openclaw health --json
openclaw health --verbose

    向运行中的 gateway 请求完整快照（仅 WebSocket）。

快速开始与初次安装 ​

卡住了？最快解套方法

用一个能看到你机器的本地 AI agent。这比在 Discord 求助有效得多——大多数"我卡住了"的问题是本地配置或环境问题，远程帮助者看不到。

推荐：

给 agent 提供完整源码（git 安装方式）：

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

先跑这几个命令（求助时把输出一起分享）：

bash
openclaw status
openclaw models status
openclaw doctor

推荐安装和设置方式

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

向导会自动构建 UI 资源。引导完成后，Gateway 默认运行在端口 18789。

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

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

心跳一直跳过？skip 原因含义

常见心跳跳过原因：

  • quiet-hours：在配置的活跃时段窗口之外
  • empty-heartbeat-file：HEARTBEAT.md 存在但只有空白或仅标题骨架
  • no-tasks-due：HEARTBEAT.md 处于任务模式但没有到期任务
  • alerts-disabled：所有心跳可见性都关闭了

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

引导程序实际做了什么？

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

  • 模型/认证设置（提供商 OAuth、API Key、Anthropic 旧版 setup-token、LM Studio 等本地模型）
  • 工作区位置 + bootstrap 文件
  • Gateway 设置（bind/端口/认证/tailscale）
  • 渠道配置（WhatsApp、Telegram、Discord、Mattermost、Signal、iMessage 等）
  • Daemon 安装（macOS launchd；Linux/WSL2 systemd）
  • 健康检查和技能选择

我需要 Claude 或 OpenAI 订阅吗？

不需要。可以用 API Key（Anthropic/OpenAI/其他）或纯本地模型，数据留在本地。订阅是可选方式。

关于 Anthropic：使用 Claude 订阅在 OpenClaw 中运行需要额外付费（Extra Usage），从 2026 年 4 月 4 日起生效。如果不想走 Extra Usage 路径，用 Anthropic API Key 即可。

OpenClaw 也支持其他订阅风格选项：Qwen Cloud Coding Plan、MiniMax Coding Plan、Z.AI/GLM Coding Plan。

能在 Raspberry Pi 上跑吗？

可以。Gateway 很轻量——个人使用 512MB-1GB RAM、1 核、约 500MB 磁盘就够了，Raspberry Pi 4 可以跑。

建议用 64 位系统，Node >= 22。用 git hackable 安装更方便查日志和快速更新。

怎么看最新版本的更新内容？

查 GitHub changelog：https://github.com/openclaw/openclaw/blob/main/CHANGELOG.md

最新条目在最上面。如果顶部标着 Unreleased，往下找第一个带日期的节。

安装卡住了怎么办？

重跑安装脚本加 verbose：

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

Windows 安装报 git not found 或 openclaw 未识别

两个常见 Windows 问题：

  1. npm error spawn git / git not found：安装 Git for Windows，确保 git 在 PATH 里，重开 PowerShell。

  2. openclaw 安装后不识别：npm global bin 目录不在 PATH。检查：

    powershell
    npm config get prefix

    把该目录加入用户 PATH，重开 PowerShell。

推荐用 WSL2 获得更顺畅的 Windows 体验。

Windows 执行命令输出中文乱码

在 PowerShell 里先运行：

powershell
chcp 65001
[Console]::InputEncoding = [System.Text.UTF8Encoding]::new($false)
[Console]::OutputEncoding = [System.Text.UTF8Encoding]::new($false)
$OutputEncoding = [System.Text.UTF8Encoding]::new($false)

然后重启 Gateway：

powershell
openclaw gateway restart

模型与认证 ​

为什么 Anthropic 报 HTTP 429 rate_limit_error？

说明当前窗口内 Anthropic 配额/速率限制已耗尽。使用 Claude CLI 的话等窗口重置或升级计划；使用 API Key 的话查 Anthropic Console 看用量。

如果错误是 Extra usage is required for long context requests，说明请求在尝试使用 1M 上下文 beta（context1m: true）。这需要你的凭证支持长上下文计费。

提示：设置降级模型（fallback model），这样当某个提供商被限速时，OpenClaw 仍能继续回复。

支持 AWS Bedrock 吗？

支持。OpenClaw 内置 Amazon Bedrock（Converse）提供商。有 AWS 环境标记时，OpenClaw 可以自动发现 Bedrock 目录，或显式启用：

plugins.entries.amazon-bedrock.config.discovery.enabled = true

Codex 认证怎么工作？

OpenClaw 通过 OAuth（ChatGPT 登录）支持 OpenAI Code（Codex）。引导程序可以运行 OAuth 流并自动设置默认模型为 openai-codex/gpt-5.4。

如何配置 Gemini CLI OAuth？

Gemini CLI 使用插件认证流，不是在 openclaw.json 里写 client id。用 Gemini API 提供商代替：

  1. 启用插件：openclaw plugins enable google
  2. 运行：openclaw onboard --auth-choice gemini-api-key
  3. 设置模型：google/gemini-3.1-pro-preview

本地模型可以用于日常聊天吗？

通常不行。OpenClaw 需要大上下文 + 强安全性；小模型会截断上下文，增加提示注入风险。如果必须本地运行，用 LM Studio 跑最大的模型。参见 本地模型文档。

硬件与部署 ​

必须买 Mac Mini 才能用吗？

不用。OpenClaw 可以在 macOS 或 Linux 上运行（Windows 用 WSL2）。小型 VPS、家用服务器或树莓派级别的机器都够用。

只有用到 macOS 独有工具时才需要 Mac。iMessage 推荐用 BlueBubbles——BlueBubbles server 在 Mac 上跑，Gateway 可以在 Linux 或其他地方跑。

iMessage 支持需要 Mac Mini 吗？

你需要某台登录了 Messages 的 macOS 设备，不一定是 Mac Mini，任何 Mac 都行。推荐用 BlueBubbles：

  • Gateway 运行在 Linux/VPS
  • BlueBubbles server 运行在任意登录了 Messages 的 Mac 上

能用 Bun 吗？

不推荐。尤其是 WhatsApp 和 Telegram 会出现运行时 bug。Gateway 请用 Node。

怎么在 localhost 和远端认证控制台（dashboard）？

本地（同机器）：

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

不在 localhost 时：

  • Tailscale Serve（推荐）：保持 bind loopback，运行 openclaw gateway --tailscale serve，打开 https://<magicdns>/。如果 gateway.auth.allowTailscale 为 true，身份 Header 满足控制 UI/WebSocket 认证（无需粘贴共享密钥，假设 gateway 宿主机可信）；HTTP API 仍需共享密钥认证。
  • Tailnet bind：运行 openclaw gateway --bind tailnet --token "<token>"（或配置密码认证），打开 http://<tailscale-ip>:18789/，在 dashboard 设置中粘贴匹配的共享密钥。
  • 身份感知反向代理：将 Gateway 置于非 loopback trusted proxy 后面，配置 gateway.auth.mode: "trusted-proxy"，然后打开代理 URL。
  • SSH 隧道：ssh -N -L 18789:127.0.0.1:18789 user@host，然后打开 http://127.0.0.1:18789/。共享密钥认证仍在隧道上生效。

详见控制台文档。

为什么 exec approval 有两个配置？

它们控制不同层级：

  • approvals.exec：将审批提示转发到聊天目的地
  • channels.<channel>.execApprovals：让该渠道作为 exec approval 的原生审批客户端

宿主机 exec 策略仍然是真正的审批关卡，聊天配置只控制审批提示出现的位置和响应方式。

大多数场景不需要同时配置两者：

  • 如果聊天已支持命令和回复，同渠道 /approve 通过共享路径就能工作。
  • 如果支持的原生渠道能安全推断审批者，当 channels.<channel>.execApprovals.enabled 未设置或为 "auto" 时，OpenClaw 会自动启用 DM 优先的原生审批。
  • 只在提示必须同时转发到其他聊天或明确的运维房间时才用 approvals.exec。
  • 只在明确希望审批提示发回原始房间/话题时才设置 channels.<channel>.execApprovals.target: "channel" 或 "both"。

简而言之：转发配置管路由，原生客户端配置管渠道特定的 UX 体验。详见 Exec 审批文档。

渠道配置 ​

Telegram allowFrom 填什么？

填发件人的 Telegram 数字 user ID，不是 bot 用户名。

获取方式（推荐，无需第三方 bot）：

bash
# DM 你的 bot 后追踪日志
openclaw logs --follow  # 查看 from.id

或用官方 Bot API：

https://api.telegram.org/bot<bot_token>/getUpdates

看 message.from.id。

一个 WhatsApp 号码可以给多人用不同的 OpenClaw 实例吗？

可以，用多 agent 路由。把每个发件人的 WhatsApp DM 绑定到不同的 agentId，每个人有自己独立的工作区和会话存储。回复仍从同一个 WhatsApp 账号发出。

详见 多 Agent 路由。

能同时跑一个"快聊 agent"和一个"Opus 编程 agent"吗？

可以。用多 agent 路由：给每个 agent 设置自己的默认模型，再把入站路由（提供商账号或特定对端）绑定到各个 agent。

数据与迁移 ​

能把配置迁移到新机器（Mac Mini）而不重新引导吗？

可以。复制状态目录和工作区，然后跑一次 Doctor。步骤：

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

这会保留配置、认证配置、WhatsApp 凭证、会话和记忆。

注意：如果你只把工作区推送到 GitHub，只备份了记忆 + bootstrap 文件，不包含会话历史或认证（这些在 ~/.openclaw/ 下）。

常见问题 ​

Q: 我的 OpenClaw 每次重启都要重新配置，有没有快速保存配置的方法？

A: 配置存在 ~/.openclaw/openclaw.json，只要不删这个文件，重启后配置完全保留。如果想备份，运行 openclaw backup create 生成完整存档文件。

Q: 能用 Bun 代替 Node 运行 Gateway 吗？

A: 官方不推荐。Bun 在 WhatsApp 和 Telegram 渠道上已知存在运行时 bug，生产环境请坚持用 Node >= 22。

Q: 报错 openclaw gateway status 显示 RPC 不可达，怎么快速修复？

A: 先运行 openclaw doctor（自动修复大多数配置问题），然后 openclaw gateway restart。如果仍有问题，用 openclaw logs --follow 查看实时日志定位具体错误。

友情链接： 能跑吗 · 打工算 · 车主算 · 开发工具 · 人工不智能

Copyright © 2026 古法编程 | 蜀ICP备2021007188号 | 关于本站 | 隐私政策