用途
OpenViking Memory Doctor 是面向 OpenViking 记忆插件的客户端故障排查工具，用于诊断并修复本机上该插件的安装、配置和连接问题。该插件由三个会各自静默失败的部分组成：安装（市场注册、插件启用、九个钩子、stdio MCP 代理，出错时钩子不运行且无日志）、配置（~/.openviking/ovcli.conf、~/.openviking/ov.conf 及 OPENVIKING_* 环境变量，解析顺序为 env → ovcli.conf → ov.conf → 默认值，格式错误的文件会被当作“无配置”从而静默禁用插件，多余的环境变量会静默覆盖文件）、连接（自托管服务器的 /health 即使密钥错误也返回 200，状态栏可能显示绿色而实际请求全部 401；OpenViking Cloud 的网关同样鉴权 /health 和 /ready，无密钥探测返回 401 且不反映 URL 情况）。
主要能力
运行方式：
node ${CLAUDE_PLUGIN_ROOT}/scripts/ov-memory-doctor.mjs
可用选项：--json（机器可读）、--offline（跳过网络探测）、--timeout <ms>（每次探测超时，默认 5000）、--no-color。
报告包含六个部分——Environment、Plugin install、Configuration、Connection、Server health、Recent activity——以及一个列出所有 ✗/⚠ 及修复建议的 Summary。当解析出的 URL 为回环地址时，服务器运行在本机，工具会额外增加 Server health 部分：检查端口是否有监听、ov.conf 中是否存在仅限插件的键（以任意 harness 命名的顶层块，如 claude_code、codex、cursor、trae、trae_cn、zcode、opencode、dsh、pi，加上 server.url）导致服务器拒绝启动、以及 GET /ready 给出的各子系统判定（agfs、vectordb、api keys、embedding、ollama）。对于远程服务器仅探测 /ready。
API 密钥永不完整打印：三段式密钥显示为 account=<a> user=<u> secret=abcd…wxyz，旧式密钥显示为 abcd…wxyz（64 字符）。
使用方式
第 1 步 — 运行 doctor：执行上述命令并完整阅读报告后再操作。单一根因通常会在多个部分同时出现（例如错误密钥 → “api key rejected” + “system/status → 401” + turns_failed > 0）。若报告提示 “this script is not running from the registered install”，需从它打印的路径重新运行。
第 2 步 — 将发现映射到原因：自上而下处理，先修复第一个 ✗ 并重跑，再追下一个。常见映射包括：插件被禁用（无可解析配置、OPENVIKING_MEMORY_ENABLED=0 或 ov.conf 中 claude_code.enabled: false）；ovcli.conf 无法解析（尾随逗号/注释，最常见的“已安装但无反应”）；未注册或旧 id（重跑一行安装命令 curl -fsSL https://openviking.ai/install | bash -s -- --harness claude）；settings.json 中插件被禁用（claude plugin enable openviking-memory@openviking 后重启）；市场目录缺失或注册为文件；版本缓存过期；2.0 之前的残留（钩子重复触发、MCP 重复注册）；node 不在 PATH 或 node < 18；服务器不可达；URL 形状错误；/health 鉴权或密钥被拒；使用 ROOT api key 导致 403；trusted 模式需要 account + user；配置的 account/user 与密钥身份不符；请求超时超过钩子预算；反向代理未转发 /mcp；代理变量设置导致 Node fetch 忽略 HTTP(S)_PROXY（需 NODE_USE_ENV_PROXY=1 或 NODE_EXTRA_CA_CERTS）；last auto-recall 的原因码（offline/bypass/disabled/short_query/no_results/filtered_out）；turns_failed > 0 或捕获负载待处理；MCP 代理针对旧 URL 启动；recall 被固定到旧端点（rm ~/.openviking/state/context-face.json）；无钩子日志；ov.conf 含顶层 harness 块或 server.url 被拒；端口无监听；/ready 的 embedding/vectordb/agfs 错误；服务器仍在初始化（503）；docker 容器无 ov.conf。
第 3 步 — 有针对性的检查（仅当报告不结论性时）：用 OPENVIKING_DEBUG=1（需放在 ~/.claude/settings.json 的 env 块中）证明钩子运行并查看 ~/.openviking/logs/cc-hooks.log；用手工 curl 验证密钥和身份（Bearer 区分大小写且恰好一个空格）；直接验证 /mcp（无状态，无需 initialize）；用 claude mcp list 验证 Claude Code 的 MCP 接线；用 last-capture.json 中的 ov_session_id 验证捕获是否落库；用 CLI 的 ov health、ov config validate、ov config list 获取第二意见；服务器端检查 curl -sS "$URL/ready"、openviking-server doctor、lsof -nP -iTCP:1933 -sTCP:LISTEN、docker logs --tail 100 openviking。log.output 默认输出到 stdout。
修复与更新
仅在用户同意下编辑 ~/.openviking/ovcli.conf，展示改动、保留未知键、保持 0600 权限、绝不回显密钥。机器级覆盖优先使用 ~/.claude/settings.json 的 env 块。更改 url、安装或更新插件后重启 Claude Code（钩子每次调用重读配置，MCP 代理不会）。更新方式：GitHub 安装用 claude plugin marketplace update openviking && claude plugin update openviking-memory@openviking；Claude Code 2.1.224+ 的 TOS 安装后台自动更新或按需更新；更旧的 TOS、归档和开发检出安装需重跑安装器。修复后重跑 doctor 并观察下一条提示出现的 <openviking-context> 块来确认。
适用场景与限制
适用于排查 OpenViking 记忆插件在本机的安装、配置、连接及服务器健康问题。限制与规则：绝不打印完整 API 密钥或 ovcli.conf 原始内容，仅使用 doctor 的掩码形式；scripts/setup.mjs 需要 TTY，旧版本还需已存在的 ovcli.conf；不要将 claude plugin list 通过管道传给 grep -q；/health 返回 200 仅证明可达性，鉴权需靠带密钥的身份字段或 /api/v1/system/status 证明；ov doctor 即 openviking-server doctor，只验证服务器自身配置，与插件无关；doctor 只读取，未经询问不得停止、重启或杀死用户服务器，也不得编辑 ov.conf；旧代理版本提示的 ov serve 命令不存在，服务器由 openviking-server 启动；OPENVIKING_MEMORY_ENABLED=0 只禁用钩子而不禁用 MCP 工具；OPENVIKING_MCP_URL 对本插件无效。更多症状、确切错误字符串和日志阶段名见 reference.md。
文档
源码与问题：https://github.com/volcengine/OpenViking（插件代码位于 examples/，共享安装器位于 examples/memory-plugin-shared/）。
文档索引（适合 LLM）：https://docs.openviking.ai/llms.txt，其下的 harness 集成页面涵盖安装路径、配置键和已知限制。
https://api.vikingdb.cn-beijing.volces.com/openviking 是火山引擎托管的 OpenViking Service（OpenViking Cloud）：路径前缀是基础 URL 的一部分，仅接受 Authorization: Bearer，其密钥由火山引擎控制台签发而非自托管管理员。