Skip to main content

Connect Claude Code with Zeldoc.ai

Claude Code is Anthropic's terminal-based coding agent. It talks to models over the Anthropic Messages API, and Zeldoc.ai serves that API at /v1/messages. That means you can point Claude Code at Zeldoc.ai the same way you would point it at an LLM gateway, and use ZDev or any other model from your Zeldoc.ai model list.

Prerequisites​

Configure Claude Code​

Claude Code reads three environment variables to route requests to Zeldoc.ai:

VariableValuePurpose
ANTHROPIC_BASE_URLhttps://api.zeldoc.aiWhere to send requests
ANTHROPIC_AUTH_TOKENYour Zeldoc.ai API keySent as Authorization: Bearer
ANTHROPIC_MODELzdev[1m]Which model to use
No /v1 in the base URL

Claude Code appends /v1/messages to the base URL itself. Use https://api.zeldoc.ai, not https://api.zeldoc.ai/v1 — otherwise requests go to /v1/v1/messages and fail.

Why zdev[1m]?

Claude Code doesn't know the ZDev model, so it assumes a 200k-token context window and compacts your conversation early. Appending [1m] tells Claude Code the model has a 1M context window; the suffix is stripped before the request is sent to Zeldoc.ai. You can also set CLAUDE_CODE_MAX_CONTEXT_TOKENS=1000000 instead of using the suffix.

Try it from the shell​

For a first test, export the variables in a terminal and start Claude Code from the same shell:

export ANTHROPIC_BASE_URL=https://api.zeldoc.ai
export ANTHROPIC_AUTH_TOKEN=your-api-key
export ANTHROPIC_MODEL="zdev[1m]"
claude

Shell exports only apply to that terminal session. Once it works, move the configuration to a settings file so it applies everywhere Claude Code runs.

Persist it in a settings file​

Add an env block to ~/.claude/settings.json (on Windows, %USERPROFILE%\.claude\settings.json):

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.zeldoc.ai",
    "ANTHROPIC_AUTH_TOKEN": "your-api-key",
    "ANTHROPIC_MODEL": "zdev[1m]",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "zdev",
    "CLAUDE_CODE_SUBAGENT_MODEL": "zdev[1m]"
  }
}

The two extra variables keep everything on Zeldoc.ai:

  • ANTHROPIC_DEFAULT_HAIKU_MODEL — Claude Code uses its haiku alias for background work such as generating session titles. Pointing the alias at ZDev keeps those requests on the same model instead of trying to resolve a Claude model name.
  • CLAUDE_CODE_SUBAGENT_MODEL — Subagents spawned by Claude Code use this model.
Keep your key out of shared files

Put the env block in your user settings (~/.claude/settings.json) or in a project's .claude/settings.local.json. Don't put your API key in a project's .claude/settings.json — that file is committed and shared with everyone who clones the repository.

Use other Zeldoc.ai models​

Nothing in this setup is specific to ZDev. Any model ID from your Zeldoc.ai model list works, including the models served through the router — see list your available models. Switch models by changing ANTHROPIC_MODEL, or per session:

claude --model zdev-2

Inside a session, /model <model-id> switches as well. Model IDs that Claude Code doesn't recognise trigger a one-line warning at startup about missing model metadata. That warning is expected and harmless.

Verify the connection​

Start Claude Code and run /status. The Status tab should show:

  • a base URL line pointing at https://api.zeldoc.ai
  • an Auth token line naming ANTHROPIC_AUTH_TOKEN

Then send any prompt. A normal reply confirms Zeldoc.ai is serving your requests. If the request fails with 401, double-check the API key; if it fails with a 404, check that the base URL has no /v1 suffix.

Things to know​

  • Your claude.ai subscription is not used while ANTHROPIC_AUTH_TOKEN is set. All requests go to Zeldoc.ai and count against your Zeldoc.ai key. Unset the variable (or remove the env block) to return to your claude.ai login.
  • Some claude.ai features are unavailable with a gateway credential active, including Remote Control, voice dictation, and claude.ai connectors. Claude Code prints a notice about this at startup.
  • The Claude Code desktop app reads gateway settings from its own third-party inference configuration, not from settings.json. The setup above applies to the CLI and the IDE extensions launched from a shell with these variables set.
  • Anthropic does not officially support non-Claude models through a gateway. ZDev works well with Claude Code in our testing, but model-specific features such as extended thinking depend on the model you choose.