Vtrix Doctor | Vtrix API Docs

Overview

Vtrix Doctor is a local diagnostic and setup helper for agent tools that connect to Vtrix. It checks local config files, Vtrix Base URLs, model IDs, API key sources, and protocol settings, then prints a redacted report.

The current workflow is macOS-first. Vtrix Doctor can check Cursor, and can configure or repair Codex, Claude Code, OpenCode, Aider, Crush, Qwen Code, Goose, Hermes, and OpenClaw after you confirm the write plan.

Use it before manual edits

Run Vtrix Doctor first when an agent tool reports 401, model not found, unsupported endpoint, or provider mismatch. The default scan does not modify files or send API requests.

Install

The installer downloads a prebuilt agent-doctor binary from the Vtrix docs domain. It does not read local config files or API keys during installation.

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

After installation, run:

agent-doctor

Optional installer variables:

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

Recommended Flow

Install or update Vtrix Doctor.
Run agent-doctor scan --all to find local agent tools.
Run agent-doctor check <tool-id> to inspect one tool.
For supported tools, run agent-doctor setup <tool-id> --model MODEL_ID.
Run agent-doctor test only when you want a real live API check.

Live checks are optional

agent-doctor test sends one tiny request with your local Vtrix API key after confirmation. Default scans and checks do not send API requests.

Common Commands

Scan local tools

agent-doctor scan --all

Check one tool

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

Export a redacted report

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

Start the interactive setup wizard

agent-doctor setup

The wizard scans local tools, asks for your Vtrix API key and model ID, shows the planned config changes, and writes only after confirmation.

Configure a supported tool directly

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 and Hermes are supported by the current Doctor flow. Run agent-doctor setup <tool-id> --model MODEL_ID to write the Vtrix settings after confirmation.

Repair an existing config

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

Repair uses the same confirmation and backup flow as setup.

Run a live validation

agent-doctor test

Supported Tools

Tool	Scan	Config check	Setup / repair	Live validation
Codex	Supported	Supported	Supported	Supported
Claude Code	Supported	Supported	Supported	Supported
OpenCode	Supported	Supported	Supported	Supported
Aider	Supported	Supported	Supported	Supported
Crush	Supported	Supported	Supported	Supported
Qwen Code	Supported	Supported	Supported	Supported
Goose	Supported	Supported	Supported	Supported
Hermes	Supported	Supported	Supported	Supported
OpenClaw	Supported	Supported	Supported	Supported
Cursor	Supported	Supported	Not supported	Not supported

Vtrix Doctor writes the endpoint shape expected by each tool. Some tools use the OpenAI-compatible root endpoint, some use a chat-completions endpoint, and Claude Code uses the Anthropic-compatible endpoint.

Safety

scan, check, and the default command do not modify config files.
Default checks do not send live API requests.
Reports redact API keys.
setup and repair show a write plan before changing files.
Config writes create backups first.
test asks for confirmation before sending a tiny live request.
Live validation blocks sending your API key to non-Vtrix hosts.

Keep API keys private

Do not paste full API keys into public issues, chats, or screenshots. Use agent-doctor --json when you need a redacted report for support.

Troubleshooting

The tool is not detected

Confirm the tool command is installed and available in your current terminal:

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

For desktop apps such as Cursor, Vtrix Doctor may still be able to inspect known config paths even when no CLI command is available.

Setup command is not recognized

Reinstall or update Vtrix Doctor, then run the setup command again:

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

Which model should I use

Use the model ID shown in the Vtrix model page for your target model. Common examples:

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

Will live validation cost money

agent-doctor test sends one tiny request and may consume a very small number of tokens. It asks for confirmation first; default checks do not send requests.