故障排除 🔧

当 OpenClaw 表现异常时，这里是如何修复它的方法。

如果您只是想要一个快速分类方案，请从 FAQ 的 前 60 秒 开始。本页面深入探讨运行时故障和诊断。

特定提供者的快捷方式：/channels/troubleshooting

状态和诊断

快速分类命令（按顺序）：

分享输出： 优先使用 openclaw status --all（它会编辑令牌）。如果您粘贴 openclaw status，请考虑先设置 OPENCLAW_SHOW_SECRETS=0（令牌预览）。

另请参阅：健康检查 和 日志。

常见问题

未找到提供者 "anthropic" 的 API 密钥

这意味着 代理的身份验证存储为空 或缺少 Anthropic 凭据。 身份验证是 按代理 的，所以新代理不会继承主代理的密钥。

修复选项：

• 重新运行入门设置并为该代理选择 Anthropic。
• 或在 网关主机 上粘贴一个设置令牌：
  bash

  openclaw models auth setup-token --provider anthropic

• 或从主代理目录复制 auth-profiles.json 到新代理目录。

验证：

openclaw models status

OAuth 令牌刷新失败（Anthropic Claude 订阅）

这意味着存储的 Anthropic OAuth 令牌已过期且刷新失败。 如果您使用的是 Claude 订阅（没有 API 密钥），最可靠的修复方法是 切换到 Claude Code 设置令牌 或在 网关主机 上重新同步 Claude Code CLI OAuth。

推荐（设置令牌）：

# 在网关主机上运行（运行 Claude Code CLI）
openclaw models auth setup-token --provider anthropic
openclaw models status

如果您在其他地方生成了令牌：

openclaw models auth paste-token --provider anthropic
openclaw models status

如果您希望保持 OAuth 重用： 在网关主机上使用 Claude Code CLI 登录，然后运行 openclaw models status 将刷新的令牌同步到 OpenClaw 的身份验证存储中。

更多详细信息：Anthropic 和 OAuth。

控制 UI 在 HTTP 上失败（"需要设备身份" / "连接失败"）

如果您通过普通 HTTP 打开仪表板（例如 http://\<lan-ip\>:18789/ 或 http://\<tailscale-ip\>:18789/），浏览器在 非安全上下文 中运行并 阻止 WebCrypto，因此无法生成设备身份。

修复：

• 优先通过 Tailscale Serve 使用 HTTPS。
• 或在网关主机上本地打开：http://127.0.0.1:18789/。
• 如果您必须保持在 HTTP 上，请启用 gateway.controlUi.allowInsecureAuth: true 并 使用网关令牌（仅令牌；无设备身份/配对）。参见 控制 UI。

Web UI 显示 "disconnected (1008): pairing required" 错误

当您访问 Web UI 时，可能会遇到以下错误：

disconnected (1008): pairing required

这个错误通常出现在 容器化部署（Docker、Kubernetes）中。

详细说明和解决方案： 见 配对要求故障排除

快速修复（Docker）：

docker compose run --rm openclaw-cli config set gateway.controlUi.allowInsecureAuth true
docker compose restart openclaw-gateway

快速修复（本地）：

openclaw config set gateway.controlUi.allowInsecureAuth true
openclaw gateway restart

Web UI 显示 "disconnected (1006): no reason" 错误

当您访问 Web 网关管理页面时，可能会遇到以下错误：

disconnected (1006): no reason

问题原因：

WebSocket 错误码 1006 表示“异常关闭”，连接在没有收到正常关闭帧的情况下断开。

常见原因包括：

1. 浏览器缓存旧 token：更新版本后，浏览器 localStorage 中的旧设备认证数据与新版网关不兼容
2. 网关进程崩溃/重启：网关突然退出，没有机会发送正常的关闭帧（常见于 Docker 部署）
3. 网络中断：容器网络问题、反向代理超时或资源限制导致连接被强制断开

场景 1：更新后首次连接失败

如果您刚更新了 OpenClaw 版本，最可能的原因是浏览器缓存了旧的设备认证数据。

解决方案：

方法 1：清除浏览器本地存储（推荐）

