farcasclaudiu/openclaw
1
0
Fork 0
mirror of https://github.com/farcasclaudiu/openclaw.git synced 2026-06-29 15:01:48 +03:00
Code Issues Packages Projects Releases Wiki Activity

Docs: normalize zh-CN terminology + tone

Browse Source 
What: switch to 你/你的 tone; standardize Skills/Gateway网关/local loopback/私信 wording
Why: align zh-CN docs with issue 6995 feedback + idiomatic tech style
Tests: pnpm docs:build
This commit is contained in:
Josh Palmer
2026-02-02 15:46:45 +01:00
parent 2b1f68c928
commit 5676a6b38d
237 changed files with 2322 additions and 2337 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/zh-CN/gateway/troubleshooting.md
+50 -50
View File
@@ -1,7 +1,7 @@
---
read_when:
- 排查运行时问题或故障时
summary: 常见 OpenClaw 故障的快速排障指南
summary: 常见 OpenClaw 故障的快速解决问题指南
title: 故障排除
x-i18n:
generated_at: "2026-02-01T21:08:01Z"
@@ -26,12 +26,12 @@ x-i18n:
| 命令 | 告诉你什么 | 何时使用 |
| ---------------------------------- | --------------------------------------------------------------------------------- | -------------------------------- |
| `openclaw status` | 本地摘要：操作系统 + 更新、Gateway 可达性/模式、服务、智能体/会话、提供商配置状态 | 首次检查，快速概览 |
| `openclaw status` | 本地摘要：操作系统 + 更新、Gateway网关可达性/模式、服务、智能体/会话、提供商配置状态 | 首次检查，快速概览 |
| `openclaw status --all` | 完整本地诊断（只读、可粘贴、基本安全）包含日志尾部 | 需要分享调试报告时 |
| `openclaw status --deep` | 运行 Gateway 健康检查（包括提供商探测；需要 Gateway 可达） | 当"已配置"不等于"正常工作"时 |
| `openclaw gateway probe` | Gateway 发现 + 可达性（本地 + 远程目标） | 怀疑探测了错误的 Gateway 时 |
| `openclaw channels status --probe` | 向运行中的 Gateway 查询渠道状态（可选探测） | Gateway 可达但渠道异常时 |
| `openclaw gateway status` | 管理器状态（launchd/systemd/schtasks）、运行时 PID/退出码、最后一次 Gateway 错误 | 服务"看起来已加载"但实际未运行时 |
| `openclaw status --deep` | 运行 Gateway网关健康检查（包括提供商探测；需要 Gateway网关可达） | 当"已配置"不等于"正常工作"时 |
| `openclaw gateway probe` | Gateway网关发现 + 可达性（本地 + 远程目标） | 怀疑探测了错误的 Gateway网关时 |
| `openclaw channels status --probe` | 向运行中的 Gateway网关查询渠道状态（可选探测） | Gateway网关可达但渠道异常时 |
| `openclaw gateway status` | 管理器状态（launchd/systemd/schtasks）、运行时 PID/退出码、最后一次 Gateway网关错误 | 服务"看起来已加载"但实际未运行时 |
| `openclaw logs --follow` | 实时日志（运行时问题的最佳信号源） | 需要查看实际失败原因时 |
**分享输出：** 优先使用 `openclaw status --all`（它会脱敏令牌）。如果粘贴 `openclaw status` 的输出，建议先设置 `OPENCLAW_SHOW_SECRETS=0`（令牌预览）。
@@ -47,8 +47,8 @@ x-i18n:
修复选项：
- 重新运行上手引导，为该智能体选择 **Anthropic**。
- 或者在 **Gateway 主机**上粘贴 setup-token：
- 重新运行新手引导，为该智能体选择 **Anthropic**。
- 或者在 **Gateway网关主机**上粘贴 setup-token：
```bash
openclaw models auth setup-token --provider anthropic
```
@@ -64,12 +64,12 @@ openclaw models status
这意味着存储的 Anthropic OAuth 令牌已过期且刷新失败。
如果你使用的是 Claude 订阅（无 API 密钥），最可靠的修复方法是
切换到 **Claude Code setup-token** 并在 **Gateway 主机**上粘贴。
切换到 **Claude Code setup-token** 并在 **Gateway网关主机**上粘贴。
**推荐方式（setup-token）：**
```bash
# 在 Gateway 主机上运行（粘贴 setup-token）
# 在 Gateway网关主机上运行（粘贴 setup-token）
openclaw models auth setup-token --provider anthropic
openclaw models status
```
@@ -92,9 +92,9 @@ openclaw models status
**修复：**
- 优先通过 [Tailscale Serve](/gateway/tailscale) 使用 HTTPS。
- 或在 Gateway 主机上本地打开：`http://127.0.0.1:18789/`。
- 或在 Gateway网关主机上本地打开：`http://127.0.0.1:18789/`。
- 如果必须使用 HTTP，启用 `gateway.controlUi.allowInsecureAuth: true` 并
使用 Gateway 令牌（仅令牌；无设备身份/配对）。参见
使用 Gateway网关令牌（仅令牌；无设备身份/配对）。参见
[控制面板](/web/control-ui#insecure-http)。
### CI 密钥扫描失败
@@ -104,7 +104,7 @@ openclaw models status
### 服务已安装但未运行
如果 Gateway 服务已安装但进程立即退出，服务
如果 Gateway网关服务已安装但进程立即退出，服务
可能显示"已加载"但实际上没有任何进程在运行。
**检查：**
@@ -122,7 +122,7 @@ Doctor/service 会显示运行时状态（PID/上次退出码）和日志提示
- 文件日志（始终可用）：`/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`
- Windows：`schtasks /Query /TN "OpenClaw Gateway网关 (<profile>)" /V /FO LIST`
**启用更详细的日志：**
@@ -138,14 +138,14 @@ Doctor/service 会显示运行时状态（PID/上次退出码）和日志提示
完整的格式、配置和访问概览请参见 [/logging](/logging)。
### "Gateway start blocked: set gateway.mode=local"
### "Gateway网关 start blocked: set gateway.mode=local"
这意味着配置文件存在但 `gateway.mode` 未设置（或不是 `local`），因此
Gateway 拒绝启动。
Gateway网关拒绝启动。
**修复（推荐）：**
- 运行向导并将 Gateway 运行模式设置为 **Local**：
- 运行向导并将 Gateway网关运行模式设置为 **Local**：
```bash
openclaw configure
```
@@ -154,7 +154,7 @@ Gateway 拒绝启动。
openclaw config set gateway.mode local
```
**如果你打算运行远程 Gateway：**
**如果你打算运行远程 Gateway网关：**
- 设置远程 URL 并保持 `gateway.mode=remote`：
```bash
@@ -163,21 +163,21 @@ Gateway 拒绝启动。
```
**仅限临时/开发用途：** 传递 `--allow-unconfigured` 以在未设置
`gateway.mode=local` 的情况下启动 Gateway。
`gateway.mode=local` 的情况下启动 Gateway网关。
**还没有配置文件？** 运行 `openclaw setup` 创建初始配置，然后重新运行
Gateway。
Gateway网关。
### 服务环境（PATH + 运行时）
Gateway 服务运行时使用**最小化 PATH**，以避免 shell/管理器的干扰：
Gateway网关服务运行时使用**最小化 PATH**，以避免 shell/管理器的干扰：
- 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` 中（由 Gateway 在启动早期加载）。
变量如 `DISPLAY` 应放在 `~/.openclaw/.env` 中（由 Gateway网关在启动早期加载）。
在 `host=gateway` 上的 Exec 运行会将你的登录 shell `PATH` 合并到执行环境中，
因此缺少工具通常意味着你的 shell 初始化脚本没有导出它们（或设置
`tools.exec.pathPrepend`）。参见 [/tools/exec](/tools/exec)。
@@ -186,11 +186,11 @@ WhatsApp + Telegram 渠道需要 **Node**；不支持 Bun。如果你的
服务安装时使用了 Bun 或版本管理器管理的 Node 路径，请运行 `openclaw doctor`
以迁移到系统级 Node 安装。
### 技能在沙箱中缺少 API 密钥
### Skills 在沙箱中缺少 API 密钥
**症状：** 技能在主机上正常运行，但在沙箱中因缺少 API 密钥而失败。
**症状：** Skills 在主机上正常运行，但在沙箱中因缺少 API 密钥而失败。
**原因：** 沙箱化的 exec 在 Docker 中运行，**不会**继承主机的 `process.env`。
**原因：** 沙箱隔离的 exec 在 Docker 中运行，**不会**继承主机的 `process.env`。
**修复：**
@@ -200,21 +200,21 @@ WhatsApp + Telegram 渠道需要 **Node**；不支持 Bun。如果你的
### 服务在运行但端口未监听
如果服务报告**正在运行**但 Gateway 端口上没有监听，
Gateway 很可能拒绝了绑定。
如果服务报告**正在运行**但 Gateway网关端口上没有监听，
Gateway网关很可能拒绝了绑定。
**此处"正在运行"的含义**
- `Runtime: running` 表示你的管理器（launchd/systemd/schtasks）认为进程是活跃的。
- `RPC probe` 表示 CLI 实际上能够连接到 Gateway WebSocket 并调用 `status`。
- `RPC probe` 表示 CLI 实际上能够连接到 Gateway网关 WebSocket 并调用 `status`。
- 始终以 `Probe target:` + `Config (service):` 作为"我们实际尝试了什么？"的依据。
**检查：**
- `gateway.mode` 对于 `openclaw gateway` 和服务必须为 `local`。
- 如果你设置了 `gateway.mode=remote`，**CLI 默认**使用远程 URL。服务可能仍在本地运行，但你的 CLI 可能在探测错误的位置。使用 `openclaw gateway status` 查看服务解析的端口 + 探测目标（或传递 `--url`）。
- `openclaw gateway status` 和 `openclaw doctor` 会在服务看起来正在运行但端口未打开时显示**最后一次 Gateway 错误**日志。
- 非回环绑定（`lan`/`tailnet`/`custom`，或回环不可用时的 `auto`）需要认证：
- `openclaw gateway status` 和 `openclaw doctor` 会在服务看起来正在运行但端口未打开时显示**最后一次 Gateway网关错误**日志。
- 非 local loopback 绑定（`lan`/`tailnet`/`custom`，或 local loopback 不可用时的 `auto`）需要认证：
`gateway.auth.token`（或 `OPENCLAW_GATEWAY_TOKEN`）。
- `gateway.remote.token` 仅用于远程 CLI 调用；它**不会**启用本地认证。
- `gateway.token` 会被忽略；请使用 `gateway.auth.token`。
@@ -232,22 +232,22 @@ Gateway 很可能拒绝了绑定。
**如果 `Last gateway error:` 提到 "refusing to bind … without auth"**
- 你将 `gateway.bind` 设置为非回环模式（`lan`/`tailnet`/`custom`，或回环不可用时的 `auto`）但未配置认证。
- 你将 `gateway.bind` 设置为非 local loopback 模式（`lan`/`tailnet`/`custom`，或 local loopback 不可用时的 `auto`）但未配置认证。
- 修复：设置 `gateway.auth.mode` + `gateway.auth.token`（或导出 `OPENCLAW_GATEWAY_TOKEN`）并重启服务。
**如果 `openclaw gateway status` 显示 `bind=tailnet` 但未找到 tailnet 接口**
- Gateway 尝试绑定到 Tailscale IP（100.64.0.0/10）但主机上未检测到。
- Gateway网关尝试绑定到 Tailscale IP（100.64.0.0/10）但主机上未检测到。
- 修复：在该机器上启动 Tailscale（或将 `gateway.bind` 改为 `loopback`/`lan`）。
**如果 `Probe note:` 显示探测使用回环**
**如果 `Probe note:` 显示探测使用 local loopback**
- 对于 `bind=lan` 这是预期行为：Gateway 监听 `0.0.0.0`（所有接口），回环在本地仍可连接。
- 对于 `bind=lan` 这是预期行为：Gateway网关监听 `0.0.0.0`（所有接口），local loopback 在本地仍可连接。
- 对于远程客户端，请使用真实的 LAN IP（不是 `0.0.0.0`）加端口，并确保已配置认证。
### 地址已被占用（端口 18789）
这意味着某个进程已经在 Gateway 端口上监听。
这意味着某个进程已经在 Gateway网关端口上监听。
**检查：**
@@ -255,7 +255,7 @@ Gateway 很可能拒绝了绑定。
openclaw gateway status
```
它会显示监听者和可能的原因（Gateway 已在运行、SSH 隧道）。
它会显示监听者和可能的原因（Gateway网关已在运行、SSH 隧道）。
如果需要，停止服务或选择其他端口。
### 检测到多余的工作区文件夹
@@ -304,7 +304,7 @@ OpenClaw 有意拒绝**旧版/不安全的模型**（特别是那些更
- 为该提供商选择一个**最新**模型，并更新你的配置或模型别名。
- 如果不确定有哪些可用模型，运行 `openclaw models list` 或
`openclaw models scan` 并选择一个受支持的模型。
- 检查 Gateway 日志了解详细的失败原因。
- 检查 Gateway网关日志了解详细的失败原因。
另见：[模型 CLI](/cli/models) 和 [模型提供商](/concepts/model-providers)。
@@ -345,7 +345,7 @@ tail -f "$(ls -t /tmp/openclaw/openclaw-*.log | head -1)" | grep "blocked\\|skip
openclaw pairing list <channel>
```
每个渠道默认最多 **3 个**待处理的 DM 配对请求。如果列表已满，新请求在有一个被批准或过期之前不会生成验证码。
每个渠道默认最多 **3 个**待处理的 私信 配对请求。如果列表已满，新请求在有一个被批准或过期之前不会生成验证码。
**检查 2：** 请求是否已创建但未发送回复？
@@ -407,14 +407,14 @@ ls -la ~/.openclaw/agents/<agentId>/sessions/
```bash
# 检查本地状态（凭据、会话、排队事件）
openclaw status
# 探测运行中的 Gateway + 渠道（WA 连接 + Telegram + Discord API）
# 探测运行中的 Gateway网关 + 渠道（WA 连接 + Telegram + Discord API）
openclaw status --deep
# 查看最近的连接事件
openclaw logs --limit 200 | grep "connection\\|disconnect\\|logout"
```
**修复：** 通常在 Gateway 运行后会自动重连。如果卡住，重启 Gateway 进程（无论你用什么方式管理），或手动运行并附带详细输出：
**修复：** 通常在 Gateway网关运行后会自动重连。如果卡住，重启 Gateway网关进程（无论你用什么方式管理），或手动运行并附带详细输出：
```bash
openclaw gateway --verbose
@@ -464,7 +464,7 @@ OpenClaw 将对话历史保存在内存中。
## 常见故障排除
### "Gateway won't start — configuration invalid"
### "Gateway网关 won't start — configuration invalid"
OpenClaw 现在会在配置包含未知键、格式错误的值或无效类型时拒绝启动。
这是出于安全考虑的有意设计。
@@ -486,7 +486,7 @@ openclaw doctor --fix
- 正在使用的提供商是否存在**凭据**（认证配置文件 + 环境变量）。
- **模型路由**：确认 `agents.defaults.model.primary` 和回退模型是你能访问的模型。
- `/tmp/openclaw/…` 中的 **Gateway 日志**查看具体的提供商错误。
- `/tmp/openclaw/…` 中的 **Gateway网关日志**查看具体的提供商错误。
- **模型状态**：使用 `/model status`（聊天中）或 `openclaw models status`（CLI）。
### 我用个人 WhatsApp 号码运行 — 为什么自聊行为异常？
@@ -542,7 +542,7 @@ openclaw gateway restart
### 如何在 git 安装和 npm 安装之间切换？
使用**官网安装脚本**并通过标志选择安装方式。它会
就地升级并重写 Gateway 服务以指向新的安装。
就地升级并重写 Gateway网关服务以指向新的安装。
切换**到 git 安装**：
@@ -611,7 +611,7 @@ schema，但此修复尚未包含在最新发布版中（截至
修复清单：
1. **更新 OpenClaw**：
- 如果你能从源码运行，拉取 `main` 并重启 Gateway。
- 如果你能从源码运行，拉取 `main` 并重启 Gateway网关。
- 否则，等待包含 schema 清洗器的下一个版本。
2. 避免不受支持的关键字，如 `anyOf/oneOf/allOf`、`patternProperties`、
`additionalProperties`、`minLength`、`maxLength`、`format` 等。
@@ -635,12 +635,12 @@ tccutil reset All bot.molt.mac.debug
**修复 2：强制使用新 Bundle ID**
如果重置无效，更改 [`scripts/package-mac-app.sh`](https://github.com/openclaw/openclaw/blob/main/scripts/package-mac-app.sh) 中的 `BUNDLE_ID`（例如添加 `.test` 后缀）并重新构建。这会强制 macOS 将其视为新应用。
### Gateway 卡在"Starting..."
### Gateway网关卡在"Starting..."
应用连接到端口 `18789` 上的本地 Gateway。如果一直卡住：
应用连接到端口 `18789` 上的本地 Gateway网关。如果一直卡住：
**修复 1：停止管理器（推荐）**
如果 Gateway 由 launchd 管理，杀死 PID 只会让它重新启动。先停止管理器：
如果 Gateway网关由 launchd 管理，杀死 PID 只会让它重新启动。先停止管理器：
```bash
openclaw gateway status
@@ -687,8 +687,8 @@ openclaw channels login --verbose
| 日志 | 位置 |
| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Gateway 文件日志（结构化） | `/tmp/openclaw/openclaw-YYYY-MM-DD.log`（或 `logging.file`） |
| Gateway 服务日志（管理器） | macOS：`$OPENCLAW_STATE_DIR/logs/gateway.log` + `gateway.err.log`（默认：`~/.openclaw/logs/...`；profile 使用 `~/.openclaw-<profile>/logs/...`）<br />Linux：`journalctl --user -u openclaw-gateway[-<profile>].service -n 200 --no-pager`<br />Windows：`schtasks /Query /TN "OpenClaw Gateway (<profile>)" /V /FO LIST` |
| Gateway网关文件日志（结构化） | `/tmp/openclaw/openclaw-YYYY-MM-DD.log`（或 `logging.file`） |
| Gateway网关服务日志（管理器） | macOS：`$OPENCLAW_STATE_DIR/logs/gateway.log` + `gateway.err.log`（默认：`~/.openclaw/logs/...`；profile 使用 `~/.openclaw-<profile>/logs/...`）<br />Linux：`journalctl --user -u openclaw-gateway[-<profile>].service -n 200 --no-pager`<br />Windows：`schtasks /Query /TN "OpenClaw Gateway网关 (<profile>)" /V /FO LIST` |
| 会话文件 | `$OPENCLAW_STATE_DIR/agents/<agentId>/sessions/` |
| 媒体缓存 | `$OPENCLAW_STATE_DIR/media/` |
| 凭据 | `$OPENCLAW_STATE_DIR/credentials/` |
@@ -701,7 +701,7 @@ openclaw gateway status
# 包含系统级扫描（旧版/多余服务、端口监听者）
openclaw gateway status --deep
# Gateway 是否可达？
# Gateway网关是否可达？
openclaw health --json
# 如果失败，附带连接详情重新运行：
openclaw health --verbose