核心用法
Context Doctor 是一款面向 OpenClaw 代理系统的上下文窗口诊断工具，通过终端可视化或 PNG 图像输出，帮助用户理解 Token 预算的具体分配情况。
主要功能模块：
- 工作区文件扫描：检测 bootstrap 文件状态（正常/缺失/截断），显示字符数与估算 Token 数（chars/4）
- 技能清单盘点：枚举系统和用户目录下所有已安装技能（仅元数据，非实际加载）
- Token 预算拆解：量化系统提示、工作区文件、技能描述、工具模式等组件的占比
典型使用场景：
1. 用户主动询问"上下文健康度"或 Token 使用情况
2. 代理输出质量下降（"Agent 变笨"）的根因排查
3. 编辑工作区文件后验证上下文影响
4. 审计 bootstrap 开销，优化配置
输出方式：支持终端彩色渲染（Rich）和 PNG 图像导出（--png 参数），便于聊天场景直接分享。
---
显著优点
| 优势 | 说明 |
|------|------|
| **可视化直观** | 彩色进度条、状态图标，一眼识别问题文件 |
| **诊断信号明确** | 红/黄/绿三级信号，配套具体行动建议 |
| **零侵入设计** | 只读扫描，不修改任何配置或文件 |
| **双模式输出** | 终端交互 + 图像导出，适配不同场景 |
| **精准定位** | 区分"文件截断"（静默截断）与"文件缺失"（符号链接断裂）|
---
潜在局限
| 局限 | 说明 |
|------|------|
| **估算误差** | Token 按 chars/4 估算，非真实分词结果 |
| **非实时 Conversation 分析** | 明确不涉及对话历史、模型选择、成本追踪 |
| **依赖外部工具链** | PNG 导出需额外安装 `rich`、`rsvg-convert` 或 `cairosvg` |
| **仅覆盖 Bootstrap** | 运行时动态加载的技能/工具不纳入统计 |
---
适合人群
- OpenClaw 高级用户：需要精细化调优上下文配置
- Agent 开发者：排查"输出质量退化"等疑难问题
- 运维/审计人员：定期检查系统健康度，预防配置膨胀
---
常规风险
1. 路径泄露风险：输出可能包含本地绝对路径，分享截图时注意脱敏
2. 依赖版本漂移：rich 或 SVG 转换工具的版本差异可能导致渲染异常
3. 误读估算值：chars/4 的 Token 估算在中文场景下误差较大（中文 Token 密度通常更高）
4. 诊断范围盲区：无法检测模型层级的上下文压缩或 KV Cache 问题