Help & FAQ

60 秒快速诊断

openclaw status              # 本地状态摘要
openclaw status --all        # 完整诊断报告（可分享）
openclaw gateway probe       # 探测 Gateway 可达性
openclaw gateway status      # Gateway 运行时状态
openclaw doctor              # 修复配置/服务问题
openclaw channels status --probe  # Channel 传输状态
openclaw logs --follow       # 实时日志

常见问题

Gateway 无法连接

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

Anthropic 429 长上下文错误

HTTP 429: rate_limit_error: Extra usage is required for long context requests → 需要在 Anthropic 账户开启长上下文额外用量。

本地 OpenAI 兼容后端失败

若错误提示 messages[].content 需要字符串：设置 compat.requiresStringContent: true
若仅 Agent 轮次失败：设置 compat.supportsTools: false

插件安装失败（missing openclaw.extensions）

插件包缺少 package.json 中的 openclaw.extensions 字段。

环境变量

OpenClaw 从多个来源加载环境变量，不覆盖已有值。

优先级（高→低）：

进程环境（父 shell/daemon 已有的）
当前目录 .env
全局 ~/.openclaw/.env
配置文件 env 块（~/.openclaw/openclaw.json）
可选 login-shell 导入（env.shellEnv.enabled: true）

配置 env 块：

{
  env: {
    OPENROUTER_API_KEY: "sk-or-...",
    vars: { GROQ_API_KEY: "gsk-..." },
  },
}

Shell env 导入：

{
  env: {
    shellEnv: { enabled: true, timeoutMs: 15000 },
  },
}

调试工具

运行时调试覆盖

/debug show
/debug set messages.responsePrefix="[openclaw]"
/debug unset messages.responsePrefix
/debug reset

需要先启用：commands.debug: true

会话追踪

/trace        # 切换追踪
/trace on
/trace off

插件生命周期追踪

OPENCLAW_PLUGIN_LIFECYCLE_TRACE=1 openclaw plugins install tokenjuice --force

原始模型流

# 查看原始模型输出（检测推理泄漏）
openclaw infer model run --stream-raw

Wiki AI

目录