⌘K

Vtrix Doctor

使用 Vtrix Doctor 检查本地 Agent 工具的 Vtrix Base URL、API Key 和模型配置，并为支持的工具执行一键配置。

概述

Vtrix Doctor 是面向本地 Agent 工具的诊断和配置助手。它会读取本机常见工具配置，检查 Vtrix Base URL、模型 ID、API Key 来源和协议设置，并输出脱敏诊断报告。

当前流程优先支持 macOS。Vtrix Doctor 可检查 Cursor, 并已可在确认后自动配置或修复 Codex、Claude Code、OpenCode、Aider、Crush、Qwen Code、Goose、Hermes 和 OpenClaw。

先检查，再手动改配置

当本地 Agent 工具出现 401、模型不存在、接口不支持、provider 走错等问题时，建议先运行 Vtrix Doctor。默认扫描不会修改文件，也不会发送真实 API 请求。

安装

安装脚本会从 Vtrix 文档域名下载预构建的 agent-doctor 二进制。安装过程不会读取本机配置文件或 API Key。

curl -fsSL "https://agent-docker.vtrix.ai/downloads/vtrix-doctor/install.sh" | sh

安装完成后运行：

agent-doctor

可选安装变量：

AGENT_DOCTOR_VERSION=latest
AGENT_DOCTOR_INSTALL_DIR=/usr/local/bin
AGENT_DOCTOR_BASE_URL=https://agent-docker.vtrix.ai/downloads/vtrix-doctor/bin

推荐流程

  1. 安装或更新 Vtrix Doctor。
  2. 运行 agent-doctor scan --all 扫描本机工具。
  3. 运行 agent-doctor check <tool-id> 检查单个工具。
  4. 对支持的工具运行 agent-doctor setup <tool-id> --model MODEL_ID。
  5. 只有需要真实连通性验证时，再运行 agent-doctor test。
实时验证是可选步骤

agent-doctor test 会在确认后使用本机 Vtrix API Key 发起一次极小请求。默认扫描和检查不会发送 API 请求。

常用命令

扫描本地工具

agent-doctor scan --all

检查单个工具

agent-doctor check codex
agent-doctor check claude-code
agent-doctor check aider
agent-doctor check crush
agent-doctor check qwen-code
agent-doctor check goose
agent-doctor check hermes
agent-doctor check openclaw
agent-doctor check cursor

输出脱敏报告

agent-doctor --json
agent-doctor check codex --json

进入交互式配置向导

agent-doctor setup

向导会扫描本机工具，询问 Vtrix API Key 和模型 ID，展示将要写入的配置变更，并且只在确认后写入。

直接配置支持的工具

agent-doctor setup codex --model gpt-5.3-codex
agent-doctor setup claude-code --model claude-sonnet-4-5
agent-doctor setup aider --model gpt-5.3-codex
agent-doctor setup crush --model gpt-5.3-codex
agent-doctor setup qwen-code --model qwen3.7-max
agent-doctor setup goose --model gpt-5.3-codex
agent-doctor setup hermes --model gpt-5.3-codex
agent-doctor setup openclaw --model gpt-5.3-codex

OpenClaw 和 Hermes 已由当前 Doctor 流程支持。确认写入计划后，可运行 agent-doctor setup <tool-id> --model MODEL_ID 写入 Vtrix 配置。

修复已有配置

agent-doctor repair codex
agent-doctor repair claude-code
agent-doctor repair aider
agent-doctor repair crush
agent-doctor repair qwen-code
agent-doctor repair goose
agent-doctor repair hermes
agent-doctor repair openclaw

修复流程和配置流程一样，会先展示变更计划并创建备份，确认后才写入。

实时验证

agent-doctor test

支持工具

工具扫描配置检查自动配置 / 修复实时验证
Codex支持支持支持支持
Claude Code支持支持支持支持
OpenCode支持支持支持支持
Aider支持支持支持支持
Crush支持支持支持支持
Qwen Code支持支持支持支持
Goose支持支持支持支持
Hermes支持支持支持支持
OpenClaw支持支持支持支持
Cursor支持支持暂不支持暂不支持

Vtrix Doctor 会按不同工具写入对应的接口形态。有些工具使用 OpenAI-compatible 根地址，有些工具使用 chat completions 地址，Claude Code 使用 Anthropic-compatible 地址。

安全边界

  • scan、check 和默认命令不会修改配置文件。
  • 默认检查不会发送实时 API 请求。
  • 输出报告会脱敏 API Key。
  • setup 和 repair 写入前会展示变更计划。
  • 写入配置前会创建备份。
  • test 会在用户确认后才发送极小请求。
  • 实时验证会阻止向非 Vtrix 域名发送 API Key。
保护 API Key

不要把完整 API Key 粘贴到公开 Issue、聊天窗口或截图中。需要排查时优先使用 agent-doctor --json 生成脱敏报告。

故障排查

未检测到某个工具

确认该工具是否已安装，并且命令是否在当前终端的 PATH 中：

which codex
which claude
which aider
which crush
which qwen
which goose
which openclaw
which cursor

对于 Cursor 这类桌面应用，即使没有 CLI 命令，Vtrix Doctor 也可能通过已知配置路径完成部分检查。

setup 命令不识别

重新安装或更新 Vtrix Doctor，然后重新运行 setup 命令：

curl -fsSL "https://agent-docker.vtrix.ai/downloads/vtrix-doctor/install.sh" | sh
agent-doctor setup openclaw --model gpt-5.3-codex

模型 ID 应该填什么

使用 Vtrix 模型页面展示的模型 ID。常见示例：

gpt-5.3-codex
claude-sonnet-4-5
qwen3.7-max

实时验证会产生费用吗

agent-doctor test 会发送一次极小请求，可能产生极少量 token 消耗。该命令会在发送前提示确认；默认检查不会发送请求。