Raven故障排查：raven doctor诊断命令实战，快速修复9个常见配置坑

Raven故障排查raven doctor诊断命令实战快速修复9个常见配置坑【免费下载链接】RavenThe Harness of Harnesses: a trusted, persistent, self-evolving multi-agent ecosystem for all-domain collaboration.项目地址: https://gitcode.com/gh_mirrors/raven35/RavenRaven 是一个可信、持久、可自我进化的多智能体生态系统The Harness of Harnesses支撑代码、研究、设计、PPT 等多域协作。当它出现模型调不通、配置读不到、渠道连不上等状况时raven doctor诊断命令就是你的第一站一条命令零联网体检配置、路由与 LLM 连通性快速定位并修复常见配置坑。为什么需要 raven doctor多智能体系统涉及配置文件、模型路由、消息渠道、外部依赖等多个环节任何一个环节出错智能体就会哑火。raven doctor把这些环节一次性体检清楚且默认模式零联网、毫秒级返回不会消耗任何 token特性说明⚡ 零联网默认只做静态检查检查配置文件、路由、渠道、外部工具 可选探测--probe发送一条真实测试消息验证 LLM 是否真的能响应 安全修复--fix仅在你授权后才写入修复绝不偷偷改配置 CI 友好--json输出机器可读结果退出码区分故障等级诊断命令的完整实现位于 raven/cli/doctor_commands.py。快速上手最常用的 5 条诊断命令命令用途raven doctor零联网静态体检毫秒级出报告raven doctor --probe额外发一条测试消息验证 LLM 端到端可用raven doctor --probe --timeout 30慢网络下放宽探测超时默认 15 秒raven doctor --json输出 JSON 报告方便接入 CI/CD 或脚本raven doctor --fix报告并自动应用安全的配置修复见下文另外raven doctor --install-summary会逐行汇报 5 类可选安装能力长期记忆、设计引擎、PPT 引擎、Deck 预览、浏览器适合快速确认装全了没有。读懂 doctor 报告9 个体检分区raven doctor的报告按分区输出每个分区对应一类常见故障分区检查内容Installation安装是否完整升级被中断会在这里暴露Paths配置文件默认~/.raven/config.json是否存在、JSON 是否合法、工作区目录是否存在Routing当前模型、路由到的 provider、最大 token、上下文窗口Features启用的消息渠道、缺少 SDK 的渠道、Skill Forge 开关External toolsLibreOffice、Chromium/Playwright、Cairo、设计引擎等外部依赖Gateway网关进程是否在运行pid、启动时间Memory长期记忆后端自检如插件是否安装、服务是否可召回Tool capabilities每个需要凭据的工具是否配置好、密钥能否解析、是否被手动关闭LLM Probe测试消息的响应文本、消耗 token 与耗时退出码是 CI 集成的关键约定0全部通过1静态检查失败配置缺失/非法/路由无法解析/安装不完整2静态检查通过但--probe或记忆后端故障——让 CI 能区分配置坏了和模型连不通。快速修复9 个常见配置坑逐个击破 下面 9 个坑按症状 → 原因 → 修复组织全部来自 doctor 报告的典型输出。坑 1配置文件不存在症状Config: ✗ (not found)并提示 Raven is not configured原因从未运行过初始化向导修复执行raven onboard引导创建配置文件。配置路径规则RAVEN_HOME环境变量、默认~/.raven/config.json定义在 raven/home.py 与 raven/contracts/path_policy.py坑 2配置文件 JSON 非法症状⚠ invalid JSON (running on defaults)——Raven 正悄悄用内置默认值运行原因JSON 不允许注释和尾逗号空文件、顶层不是对象同样判为非法修复修正 [~/.raven/config.json] 的语法或执行raven onboard --reset重建配置模板。配置加载与迁移逻辑见 raven/config/loader.py坑 3模型无法路由到任何 provider症状Routing 分区显示Routes to: unresolved原因配置了模型但没有 provider 能接住它修复先raven provider list查看可用名称再执行raven provider use model --provider name显式绑定。provider 子命令实现见 raven/cli/provider_commands.py坑 4provider 名称拼错或不存在症状agents.defaults.provider is xxx, which nothing routes to原因名字不存在时每次调用的凭据都永远找不到修复raven provider list列出合法名称后改配置——这是拼写错误不是无解坑 5provider 未设置或写着 auto症状报告提示 vendor serving your model is derived from its id原因厂商靠模型 id 推导配置了两个厂商时谁付钱可能取决于它们在列表中的顺序auto是已废弃的未设置写法修复raven provider use model --provider name让谁服务、谁出钱明确下来坑 6上下文窗口被钉死偏小症状contextWindowTokens is pinned to X, but model holds Y原因历史预算、记忆归档时机全部按这个偏小的值计算模型能力被锁住修复删除agents.defaults.contextWindowTokens让窗口跟随模型——这是raven doctor --fix会自动安全修复的两类问题之一坑 7模型不在目录中窗口回退默认值症状auto - 128,000 default (no catalogue knows this model)原因目录不认识该模型时历史预算按默认值计算——对于百万 token 级的模型这相当于只用了五分之一修复用agents.defaults.contextWindowTokens手动钉上真实窗口坑 8LLM Probe 失败症状raven doctor --probe显示✗ Failed: ...原因密钥错误或agents.defaults.model写的 id 不是该 provider 实际服务的模型修复按 doctor 附带的排障提示依次执行raven provider test provider不花 token 复验凭据、raven provider get provider查看磁盘上实际存了什么再核对配置里的 model id坑 9安装不完整升级被中断症状Installation: ✗ incomplete——这是唯一能让其余诊断全部失效的分区原因uv tool install中途被打断留下半新半旧的安装修复按提示用官方安装脚本仓库内的 install.sh重新修复环境用raven doctor --install-summary逐行确认长期记忆、设计引擎、PPT 引擎等可选组件是否到位外部依赖体检报告但不误伤External tools 分区检查四类外部程序缺失只报告、不改变退出码——因为缺 LibreOffice 时 PPT 仍可以构建、智能体仍会回答只是无法渲染预览依赖缺失影响安装提示LibreOffice (soffice)Deck 无法渲染、测量、预览系统包管理器安装提示语见 raven/utils/office.pyChromium headless shell浏览器工具无法启动重新安装 Raven或python -m playwright install chromiumCairoDeck 里抓取的 SVG 图片被拒安装 libcairo提示语见 raven/utils/cairo.py设计引擎 (raven_design)设计类渲染不可用通过安装脚本重装收尾让诊断成为日常建议把raven doctor作为每次环境变更后的固定动作把raven doctor --probe --json接入 CI——退出码语义清晰天然适合做流水线卡点。 延伸资料诊断命令源码raven/cli/doctor_commands.py配置加载与迁移raven/config/loader.py、raven/home.py初始化向导raven/cli/onboard_commands.py官方命令参考docs-site/docs/commands.zh.mdRaven 使用指南docs-site/docs/using-raven.zh.md一条raven doctor把智能体为什么不理我变成第几个分区红了、敲哪条命令。【免费下载链接】RavenThe Harness of Harnesses: a trusted, persistent, self-evolving multi-agent ecosystem for all-domain collaboration.项目地址: https://gitcode.com/gh_mirrors/raven35/Raven创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考