OpenClaw 故障排查

解决 OpenClaw 集成中的常见问题

OpenClaw 故障排查

本文档帮助您诊断和解决使用 OpenClaw 集成时遇到的常见问题。

Gateway 问题

Gateway 无法启动

症状：对话时提示"OpenClaw Gateway 不可用"

可能原因：

  1. 配置文件错误

    • 检查 .openclaw/openclaw.json 语法是否正确
    • 确保 JSON 格式有效（无多余逗号、引号匹配等）
    • 验证模型 ID 格式是否正确

  2. 环境变量缺失

    • 确认组织已配置相应的 AI 模型 Channel
    • 检查 API Key 是否有效
    • 联系管理员确认环境变量已注入

  3. 端口冲突

    • Gateway 默认使用 18789 端口
    • 检查 Sandbox 容器内是否有其他服务占用该端口

解决方案：

  1. 前往工作空间设置 → AgentOS 标签页
  2. 点击"重启 Gateway"
  3. 查看错误提示中的详细信息
  4. 根据错误信息修复配置文件
  5. 再次重启 Gateway

Gateway 频繁重启

症状：对话时断断续续，状态指示器频繁变化

可能原因：

  1. 内存不足

    • Sandbox 容器内存限制
    • OpenClaw Gateway 内存占用过高

  2. 配置错误导致崩溃

    • 模型配置错误
    • Provider 配置不正确

  3. API 调用失败

    • API Key 无效或过期
    • API 端点不可达

解决方案：

  1. 检查 Gateway 日志（在 Sandbox 容器内）
  2. 简化配置，使用默认模型
  3. 确认 API Key 有效性
  4. 联系管理员检查容器资源限制

Gateway 健康检查失败

症状：状态指示器显示"异常"

可能原因：

  1. Gateway 进程已退出
  2. 健康检查端点不可达
  3. 网络问题

解决方案：

  1. 手动重启 Gateway
  2. 检查容器网络状态
  3. 查看 Wrapper Service 日志

对话问题

首次对话很慢

症状：第一次发送消息需要等待很久

原因：这是正常现象，系统需要：

  1. 启动 Sandbox 容器（如果未运行）
  2. 启动 OpenClaw Gateway
  3. 加载配置和模型
  4. 等待服务就绪

优化建议：

  • 耐心等待首次启动（通常 1~2 分钟）
  • 后续对话将显著加快

回复中断或不完整

症状：AI 回复到一半停止，没有错误提示

可能原因：

  1. 流式响应中断

    • 网络不稳定
    • Gateway 重启
    • Sandbox 容器重启

  2. Token 限制

    • 达到模型最大 token 限制
    • 上下文过长

解决方案：

  1. 刷新页面重试
  2. 检查 Gateway 状态
  3. 使用更大上下文的模型
  4. 清理对话历史，开始新对话

上下文丢失

症状：AI 忘记之前的对话内容

可能原因：

  1. Session 未持久化

    • Gateway 重启导致 Session 丢失
    • 切换到其他对话

  2. 对话太长

    • 超过模型上下文窗口
    • 旧消息被截断

解决方案：

  1. 确保在同一对话中交流
  2. 避免频繁切换对话
  3. 定期总结对话内容
  4. 使用支持更大上下文的模型

错误提示：Gateway 连接超时

症状：提示"无法连接到 OpenClaw Gateway"

可能原因：

  1. Gateway 未启动
  2. Sandbox 容器未运行
  3. 网络配置问题

解决方案：

  1. 检查 Gateway 状态
  2. 手动重启 Gateway
  3. 等待 30 秒后重试
  4. 如果持续失败，联系管理员

配置问题

配置修改不生效

症状：修改了 openclaw.json 但行为没有变化

原因：Gateway 需要重启才能加载新配置

解决方案：

  1. 保存配置文件
  2. 前往工作空间设置 → AgentOS 标签页
  3. 点击"重启 Gateway"
  4. 等待重启完成
  5. 开始新对话测试

配置语法错误

症状：Gateway 启动失败，提示配置错误

常见错误：

  1. 多余的逗号

    {
  "model": "claude-sonnet-4-5",  // ❌ 最后一项不能有逗号
}

  2. 引号不匹配

    {
  "model": "claude-sonnet-4-5'  // ❌ 引号类型不一致
}

  3. 环境变量格式错误

    {
  "apiKey": "$ANTHROPIC_API_KEY"  // ❌ 缺少花括号
}

