AionRouter Client and Coding Tool Integration Guide

Connecting a client to AionRouter requires a matching API URL, key, model ID and protocol. Success means the intended feature sends a request to the correct model, a matching usage record exists and the client parses the result. Saving settings alone does not establish connectivity.

This guide covers Claude Code, Codex CLI, Cline, OpenClaw and chat tools with custom providers on macOS, Windows or Linux. Updates can change features and configuration scope. Codex guidance follows the OpenAI Docs checked for this revision, with official references also retained for other tools.

Prepare for how your client actually runs

Connect one client to one verified model before adding models or automation. Use exact model IDs, not display names, rankings or a model's self-description to infer routing.

Prepare four connection details

Set environment variables first, using the syntax for your shell:

Terminal compatibility

Use the examples for your shell: macOS/Linux use Bash or Zsh; Windows uses PowerShell or CMD. Git Bash/WSL can use the Bash examples, but run all setup and requests in the same environment. The current API root is https://test.aionrouter.io.

Windows examples explicitly use curl.exe to avoid the curl alias in Windows PowerShell 5.1. Check curl --version or curl.exe --version; --fail-with-body requires cURL 7.76.0 or later. Microsoft: curl on Windows · cURL options

Run one shell variant only. Environment variables apply to that terminal and programs started from it. In CMD, run each line separately; at the AIONROUTER_BASE_URL prompt, paste the API root shown above, without a trailing slash. Then enter the actual key, model or voice when prompted. Do not paste Bash export, backslash continuations or heredocs into CMD or PowerShell.

macOS / Linux — Bash / Zsh

export AIONROUTER_BASE_URL='https://test.aionrouter.io'
export AIONROUTER_API_KEY='替换为控制台复制的完整密钥'

Windows — PowerShell

$env:AIONROUTER_BASE_URL = 'https://test.aionrouter.io'
$env:AIONROUTER_API_KEY = Read-Host 'AIONROUTER_API_KEY'

Windows — CMD

set "AIONROUTER_BASE_URL="
set /p "AIONROUTER_BASE_URL=AIONROUTER_BASE_URL: "
set "AIONROUTER_API_KEY="
set /p "AIONROUTER_API_KEY=AIONROUTER_API_KEY: "

Then verify the model list:

macOS / Linux — Bash / Zsh

curl --fail-with-body --silent --show-error \
  "$AIONROUTER_BASE_URL/v1/models" \
  -H "Authorization: Bearer $AIONROUTER_API_KEY"

Windows — PowerShell

curl.exe --fail-with-body --silent --show-error "${env:AIONROUTER_BASE_URL}/v1/models" -H "Authorization: Bearer ${env:AIONROUTER_API_KEY}"

Windows — CMD

curl.exe --fail-with-body --silent --show-error "%AIONROUTER_BASE_URL%/v1/models" -H "Authorization: Bearer %AIONROUTER_API_KEY%"

If this fails, resolve the address, authentication and access permissions first. A successful model list still requires a small request to the target endpoint to verify model and protocol compatibility.

Match Base URLs, endpoints and protocols

Should the Base URL include /v1?

These are common URL-building conventions for the corresponding integrations. With a 404, inspect the final path. /v1/v1/messages, duplicated /chat/completions, or a missing /v1 may indicate an incorrect base URL.

Do not add or remove /v1 for every client indiscriminately, or assume every “API URL” field has the same meaning.

Inspect the final request one part at a time. The API root, versioned Base URL and full endpoint are different levels. Check where the client actually sends requests instead of repeatedly adding or removing /v1 everywhere.

Credentials and URLs must belong to the same service. A AionRouter key sent to an unchanged official endpoint goes to the wrong destination. Changing the URL while retaining an old provider's key also does not validate this platform. A small terminal request with the same model helps distinguish gateway problems from client configuration.

Connect Claude Code and check configuration scope

Claude Code: use Anthropic Messages

Point Claude Code at the gateway root and select an available model supporting Messages:

macOS / Linux — Bash / Zsh

export ANTHROPIC_BASE_URL="$AIONROUTER_BASE_URL"
export ANTHROPIC_AUTH_TOKEN="$AIONROUTER_API_KEY"
export ANTHROPIC_MODEL='替换为支持 Messages 的实际模型 ID'
claude

Windows — PowerShell

$env:ANTHROPIC_BASE_URL = $env:AIONROUTER_BASE_URL
$env:ANTHROPIC_AUTH_TOKEN = $env:AIONROUTER_API_KEY
$env:ANTHROPIC_MODEL = Read-Host 'ANTHROPIC_MODEL'
claude