方法 2：使用无痕/隐私模式

在新的无痕浏览窗口打开 Web UI，这样会使用全新的本地存储。

• Chrome：Ctrl+Shift+N（Windows/Linux）或 Cmd+Shift+N（macOS）
• Firefox：Ctrl+Shift+P（Windows/Linux）或 Cmd+Shift+P（macOS）
• Safari：文件 → 新建私密窗口

方法 3：清除站点数据（快捷方式）

Ctrl+Shift+Delete（Windows/Linux）或 Cmd+Shift+Delete（macOS），然后：

• 时间范围选择“全部时间”
• 仅勾选“Cookie 和站点数据”
• 点击清除

场景 2：Docker 部署中频繁出现 1006 错误

如果您使用 Docker 部署，且 清除浏览器缓存后仍然经常遇到 1006 错误，问题很可能是网关进程不稳定。

诊断步骤：

步骤 1：检查容器状态和重启次数

# 查看容器状态
docker compose ps

# 查看容器重启次数
docker inspect openclaw-gateway --format='{{.RestartCount}}'

# 如果重启次数 > 0，说明容器曾经崩溃过

步骤 2：查看容器日志

# 查看最近日志
docker compose logs -f openclaw-gateway --tail 100

# 检查是否有错误或崩溃信息
docker compose logs openclaw-gateway 2>&1 | grep -i "error\|crash\|killed\|oom\|fatal"

步骤 3：检查资源使用

# 查看容器资源使用
docker stats openclaw-gateway --no-stream

# 检查是否接近内存限制

常见原因和解决方案：

修复建议：

1. 增加容器资源限制（如果使用了限制）

在 docker-compose.yml 中调整：

services:
  openclaw-gateway:
    # ... 其他配置 ...
    deploy:
      resources:
        limits:
          memory: 1G  # 适当增加内存限制

2. 确保数据卷正确挂载

# 检查数据目录是否存在且有正确权限
ls -la ${OPENCLAW_CONFIG_DIR:-./data/.openclaw}

# 确保容器内用户有写入权限
docker compose exec openclaw-gateway ls -la /home/node/.openclaw

3. 检查网关健康状态

# 在容器内运行健康检查
docker compose exec openclaw-gateway node dist/index.js health --json

场景 3：使用反向代理时的 1006 错误

如果您在 Nginx、Caddy 或 Traefik 等反向代理后面运行网关，WebSocket 连接可能因代理配置不当而断开。

Nginx 配置示例：

location / {
    proxy_pass http://127.0.0.1:18789;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
    
    # 关键：增加超时时间防止空闲断开
    proxy_read_timeout 86400s;
    proxy_send_timeout 86400s;
}

Caddy 配置示例：

your-domain.com {
    reverse_proxy localhost:18789 {
        # WebSocket 支持是自动的
        # 但可以显式设置超时
        transport http {
            read_timeout 0
        }
    }
}

检查要点：

• 确保代理正确传递 WebSocket 升级头（Upgrade 和 Connection）
• 将空闲超时设置为较长时间或禁用
• 确保 X-Forwarded-* 头正确传递

预防建议：

• 每次大版本更新后，如果遇到连接问题，优先尝试清除浏览器本地存储
• Docker 部署时，建议启用容器日志持久化，便于排查问题
• 使用反向代理时，确保 WebSocket 配置正确

CI Secrets Scan 失败

这意味着 detect-secrets 找到了基准线中尚未包含的新候选项目。 请遵循 秘密扫描。

服务已安装但没有运行

如果网关服务已安装但进程立即退出，服务 可能显示为"已加载"但实际上没有运行任何东西。

检查：

openclaw gateway status
openclaw doctor

Doctor/服务将显示运行时状态（PID/上次退出）和日志提示。

日志：

• 优先使用：openclaw logs --follow
• 文件日志（始终）：/tmp/openclaw/openclaw-YYYY-MM-DD.log（或您配置的 logging.file）
• macOS LaunchAgent（如果已安装）：$OPENCLAW_STATE_DIR/logs/gateway.log 和 gateway.err.log
• Linux systemd（如果已安装）：journalctl --user -u OpenClaw-gateway[-\<profile\>].service -n 200 --no-pager
• Windows：schtasks /Query /TN "OpenClaw Gateway (\<profile\>)" /V /FO LIST

