Skip to content

Manual configuration for Claude Code

Route Claude Code through CloudService's native Anthropic Messages endpoint without an installer.

This page is for Claude Code, not Codex. Claude Code uses Anthropic Messages. For Codex's OpenAI Responses provider, use Manual configuration for Codex.

This is the direct, no-npx setup for an existing Claude Code installation. Do not configure it as an OpenAI-compatible provider, and do not add /v1 to ANTHROPIC_BASE_URL.

Choose the URL that matches the key. API-credit keys use https://api.yourdomain.example. Claude token-pack keys use https://api.yourdomain.example/token. The two key types are intentionally not interchangeable.

Connection settings

  • Protocol: Anthropic Messages
  • API-credit base URL: https://api.yourdomain.example
  • Claude token API base URL: https://api.yourdomain.example/token
  • Authentication: file-backed credential through Claude Code's cached apiKeyHelper
  • User settings: ~/.claude/settings.json
  • Secret file: ~/.claude/cloudservice.key

Store the key privately

This prompt reads the key without echoing it or placing it in the command itself:

bash
umask 077
mkdir -p "$HOME/.claude"
printf "CloudService API key: "
IFS= read -r -s CLOUDSERVICE_API_KEY
printf "\n"
printf "%s\n" "$CLOUDSERVICE_API_KEY" > "$HOME/.claude/cloudservice.key"
unset CLOUDSERVICE_API_KEY
chmod 600 "$HOME/.claude/cloudservice.key"

Configure Claude Code

Create ~/.claude/settings.json, or merge the following keys into its existing env object. Preserve any settings you already use.

json
{
  "apiKeyHelper": "cat ~/.claude/cloudservice.key",
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.yourdomain.example",
    "CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY": "1",
    "ANTHROPIC_MODEL": "claude-opus-5",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "claude-haiku-4-5-20251001",
    "ANTHROPIC_CUSTOM_MODEL_OPTION": "fable-5",
    "ANTHROPIC_CUSTOM_MODEL_OPTION_NAME": "Fable 5",
    "ANTHROPIC_CUSTOM_MODEL_OPTION_DESCRIPTION": "Fable 5 via CloudService",
    "CLAUDE_CODE_API_KEY_HELPER_TTL_MS": "900000"
  }
}

If the key came from a Claude token pack, change only ANTHROPIC_BASE_URL in that example to https://api.yourdomain.example/token. Do not use the token URL with an API-credit key.

apiKeyHelper keeps the raw credential out of the settings JSON. Claude Code caches the helper result for 15 minutes and refreshes it after an authentication failure. On Windows, use a PowerShell Get-Content -Raw helper command instead of cat.

CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY queries $ANTHROPIC_BASE_URL/v1/models at startup and adds its Claude entries to the /model picker. With the Claude token origin, that becomes https://api.yourdomain.example/token/v1/models; do not replace the origin setting with /token/v1. Claude Code intentionally filters discovered IDs to names beginning with claude or anthropic, so the three ANTHROPIC_CUSTOM_MODEL_OPTION* entries in the example explicitly add CloudService's public fable-5 ID to the picker. Claude Code refreshes its discovery cache at startup and falls back to the previous cache if a refresh fails. Gateway discovery requires Claude Code 2.1.129 or later.

An earlier version of this example set CLAUDE_CODE_DISABLE_THINKING, which is not a real Claude Code environment variable. The actual flag is CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING, and per Anthropic's own documentation it has no effect on Claude Opus, Claude Sonnet, or Fable models—the only models this guide configures—so the example above omits it.

The main model is Opus 5. ANTHROPIC_DEFAULT_HAIKU_MODEL sends lightweight background work to Haiku, reducing wait time without changing the model used for the main coding turn. The custom Fable entry is only added when the authenticated catalog includes Fable 5; it sends fable-5 to the CloudService gateway and does not expose a provider or backend name. Claude Code streams normal responses and uses prompt caching automatically.

Available Claude models

  • fable-5 (also accepted as claude-fable-5)
  • claude-haiku-4-5-20251001
  • claude-opus-4-6
  • claude-opus-4-7
  • claude-opus-4-8
  • claude-opus-5
  • claude-sonnet-5

Use an exact model ID. You can change the default ANTHROPIC_MODEL value or switch models from Claude Code with /model fable-5 (or another ID from the authenticated picker). CloudService keeps Fable 5’s public identity and handles compatibility automatically.

Verify with a one-token request

This direct probe validates the URL, key, and cheapest Claude route before Claude Code loads its agent prompt.

bash
export ANTHROPIC_BASE_URL="https://api.yourdomain.example"
export ANTHROPIC_AUTH_TOKEN="$(cat "$HOME/.claude/cloudservice.key")"

curl -sS "$ANTHROPIC_BASE_URL/v1/messages" \
  -H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model":"claude-haiku-4-5-20251001","max_tokens":1,"messages":[{"role":"user","content":"K"}]}'

A successful response contains a message ID and a content array. Then run one minimal, non-persistent Claude Code turn. The verification uses --bare, so it passes the user settings file explicitly; an ordinary interactive claude session loads that file normally.

bash
claude --bare --settings "$HOME/.claude/settings.json" \
  -p "Output the single uppercase letter K as your final answer." \
  --model claude-haiku-4-5-20251001 \
  --tools "" \
  --max-turns 1 \
  --no-session-persistence \
  --output-format json

For an interactive check, start claude and run /status. The Anthropic base URL must match the purchased key type—https://api.yourdomain.example for API credit or https://api.yourdomain.example/token for a Claude token pack—and the credential source must show apiKeyHelper.

Keep the key private

Keep cloudservice.key readable only by your user. Never commit it, paste it into support messages, or put a credential in a project-level .claude/settings.json that is tracked by Git.

Automatic configuration

Install the reusable CloudService CLI once, then run it directly—no npx is required:

bash
npm install -g cloudservice@latest
cloudservice

Select Claude Code. The CLI detects whether the key uses API credit or a Claude token pack, backs up the existing user settings, keeps the credential file user-only, and verifies the Anthropic Messages route. Run cloudservice doctor afterward for a repeatable health check.

Enable GitHub skills

Model routing and tool installation are separate. To install Anthropic's official skills marketplace and add bounded public-GitHub read permissions to Claude Code, run:

bash
cloudservice claude-tools

The command verifies that example-skills@anthropic-agent-skills is enabled. It does not grant unrestricted downloads or a blanket shell permission. Claude Code still asks before any operation outside the narrow public-GitHub permissions.

Claude Desktop is separate

The Claude desktop app does not read Claude Code's settings.json or its environment variables. Configure the app through its third-party inference settings instead. See Claude Desktop.

For the upstream gateway behavior and version requirements, see Claude Code's gateway guide.