Windows — CMD

set "ANTHROPIC_BASE_URL=%AIONROUTER_BASE_URL%"
set "ANTHROPIC_AUTH_TOKEN=%AIONROUTER_API_KEY%"
set "ANTHROPIC_MODEL="
set /p "ANTHROPIC_MODEL=ANTHROPIC_MODEL: "
claude

ANTHROPIC_AUTH_TOKEN uses Bearer authentication; ANTHROPIC_API_KEY uses x-api-key. Check for conflicting credential settings, then use /status in Claude Code to verify the address and credential source. Official Claude Code gateway configuration

Test in the same terminal before persisting settings. Do not put real keys in project configuration committed to a repository. CLI environment variables do not automatically configure desktop apps, editor extensions or cloud sessions; follow the instructions for each environment. Claude Code configuration scope

AionRouter supports the Messages route and both authentication methods. Full agent functionality still depends on the model, channel and client version. A successful ordinary Messages request does not verify every tool, context-management feature or extension.

Inspect active configuration before changing it. If terminal calls work but Claude Code takes another route, check for settings files, process variables or other credential sources overriding your setup. Confirm in /status as described by the official gateway guide. Do not immediately delete all saved sign-ins for troubleshooting.

CLI, editor extensions, desktop apps and cloud tasks have different configuration entry points. Editors launched from Dock or the Start menu may not inherit terminal variables. Follow the current documentation for that surface and verify requests in platform records instead of editing an unread file. Claude Code: gateway configuration and scope

Connect Codex CLI and check models and user configuration

Codex CLI: use Responses

Merge this into user-level ~/.codex/config.toml, replacing the model ID and address. Preserve existing settings; do not overwrite the entire file with this example. OpenAI Docs: Codex configuration reference

model = "YOUR_RESPONSES_MODEL_ID"
model_provider = "aionrouter"

[model_providers.aionrouter]
name = "AionRouter"
base_url = "https://test.aionrouter.io/v1"
env_key = "AIONROUTER_API_KEY"
wire_api = "responses"
requires_openai_auth = false

Codex configuration paths by environment

If CODEX_HOME is set, use config.toml under that directory. WSL uses its own Linux home directory; editing the Windows file does not automatically configure WSL. Merge the existing TOML example into the appropriate file. Install and launch each CLI in the same operating-system environment as its configuration; shell syntax does not guarantee every third-party feature is supported. OpenAI Docs: configuration locations · Claude Code: Windows and WSL

Set AIONROUTER_API_KEY in the terminal before starting, then run:

macOS / Linux / Windows

codex

env_key is the environment variable name, not the key value. The current official configuration defines custom-provider wire_api as responses. Do not follow old advice to switch it to chat on failure. Put provider settings in user-level configuration. OpenAI Docs: provider and protocol fields

The gateway provides /v1/responses, but the model and channel must support the events and tools required by the client. Investigate the selected model and response when incompatibilities occur, rather than using a nonexistent protocol value.

Check TOML hierarchy and duplicate definitions. Put top-level model and model_provider before provider tables. Do not duplicate an existing table or place top-level keys inside it. Back up the original, then merge only required fields. OpenAI Docs: gateways and configuration locations

Appearing in /v1/models does not guarantee integration with the full Codex model picker. The native catalog also needs recognized identifiers and metadata. For custom aliases with catalog, context or capability issues, check your client's catalog requirements. Do not substitute a generic list URL for a dedicated catalog or invent an endpoint the platform does not provide.

Configuration and keys may live in different environments. WSL, containers and remote CLIs use their own user directories and process environments. Inspect what the running process loads before concluding the platform rejected it. Saving Windows configuration does not automatically configure a CLI inside WSL.

Connect Cline, OpenClaw and other tools

Cline: choose OpenAI Compatible

Choose OpenAI Compatible in Cline provider settings and enter:

This integration uses a custom provider URL, key and model ID. Set context size, output limits, image support and tool capabilities according to the actual model. A visible option does not prove support. Official Cline OpenAI Compatible guide

After saving, run a small task and check console request records. Passing a model-list or connection check does not validate the complete tool-use workflow.

OpenClaw: match the custom-provider protocol

OpenClaw custom providers can be configured under models.providers. Common mappings are below; check field names against your version:

openai-completions is OpenClaw's adapter name for the corresponding Chat-compatible connection. It does not mean requests should use the legacy /v1/completions. Choose openai-responses only when the backend supports Responses. Official OpenClaw custom-provider configuration