启用更多日志记录：

• 提高文件日志详细程度（持久化 JSONL）：
  json

  { "logging": { "level": "debug" } }

• 提高控制台详细程度（仅 TTY 输出）：
  json

  { "logging": { "consoleLevel": "debug", "consoleStyle": "pretty" } }

• 快速提示：--verbose 仅影响 控制台 输出。文件日志仍由 logging.level 控制。

有关格式、配置和访问的完整概述，请参见 /logging。

"网关启动被阻止：设置 gateway.mode=local"

这意味着配置存在但 gateway.mode 未设置（或不是 local），所以 网关拒绝启动。

修复（推荐）：

• 运行向导并将网关运行模式设置为 本地：
  bash

  openclaw configure

• 或直接设置：
  bash

  openclaw config set gateway.mode local

如果您打算运行远程网关：

• 设置远程 URL 并保持 gateway.mode=remote：
  bash

  openclaw config set gateway.mode remote
  openclaw config set gateway.remote.url "wss://gateway.example.com"

仅临时/开发： 传递 --allow-unconfigured 以在没有 gateway.mode=local 的情况下启动网关。

还没有配置文件？ 运行 openclaw setup 创建起始配置，然后重新运行 网关。

服务环境（PATH + 运行时）

网关服务使用 最小 PATH 运行，以避免 shell/manager 杂乱：

• macOS: /opt/homebrew/bin, /usr/local/bin, /usr/bin, /bin
• Linux: /usr/local/bin, /usr/bin, /bin

这有意排除版本管理器（nvm/fnm/volta/asdf）和包 管理器（pnpm/npm），因为服务不加载您的 shell 初始化。运行时 变量如 DISPLAY 应该位于 ~/.openclaw/.env 中（由 网关早期加载）。 在 host=gateway 上运行的 Exec 将您的登录 shell PATH 合并到 exec 环境中， 所以缺少工具通常意味着您的 shell 初始化没有导出它们（或设置 tools.exec.pathPrepend）。参见 /tools/exec。

WhatsApp + Telegram 通道需要 Node；Bun 不受支持。如果您的 服务是使用 Bun 或版本管理的 Node 路径安装的，请运行 openclaw doctor 迁移到系统 Node 安装。

技能在沙盒中缺少 API 密钥

症状： 技能在主机上工作但在沙盒中因缺少 API 密钥而失败。

原因： 沙盒化的 exec 在 Docker 内部运行，不继承主机的 process.env。

修复：

• 设置 agents.defaults.sandbox.docker.env（或按代理 agents.list[].sandbox.docker.env）
• 或将密钥嵌入到您的自定义沙盒镜像中
• 然后运行 openclaw sandbox recreate --agent \<id\>（或 --all）

服务运行但端口未监听

如果服务报告 运行中 但在网关端口上没有任何监听， 网关可能拒绝绑定。

"运行中"在此处的含义

• 运行时：运行中 意味着您的监督程序（launchd/systemd/schtasks）认为进程是活动的。
• RPC 探测 意味着 CLI 实际上可以连接到网关 WebSocket 并调用 status。
• 始终信任 探测目标： + 配置（服务）： 作为 "我们实际上尝试了什么？" 的行。

检查：

• 对于 openclaw gateway 和服务，gateway.mode 必须是 local。
• 如果您设置了 gateway.mode=remote，CLI 默认 为远程 URL。服务仍可能在本地运行，但您的 CLI 可能正在探测错误的位置。使用 openclaw gateway status 查看服务解析的端口 + 探测目标（或传递 --url）。
• 当服务看起来在运行但端口已关闭时，openclaw gateway status 和 openclaw doctor 会从日志中显示 最后的网关错误。
• 非回环绑定（lan/tailnet/custom，或当回环不可用时的 auto）需要认证： gateway.auth.token（或 OPENCLAW_GATEWAY_TOKEN）。
• gateway.remote.token 仅用于远程 CLI 调用；它 不 启用本地认证。
• gateway.token 被忽略；使用 gateway.auth.token。

