Claude Code

Revision 2 · Updated 2026-11-12 · 4 min read

Connect Claude Code CLI to Runtoken.

Prerequisites#

Before configuring the connection, prepare:

• A working Claude Code installation. Check with claude --version; see the official instructions for installation and upgrades.
• A Runtoken platform API key.
• A model ID supporting Anthropic Messages and the required tool calls.

Connection settings#

Use these settings for the Messages interface. File and command operations run in the client's environment under its permission controls.

ANTHROPIC_AUTH_TOKEN sends a bearer token in a different header. This guide uses ANTHROPIC_API_KEY for the Messages route; do not configure both credentials for the same test.

Set credentials and launch#

Start in a separate terminal and an empty test directory. The following commands affect the current shell and programs launched from it; they do not edit a shell profile or Claude Code settings file. If your organization manages these settings, check with its administrator before changing them.

mkdir runtoken-claude-test
cd runtoken-claude-test
unset ANTHROPIC_AUTH_TOKEN
export ANTHROPIC_BASE_URL="https://api.runtoken.net"
export ANTHROPIC_API_KEY="YOUR_PLATFORM_KEY"
claude --model "YOUR_MODEL_ID"

New-Item -ItemType Directory -Path runtoken-claude-test
Set-Location runtoken-claude-test
Remove-Item Env:ANTHROPIC_AUTH_TOKEN -ErrorAction SilentlyContinue
$env:ANTHROPIC_BASE_URL = "https://api.runtoken.net"
$env:ANTHROPIC_API_KEY = "YOUR_PLATFORM_KEY"
claude --model "YOUR_MODEL_ID"

Replace the example credentials before running the commands. If the test directory already exists, choose another empty directory.

The commands clear ANTHROPIC_AUTH_TOKEN only in the test shell to avoid conflicting credentials. Keep existing settings unchanged elsewhere. An interactive launch may ask you to approve the API key and trust the test directory; review those prompts and keep normal tool permissions enabled.

Check the connection and file task#

Once Claude Code opens, run the following command inside the session.

/status

Check the gateway address, active credential source and selected model. The labels may differ by CLI version. An existing settings file or managed configuration can change the effective settings, so inspect the running session rather than relying on what you exported.

Send a short text request, then look for its matching request record in Runtoken. Use the time, model and platform key to identify it; check the request status and available usage or charge information. A reply alone does not prove that the request used this gateway.

Check a file task#

In the empty test directory, ask Claude Code to perform this small task.

Create a file named greeting.py containing a greet(name) function.
The function should return "Hello, " followed by the supplied name.
Do not install dependencies or access the network.
After creating the file, read it back and explain what it does.

After reviewing the proposed changes, approve only the file operations needed for the task. Then send a second instruction.

Update greet(name) so an empty name returns "Hello, friend".
Read the updated file back and describe the change.

Inspect the actual file and diff. Check that the follow-up succeeds after tool results are returned, and match the resulting model requests in Runtoken. This tests more of the agent loop than a single text reply; it does not establish support for every Claude Code feature.

Capabilities and limits#

Runtoken does not automatically convert protocols. Use the Messages route for the model selected here; an OpenAI Chat model cannot be substituted solely by changing the model ID.

Claude Code may send additional headers and body fields beyond a basic Messages example. A successful minimal API call is useful for diagnosis, but does not validate those features. Token counting and model discovery also need separate checks.

Troubleshooting#

Use the effective configuration and the platform request record to narrow down a failure.

When reporting an issue, include the CLI version, operating system, model ID and a request ID if available. Remove credentials and private project content.

Restore settings and further reading#

Restore the previous setup#

Exit Claude Code and close the test terminal. Since these instructions do not change persistent configuration, later launches use the environment and settings they normally inherit.

If you saved the gateway values in a shell profile or settings file yourself, restore those specific entries from your original configuration. Do not delete the entire settings file or log out of an existing account just to remove this test.

Further reading#

For the underlying request format, see Anthropic Messages. Shared gateway behavior is covered in the integration guide.

See the official gateway connection guide, model configuration and gateway compatibility requirements for client settings.