Check which agent receives the configuration and whether an existing model catalog or credentials override it. Do not overwrite the current environment with an entire configuration file from another installation.

Cursor and other custom-provider clients

Cursor

Cursor supports bringing API keys for some providers. Connecting it to AionRouter also requires a suitable custom service URL setting in the current version. Pasting a AionRouter key into the official OpenAI key field alone does not route requests to AionRouter.

If your version offers a custom or override URL, enter the root or /v1 base URL according to that field's meaning, then select a compatible model. Without that setting, this tutorial does not constitute a verified integration.

Bring-your-own-key support does not cover all Cursor features. Tab completion, for example, still uses its built-in models. A single completion appearing or not appearing in AionRouter logs cannot validate every client setting. Official Cursor API key documentation

Cherry Studio, LobeChat and similar chat tools

For tools whose current version supports custom OpenAI-compatible providers:

1. Create or select a custom provider and confirm whether it uses Chat or Responses.
2. Enter the API URL, key and actual model ID as required by the fields.
3. If model-list refresh is available, check the service address it reads. Otherwise, add models manually as instructed.
4. Save, send a small request and check usage records.

Menu names and model discovery change by version. Clicking a button is not proof of successful integration, and automatic model import is not universal.

AionRouter desktop client entry

You can also visit the site's desktop client page for downloads. Follow the actual version's installation, login and model-configuration workflow. A download page does not prove that every model or protocol is supported by a client's settings.

Match locally entered pricing and context to the real model. Some tools require manual context windows, output limits and prices for estimates. These settings do not change platform capabilities or billing. Do not copy another model's values without evidence; estimates do not replace actual usage records.

A supplied key may not power every feature. A tool can combine custom models, built-in completion, other providers and separately charged features. Determine what actually passes through AionRouter from feature settings and usage records, not a model name shown in the main window.

Verify real requests before moving to daily work

Verify that requests really use AionRouter

Complete these checks in order:

1. Make a minimal API request with the same address and key to verify the target model and endpoint.
2. Send a small, recognizable request in the client and note its time and model ID.
3. Match the call in consumption logs, using the request ID if necessary.
4. For agent use, also validate a controlled tool-use task.

A model's answer to “which model are you?” does not independently prove routing. Other logins, fallback providers or built-in models may be active. Check the effective settings and request records together.

Verify these four levels in order:

1. Basic connection: complete a minimal request with the same URL, key and model.
2. Client conversation: send an identifiable short prompt and check the time, model and usage record.
3. Tool loop: run a bounded task with inspectable results in a temporary directory and verify arguments and result submission.
4. Real work sample: use an anonymized project excerpt or small task to check context, streaming, recovery and costs before expanding.

Migrate one client or environment at a time and keep a reversible configuration. Avoid changing URLs, credentials, protocols and every model together. Teams can share nonsensitive provider names, URLs and model IDs while assigning keys by user or purpose.

The platform records requests reaching it; a client may also have subscriptions, built-in features or service charges. Reconcile each billing party separately. One successful platform call does not cover every client fee.

Troubleshooting and common questions

Troubleshooting connections

A 404 does not establish an invalid key. Authentication failure does not automatically require signing out of every client. Check the specific error, final URL and effective settings first.

Frequently asked questions

Can one API Key be used in several tools?

Yes, if its settings allow the models and request origins. Separate keys per tool or user make usage management and revocation easier.

Why does my configuration fail after switching models?

The new model may support different endpoints, tools or parameters. Visibility does not guarantee suitability for the same agent configuration. Recheck the protocol and capabilities.

Will using a AionRouter key also consume the client's included quota?

That depends on the client, feature, plan and routing settings. The platform records only requests actually sent to AionRouter and cannot guarantee that third-party clients incur no other charges.

Can client settings turn a Chat model into a complete Responses or Messages model?

Names and protocol selectors alone cannot guarantee that. The gateway, channel and upstream model must support the actual interactions, especially streaming events and tool calls.

If the terminal works but the editor fails, check where it runs. Record configuration paths and environment sources for local editors, Remote SSH, development containers and WSL separately. Restart the process that actually sends model requests, not an unrelated terminal.

Stop expanding call chains when an agent keeps retrying. Save errors and request details, return to a verified small request, and check protocol, tools and model. More retries, larger context and new tasks do not substitute for diagnosis.

Further reading

• API authentication and key management
• Text generation API: endpoints and response formats
• Quick start
• Model Marketplace