正确格式：

{
  "model": "claude-sonnet-4-5",
  "apiKey": "${ANTHROPIC_API_KEY}"
}

模型不可用

症状：提示"模型 xxx 不可用"

可能原因：

  1. 模型 ID 格式错误

    • 正确格式：provider/model-id
    • 示例：anthropic/claude-sonnet-4-5

  2. Provider 未配置

    • 组织未配置该 Provider 的 Channel
    • API Key 缺失

  3. 模型不存在

    • 模型 ID 拼写错误
    • 该 Provider 不支持该模型

解决方案：

  1. 检查模型 ID 格式
  2. 确认组织已配置相应的 Channel
  3. 参考组织配置使用正确的模型 ID
  4. 联系管理员添加所需模型

权限问题

无法创建 OpenClaw 助手

症状：创建按钮不可用或提示权限不足

可能原因：

  1. 账号权限不足

    • 非组织成员
    • 权限级别不够

  2. 组织配置缺失

    • 组织未配置 AI 模型
    • 无可用的 Channel

解决方案：

  1. 联系组织管理员
  2. 确认账号已加入组织
  3. 确认组织已配置 AI 模型
  4. 申请必要的权限

无法重启 Gateway

症状：重启按钮不可用

可能原因：

  1. 工作空间权限不足
  2. 不是工作空间成员

解决方案：

  1. 确认是工作空间成员
  2. 联系工作空间管理员
  3. 申请必要的权限

性能问题

响应延迟高

症状：AI 回复速度很慢

可能原因：

  1. 模型选择

    • 使用了较大的模型（如 Opus）
    • 模型推理速度慢

  2. 网络延迟

    • API 端点距离远
    • 网络不稳定

  3. 资源限制

    • Sandbox 容器资源不足
    • Gateway 并发处理能力受限

优化建议：

  1. 切换到更快的模型（如 Sonnet）
  2. 使用更近的 API 端点
  3. 避免在对话中包含大量上下文
  4. 联系管理员调整资源限制

Gateway 内存占用高

症状：Gateway 运行一段时间后变慢或崩溃

可能原因：

  1. Session 缓存过多
  2. 内存泄漏
  3. 资源限制过低

解决方案：

  1. 定期重启 Gateway
  2. 清理旧的对话 Session
  3. 联系管理员调整容器内存限制
  4. 更新到最新版本的 OpenClaw

日志和诊断

查看 Gateway 日志

如果您有 Sandbox 容器访问权限：

  1. 进入 Sandbox 容器
  2. 查看 Gateway 日志： 
    # 查看实时日志
tail -f /workspace/.openclaw/gateway.log

# 查看完整日志
cat /workspace/.openclaw/gateway.log

启用调试模式

在 openclaw.json 中添加调试配置：

{
  "gateway": {
    "debug": true,
    "logLevel": "debug"
  }
}

重启 Gateway 后，将输出更详细的日志信息。

诊断信息收集

遇到问题时，收集以下信息有助于快速定位：

  1. 错误信息

    • 完整的错误提示
    • 错误发生的时间

  2. 配置信息

    • openclaw.json 内容（脱敏后）
    • 使用的模型 ID

  3. 环境信息

    • 浏览器类型和版本
    • 操作系统版本
    • 网络状况

  4. 操作步骤

    • 重现问题的详细步骤
    • 预期行为和实际行为

常见问题速查

问题快速解决方案
Gateway 无法启动检查配置文件 → 重启 Gateway
回复中断刷新页面 → 检查 Gateway 状态
配置不生效保存配置 → 重启 Gateway
首次对话慢正常现象，耐心等待
上下文丢失确保在同一对话中
模型不可用检查模型 ID 格式
权限不足联系管理员
响应延迟高切换到更快的模型

获取帮助

如果以上方法都无法解决您的问题：

  1. 查看相关文档

  2. 联系支持

    • 提交工单
    • 邮件联系技术支持
    • 加入用户社群

  3. 提供详细信息

    • 错误信息
    • 配置文件（脱敏）
    • 操作步骤
    • 环境信息

相关文档

OpenClaw 故障排查 | Knodo 文档