如果 openclaw gateway status 显示配置不匹配

• 配置（cli）：... 和 配置（服务）：... 通常应该匹配。
• 如果它们不匹配，您几乎肯定是在编辑一个配置，而服务正在运行另一个配置。
• 修复：从您希望服务使用的相同 --profile / OPENCLAW_STATE_DIR 重新运行 openclaw gateway install --force。

如果 openclaw gateway status 报告服务配置问题

• 监督程序配置（launchd/systemd/schtasks）缺少当前默认值。
• 修复：运行 openclaw doctor 更新它（或 openclaw gateway install --force 进行完全重写）。

如果 最后网关错误： 提到 "拒绝绑定 … 没有认证"

• 您将 gateway.bind 设置为非回环模式（lan/tailnet/custom，或当回环不可用时的 auto）但没有启用认证。
• 修复：设置 gateway.auth.mode + gateway.auth.token（或导出 OPENCLAW_GATEWAY_TOKEN）并重启服务。

如果 openclaw gateway status 显示 bind=tailnet 但未找到 tailnet 接口

• 网关尝试绑定到 Tailscale IP (100.64.0.0/10) 但在主机上未检测到任何。
• 修复：在该机器上启动 Tailscale（或将 gateway.bind 更改为 loopback/lan）。

如果 探测注释： 说探测使用回环

• 这对 bind=lan 是预期的：网关监听 0.0.0.0（所有接口），而回环仍应能本地连接。
• 对于远程客户端，使用真实的局域网 IP（不是 0.0.0.0）加上端口，并确保已配置认证。

地址已在使用（端口 18789）

这意味着网关端口上已有其他程序在监听。

检查：

openclaw gateway status

它将显示监听器和可能的原因（网关已在运行，SSH 隧道）。 如有需要，停止服务或选择不同的端口。

检测到额外工作空间文件夹

如果您从旧版本升级，磁盘上可能仍有 ~/openclawot。 多个工作空间目录可能导致混乱的认证或状态漂移，因为 只有一个工作空间处于活动状态。

修复： 保留单个活动工作空间并归档/删除其余的。参见 代理工作空间。

主聊天在沙盒工作空间中运行

症状：pwd 或文件工具显示 ~/.openclaw/sandboxes/... 即使您 期望的是主机工作空间。

原因： agents.defaults.sandbox.mode: "non-main" 基于 session.mainKey（默认为 "main"）。 群组/频道会话使用自己的键，因此它们被视为非主要会话并 获得沙盒工作空间。

修复选项：

• 如果您希望代理使用主机工作空间：设置 agents.list[].sandbox.mode: "off"。
• 如果您希望在沙盒内访问主机工作空间：为该代理设置 workspaceAccess: "rw"。

"代理被中止"

代理在响应过程中被中断。

原因：

• 用户发送了 stop、abort、esc、wait 或 exit
• 超时超过
• 进程崩溃

修复： 只需发送另一条消息。会话将继续。

"代理回复前失败：未知模型：anthropic/claude-haiku-3-5"

openclaw 故意拒绝 较旧/不安全的模型（特别是那些更容易 受到提示注入攻击的模型）。如果您看到此错误，则表示该模型名称已 不再受支持。

修复：

• 为提供者选择一个 最新 模型并更新您的配置或模型别名。
• 如果您不确定哪些模型可用，请运行 openclaw models list 或 openclaw models scan 并选择一个受支持的模型。
• 检查网关日志以了解详细的失败原因。

另请参阅：模型 CLI 和 模型提供者。

Messages Not Triggering

检查 1： 发送者是否在允许列表中？

openclaw status

在输出中查找 AllowFrom: ...。

检查 2： 对于群聊，是否需要提及？

