oc-doctor

OpenClaw Doctor 综合评估

核心用法

OpenClaw Doctor 是一款专为本地 OpenClaw 安装设计的深度诊断工具，通过 11 个系统化检测模块生成结构化健康报告。用户可通过 "openclaw doctor"、"claw health check" 等触发词调用，工具将自动执行从安装版本校验到系统指令令牌预算的全链路扫描。

诊断流程采用分层递进架构：先执行前置依赖检查（openclaw/jq 可用性），再动态探测运行时路径，随后并行扫描 11 个核心维度——涵盖配置一致性、会话维护策略、模型对齐状态、Cron 任务健康度、安全审计、资源占用、网关进程、以及系统指令令牌预算等关键领域。

显著优点

1. 检测深度与广度兼具

• 11 个独立检测章节，覆盖从微观配置项（如 reserveTokensFloor 缓冲区）到宏观系统状态（如网关进程僵尸检测）
• 独创的双向交叉验证机制：既读取配置文件，又通过 openclaw sessions/status 等内置命令获取运行时实况，避免"配置漂移"导致的误判
• 系统指令健康检查引入动态基准算法，根据实际 context_window 计算百分比阈值，而非固定数值

2. 分级告警与可操作修复

• 三级严重度体系：CRITICAL（功能中断/数据丢失风险）、WARNING（配置亚健康）、INFO（优化机会）
• 每个发现项标配影响说明+修复命令，支持交互式一键修复（需用户确认）
• 智能区分"可自动修复"（孤儿文件清理、Cron 去重）与"需人工决策"（安全策略调整、模型降级）

3. 本地化隐私优先设计

• 零网络请求，纯本地文件系统操作
• 强制敏感信息脱敏：API 密钥仅显示前 8 位、密码字段替换为 ***REDACTED***
• 修改操作遵循显式确认原则，默认只读模式运行

4. 动态语言适配

• 自动推断用户语言偏好：优先检查对话历史、工作区文件编码（CJK 检测）、系统 locale，最终回退英文
• 诊断报告、交互提示、修复建议全程同源语言输出

潜在局限与注意事项

1. 平台与版本绑定

• 仅支持 macOS/Linux，Windows 用户需 WSL 环境
• 依赖特定 OpenClaw 内部文件结构（如 $OPENCLAW_HOME/agents/main/sessions/），若上游架构变更可能导致路径探测失效

2. 动态阈值的不确定性

• 当 context_window_source 为 "default_fallback" 时，系统指令占比计算可能失准，需人工复核
• 模型上下文窗口值依赖本地 models.json，若用户手动覆盖官方定义，可能出现"假阴性"健康状态

3. 修复操作的边界风险

• 会话对齐修复会批量修改所有会话的 model 字段，若用户有意为不同会话配置差异化模型，将被强制统一
• Cron 任务去重基于 name+schedule+enabled 三元组，逻辑重复但用途不同的任务可能被误合并

4. 工具描述膨胀检测的局限性

• 仅标识 OpenClaw 自动注入的工具（如 Feishu bitable），无法识别用户自定义 Skill 的过度描述
• 未提供自动精简建议，仅标记警告

适合人群

• OpenClaw 重度用户：运行多通道（Telegram/Feishu）、高频 Cron 任务、长期积累会话数据的复杂场景
• DevOps/SRE 角色：负责多实例部署的健康监控与标准化治理
• 性能敏感型用户：遭遇上下文截断、响应延迟、磁盘空间告警等问题，需定位根因
• 安全意识优先用户：希望审计 Feishu/Telegram 权限配置、网关认证模式、密钥存储方式

常规风险提示

• 误删风险：孤儿文件检测依赖 sessions.json 索引一致性，若该文件损坏，可能误判有效会话为孤儿
• 配置覆盖风险：一键修复会重写 openclaw.json，建议修复前手动备份（工具未内置备份机制）
• 网关中断风险：僵尸进程清理可能误杀合法长连接，建议在低峰期操作
• 令牌预算误判：若实际使用的模型与 models.json 定义不符，系统指令占比计算将失真，可能导致过度优化或忽视真正风险