🔧 OpenClaw 故障排查 101

为什么需要故障排查指南？

OpenClaw 是一个复杂的 AI Agent 平台，涉及模型调用、工具执行、状态管理等多个环节。任何一个环节出问题，都可能导致 Agent 行为异常。

本指南将带你从入门到精通，掌握 OpenClaw 故障排查的核心技能。

入门：常见问题快速诊断

问题 1：Agent 无响应

# 步骤 1：检查 Agent 状态
openclaw agent status my-agent

# 步骤 2：查看日志
openclaw logs my-agent --last 50

# 步骤 3：常见原因和修复
# 原因 1：模型 API 未配置
export OPENAI_API_KEY="sk-..."
openclaw config set model.provider openai

# 原因 2：模型 API 错误
# 检查 API Key 是否有效、余额是否充足

# 原因 3：Context Window 满了
openclaw context clear my-agent

# 原因 4：Agent 卡死（死循环）
openclaw agent restart my-agent

问题 2：工具调用失败

# 步骤 1：检查工具是否安装
openclaw skills list | grep web_search

# 步骤 2：测试工具
openclaw tool test web_search --query "test"

# 步骤 3：查看工具日志
openclaw tool logs web_search

# 常见原因：
# 1. 工具未安装 → openclaw skills install clawhub/web-search
# 2. 工具依赖缺失 → 检查工具的 README
# 3. 权限不足 → openclaw permissions add my-agent tool_execute
# 4. 网络问题 → 检查防火墙、代理设置

问题 3：记忆丢失

# 步骤 1：检查 Memory 配置
openclaw config get memory

# 步骤 2：检查 Memory 后端
openclaw memory status

# 步骤 3：测试记忆存储和检索
openclaw memory test

# 常见原因：
# 1. Memory Skill 未安装 → openclaw skills install clawhub/memory-core
# 2. 记忆后端未启动（如 Redis）→ 启动后端服务
# 3. Context Window 策略问题 → 调整 context.strategy
# 4. 记忆 TTL 过短 → 增加 memory.ttl

进阶：日志分析和诊断

理解 OpenClaw 日志

# 查看实时日志
openclaw logs my-agent --follow

# 日志示例：
[2026-07-04 01:05:23] [INFO] Agent my-agent started
[2026-07-04 01:05:24] [DEBUG] Loading context (145,234 tokens)
[2026-07-04 01:05:25] [INFO] Calling model: gpt-5.6-sol
[2026-07-04 01:05:27] [DEBUG] Model response received (2,345 tokens)
[2026-07-04 01:05:28] [INFO] Executing tool: web_search
[2026-07-04 01:05:30] [ERROR] Tool execution failed: API rate limit
[2026-07-04 01:05:31] [WARN] Retrying tool execution (1/3)
[2026-07-04 01:05:33] [INFO] Tool execution succeeded

日志级别

启用详细日志

# ~/.openclaw/config.yaml
logging:
  level: debug          # 或 trace
  output: file           # 或 console, both
  file: /var/log/openclaw/agent.log
  rotation: daily        # 日志轮转
  retention: 7d         # 保留 7 天

高级：性能分析和优化

性能瓶颈诊断

# 生成性能报告
openclaw analyze performance my-agent --last 24h

# 报告示例：
Performance Report for my-agent
=====================================
1. Model Latency: 1,250ms (avg)
   - GPT-5.6 Sol: 1,400ms
   - GPT-5.6 Turbo: 800ms
   → Recommendation: Use Turbo for non-reasoning tasks

2. Token Usage: 8.5M tokens (24h)
   - Input: 6.2M (73%)
   - Output: 2.3M (27%)
   → Recommendation: Enable token caching

3. Tool Execution: 1,200 calls (24h)
   - web_search: 450 calls (avg 1.2s)
   - memory: 350 calls (avg 0.3s)
   - write: 200 calls (avg 0.5s)
   → Recommendation: Parallelize tool calls

4. Error Rate: 2.3%
   - Rate limit: 15 errors
   - Timeout: 8 errors
   - Invalid request: 5 errors
   → Recommendation: Implement retry with backoff

使用 OpenClaw Doctor

# 运行自动诊断
openclaw doctor

# 输出示例：
OpenClaw System Diagnosis
========================
✅ Config file: valid
✅ Model API: connected (latency: 120ms)
✅ Memory backend: connected (Redis 6.2.6)
⚠️  Token usage: high (95% of budget)
   → Recommendation: Enable token caching
⚠️  Memory TTL: short (1 day)
   → Recommendation: Increase to 30 days
❌ Skill "web-scraper": failed dependencies
   → Fix: run `openclaw skills fix web-scraper`

Summary: 2 errors, 2 warnings, 2 recommendations

专家：源码调试和社区资源

启用源码调试

# 以调试模式启动 Agent
openclaw agent run my-agent --debug

# 使用 Node.js 调试器
node --inspect $(which openclaw) agent run my-agent

# 在 Chrome DevTools 中调试
# 1. 打开 chrome://inspect
# 2. 点击 "Open dedicated DevTools for Node"
# 3. 设置断点、单步执行、查看变量

社区资源

报告 Bug

# 生成 Bug 报告
openclaw bug-report --include-logs --include-config

# 会生成包含以下内容的报告：
# - OpenClaw 版本
# - 操作系统信息
# - 配置文件（脱敏后）
# - 最近的错误日志
# - 复现步骤

# 然后到 GitHub Issues 提交
# https://github.com/openclaw/openclaw/issues/new

故障排查检查清单

1. 问题确认：明确问题现象、复现步骤、影响范围
2. 日志检查：查看 Agent 日志、工具日志、系统日志
3. 配置验证：检查配置文件、环境变量、权限设置
4. 依赖检查：验证 Skills 安装、工具依赖、后端服务
5. 性能分析：查看延迟、Token 使用、错误率
6. 社区求助：搜索类似问题、在 Discord 提问、提交 Issue
7. 修复验证：应用修复后，验证问题是否解决
8. 总结记录：记录问题和解决方案，帮助他人