# 消息必须匹配 mentionPatterns 或明确提及；默认值位于通道组/公会中。
# 多代理：`agents.list[].groupChat.mentionPatterns` 覆盖全局模式。
grep -n "agents\|groupChat\|mentionPatterns\|channels\.whatsapp\.groups\|channels\.telegram\.groups\|channels\.imessage\.groups\|channels\.discord\.guilds" \
  "${OPENCLAW_CONFIG_PATH:-$HOME/.openclaw/openclaw.json}"

检查 3： 检查日志

openclaw logs --follow
# 或如果您想要快速过滤：
tail -f "$(ls -t /tmp/openclaw/openclaw-*.log | head -1)" | grep "blocked|skip|unauthorized"

配对码未到达

如果 dmPolicy 是 pairing，未知发送者应该收到一个代码，在获得批准之前他们的消息会被忽略。

检查 1： 是否有待处理的请求正在等待？

openclaw pairing list <channel>

待处理的 DM 配对请求默认限制为每个通道 3 个。如果列表已满，新请求不会生成代码，直到其中一个被批准或过期。

检查 2： 请求是否已创建但没有发送回复？

openclaw logs --follow | grep "pairing request"

检查 3： 确认该通道的 dmPolicy 不是 open/allowlist。

图片 + 提及不起作用

已知问题：当您仅发送带有提及的消息（没有其他文本）时，WhatsApp 有时不包含提及元数据。

解决方法： 添加一些带提及的文本：

• ❌ @clawd + 图片
• ✅ @clawd check this + 图片

会话未恢复

检查 1： 会话文件是否存在？

ls -la ~/.openclaw/agents/<agentId>/sessions/

检查 2： 重置窗口是否太短？

{
  "session": {
    "reset": {
      "mode": "daily",
      "atHour": 4,
      "idleMinutes": 10080  // 7 天
    }
  }
}

检查 3： 是否有人发送了 /new、/reset 或重置触发器？

代理超时

默认超时时间为 30 分钟。对于长时间任务：

{
  "reply": {
    "timeoutSeconds": 3600  // 1 小时
  }
}

或者使用 process 工具在后台运行长时间命令。

WhatsApp 断开连接

# 检查本地状态（凭据，会话，排队事件）
openclaw status
# 探测运行中的网关 + 通道（WA 连接 + Telegram + Discord API）
openclaw status --deep

# 查看最近的连接事件
openclaw logs --limit 200 | grep "connection\|disconnect\|logout"

修复： 一旦网关运行通常会自动重新连接。如果您卡住了，请重启网关进程（无论您如何监督它），或手动运行详细输出：

openclaw gateway --verbose

如果您已登出/取消链接：

openclaw channels logout
trash "${OPENCLAW_STATE_DIR:-$HOME/.openclaw}/credentials" # 如果登出不能完全清除所有内容
openclaw channels login --verbose       # 重新扫描二维码

媒体发送失败

检查 1： 文件路径是否有效？

ls -la /path/to/your/image.jpg

检查 2： 文件是否太大？

• 图片：最大 6MB
• 音频/视频：最大 16MB
• 文档：最大 100MB

检查 3： 检查媒体日志

grep "media|fetch|download" "$(ls -t /tmp/openclaw/openclaw-*.log | head -1)" | tail -20

高内存使用

OpenClaw 将对话历史保存在内存中。

修复： 定期重启或设置会话限制：

{
  "session": {
    "historyLimit": 100  // 最大保留消息数
  }
}

通用故障排除

"网关无法启动 — 配置无效"

当配置包含未知键、格式错误的值或无效类型时，OpenClaw 现在拒绝启动。 这是为了安全而有意为之的。

使用 Doctor 修复它：

openclaw doctor
openclaw doctor --fix

注意事项：

• openclaw doctor 报告每个无效条目。
• openclaw doctor --fix 应用迁移/修复并重写配置。
• 即使配置无效，诊断命令如 openclaw logs、openclaw health、openclaw status、openclaw gateway status 和 openclaw gateway probe 仍然可以运行。

"所有模型都失败了" — 我应该首先检查什么？

• 凭据：尝试的提供者是否存在凭据（认证配置文件 + 环境变量）。
• 模型路由：确认 agents.defaults.model.primary 和备用模型是您可以访问的模型。
• 网关日志：在 /tmp/openclaw/… 中查看确切的提供者错误。
• 模型状态：使用 /model status（聊天）或 openclaw models status（CLI）。

我在我的个人 WhatsApp 号码上运行 — 为什么自聊很奇怪？

启用自聊模式并允许您自己的号码：

{
  channels: {
    whatsapp: {
      selfChatMode: true,
      dmPolicy: "allowlist",
      allowFrom: ["+15555550123"]
    }
  }
}

参见 WhatsApp 设置。

WhatsApp 将我登出了。如何重新认证？

再次运行登录命令并扫描二维码：

openclaw channels login

在 main 分支上出现构建错误 — 标准修复路径是什么？

1. git pull origin main && pnpm install
2. openclaw doctor
3. 检查 GitHub issues 或 Discord
4. 临时解决方法：检出一个较早的提交

npm 安装失败（allow-build-scripts / 缺少 tar 或 yargs）。现在怎么办？

如果您从源代码运行，请使用仓库的包管理器：pnpm（推荐）。 仓库声明了 packageManager: "pnpm@…"。

典型恢复步骤：

git status   # 确保您在仓库根目录
pnpm install
pnpm build
openclaw doctor
openclaw gateway restart

原因：pnpm 是此仓库配置的包管理器。

如何在 git 安装和 npm 安装之间切换？

使用 网站安装程序 并使用标志选择安装方法。它 就地升级并重写网关服务以指向新安装。

切换 到 git 安装：

curl -fsSL https://clawd.bot/install.sh | bash -s -- --install-method git --no-onboard

切换 到 npm 全局：

curl -fsSL https://clawd.bot/install.sh | bash

注意事项：

• git 流程仅在仓库干净时才会变基。请先提交或暂存更改。
• 切换后，运行：
  bash

  openclaw doctor
  openclaw gateway restart

Telegram 块流在工具调用之间没有分割文本。为什么？

块流只发送完整的文本块。常见的导致单个消息的原因：

• agents.defaults.blockStreamingDefault 仍然是 "off"。
• channels.telegram.blockStreaming 设置为 false。
• channels.telegram.streamMode 是 partial 或 block 并且草稿流是激活的 （私人聊天 + 主题）。在这种情况下，草稿流禁用了块流。
• 您的 minChars / 合并设置太高，因此块被合并了。
• 模型发出一个大的文本块（没有中间回复刷新点）。

修复清单：

1. 将块流设置放在 agents.defaults 下，而不是根目录。
2. 如果您想要真正的多消息块回复，请设置 channels.telegram.streamMode: "off"。
3. 调试时使用较小的块/合并阈值。

See Streaming.

Discord 在我的服务器中即使设置了 requireMention: false 也不回复。为什么？

requireMention 仅在通道通过允许列表后控制提及门控。 默认情况下 channels.discord.groupPolicy 是 允许列表，所以公会必须显式启用。 如果您设置了 channels.discord.guilds.\<guildId\>.channels，只有列出的通道被允许；省略它以允许公会中的所有通道。

修复清单：

1. 设置 channels.discord.groupPolicy: "open" 或 添加一个公会允许列表条目（以及可选的通道允许列表）。
2. 在 channels.discord.guilds.\<guildId\>.channels 中使用 数字通道 ID。
3. 将 requireMention: false 放在 channels.discord.guilds 下（全局或每个通道）。 顶层 channels.discord.requireMention 不是受支持的键。
4. 确保机器人具有 消息内容意图 和通道权限。
5. 运行 openclaw channels status --probe 获取审核提示。

文档：Discord，通道故障排除。

Cloud Code Assist API 错误：无效的工具模式 (400)。现在怎么办？

这几乎总是 工具模式兼容性 问题。Cloud Code Assist 端点接受严格的 JSON 模式子集。OpenClaw 在当前 main 分支中清理/规范化工具 模式，但该修复尚未包含在最新版本中（截至 2026年1月13日）。

修复清单：

1. 更新 OpenClaw：
   • 如果您可以从源代码运行，请拉取 main 并重启网关。
   • 否则，请等待包含模式清理器的下一个版本。
2. 避免不受支持的关键字，如 anyOf/oneOf/allOf、patternProperties、 additionalProperties、minLength、maxLength、format 等。
3. 如果您定义自定义工具，请保持顶层模式为 type: "object"，并使用 properties 和简单枚举。

参见 工具 和 TypeBox 模式。

macOS 特定问题

授予权限时应用程序崩溃（语音/麦克风）

如果应用程序在您点击隐私提示上的"允许"时消失或显示"Abort trap 6"：

修复 1：重置 TCC 缓存

tccutil reset All com.openclaw.mac.debug

修复 2：强制新包 ID 如果重置不起作用，请在 scripts/package-mac-app.sh 中更改 BUNDLE_ID（例如，添加 .test 后缀）并重建。这会强制 macOS 将其视为新应用。

网关卡在 "Starting..."

应用程序连接到端口 18789 上的本地网关。如果它一直卡住：

修复 1：停止监督程序（首选） 如果网关由 launchd 监督，杀死 PID 只会使它重新生成。首先停止监督程序：

openclaw gateway status
openclaw gateway stop
# 或：launchctl bootout gui/$UID/com.openclaw.gateway （如需要，替换为 com.openclaw.<profile>）

修复 2：端口正忙（查找监听器）

lsof -nP -iTCP:18789 -sTCP:LISTEN

如果是无人监督的进程，请先尝试优雅停止，然后升级：

kill -TERM <PID>
sleep 1
kill -9 <PID> # 最后的手段

修复 3：检查 CLI 安装 确保全局 openclaw CLI 已安装并与应用程序版本匹配：

openclaw --version
npm install -g openclaw@<version>

调试模式

获取详细日志：

# 在配置中开启跟踪日志：
#   ${OPENCLAW_CONFIG_PATH:-$HOME/.openclaw/openclaw.json} -> { logging: { level: "trace" } }
#
# 然后运行详细命令将调试输出镜像到标准输出：
openclaw gateway --verbose
openclaw channels login --verbose

日志位置

健康检查

# 监督程序 + 探测目标 + 配置路径
openclaw gateway status
# 包括系统级扫描（遗留/额外服务，端口监听器）
openclaw gateway status --deep

# 网关是否可访问？
openclaw health --json
# 如果失败，请使用连接详情重新运行：
openclaw health --verbose

# 是否有其他程序在默认端口上监听？
lsof -nP -iTCP:18789 -sTCP:LISTEN

# 最近活动（RPC 日志尾部）
openclaw logs --follow
# 如果 RPC 关闭则使用备选方案
tail -20 /tmp/openclaw/openclaw-*.log

重置所有内容

终极选项：

openclaw gateway stop
# 如果您安装了服务并希望进行干净安装：
# openclaw gateway uninstall

trash "${OPENCLAW_STATE_DIR:-$HOME/.openclaw}"
openclaw channels login         # 重新配对 WhatsApp
openclaw gateway restart           # 或：openclaw gateway

⚠️ 这会丢失所有会话并需要重新配对 WhatsApp。

获取帮助

1. 首先检查日志：/tmp/openclaw/ （默认：openclaw-YYYY-MM-DD.log，或您配置的 logging.file）
2. 在 GitHub 上搜索现有问题
3. 使用以下信息打开新问题：
   • openclaw 版本
   • 相关日志片段
   • 重现步骤
   • 您的配置（请编辑掉敏感信息！）

"Have you tried turning it off and on again?" — Every IT person ever

🦞🔧

浏览器未启动（Linux）

如果您看到 "Failed to start Chrome CDP on port 18800"：

最可能的原因： Ubuntu 上的 Snap 包装的 Chromium。

快速修复： 改为安装 Google Chrome：

wget https://dl.google.com/linux/direct/google-chrome-stable_current_amd64.deb
sudo dpkg -i google-chrome-stable_current_amd64.deb

然后在配置中设置：

{
  "browser": {
    "executablePath": "/usr/bin/google-chrome-stable"
  }
}

完整指南： 参见 browser-linux-troubleshooting