API key guide

Client setup guide

Connect an API key from your dashboard to Codex, Claude Code, Cherry Studio, TRAE, Hermes, OpenClaw, opencode, or any OpenAI-compatible client.

Supported clients

CodexClaude CodeCherry StudioTRAEHermesOpenClawopencodeOpenAI SDK

Back to API keys

Site base URL

https://cn.caiaiu.com

Create and copy your key

Create an API key in the dashboard. Copy the full key immediately and store it somewhere safe.

Confirm the key group

Keys must be bound to an available group. If a model is unavailable, billing looks wrong, or traffic hits the wrong group, check the key group first.

Configure your client

OpenAI-compatible clients usually need a Base URL ending in /v1. Claude Code gateway settings usually use the site Base URL without /v1.

Codex

Codex step-by-step

GitHub

What you will do

This is the easiest way to point official Codex at CaiAI. You download a small config helper, paste your URL and key, click Use, then restart. The helper only rewrites local Codex settings. It does not take over your OpenAI account. Switching back to official Codex uses the same screen.

1. Download the config helper

Open this GitHub page in a browser. On the right, click Releases, then download the installer for your computer. Apple Silicon Mac: CodexPlusPlus-*-macos-arm64.dmg. Intel Mac: macos-x64.dmg. Windows: windows-x64-setup.exe. Install it, then open 「Codex++ 管理工具」 — that is the settings window. Do not open the official Codex app yet.

GitHub

https://github.com/BigPizzaV3/CodexPlusPlus

Download the installer that matches your computer

2. Create a CaiAI key first

On caiaiu.com, click API Keys in the left menu. Click Create key, give it any name, pick a plan or balance group, then create. Copy the full key immediately — you will paste it in the next step. If you lose it, create another one.

Left menu → API Keys. This is where you copy the key

Create a key and choose a plan or balance group, then copy it

3. Add CaiAI in the settings window

In 「Codex++ 管理工具」, click 供应商配置 on the left. Click 添加供应商. Fill only the fields below and leave everything else at the default. Mainland China URL is https://cn.caiaiu.com — do not add /v1.

Site base URL

https://cn.caiaiu.com

名称: anything, for example Caiai
接入模式: 纯 API
上游协议: Responses API
Base URL: https://cn.caiaiu.com (mainland). Do not append /v1.
Key: paste the CaiAI key you just copied

This list is the main screen. After saving, you will click 使用 here, then 重启 Codex++ in the top right

Fill Base URL and Key on this form, then click 从上游获取 to pull models

4. Fetch models, save, then click 使用

On the same form, click 从上游获取. Wait for the model list to appear — you do not need to edit it. Click 保存. Back on the provider list, find the Caiai card and click 使用 until it shows 使用中. Filling the form is not enough; 使用 is what actually switches Codex.

Done for this step when the card shows 使用中

5. Click 重启 Codex++

Look at the top-right of the settings window and click 重启 Codex++. After it restarts, always launch Codex from this helper. If you open official Codex by itself, the new settings will not load.

Switch back to official Codex

Same screen: select the 官方登录 provider, click 使用, then click 重启 Codex++. This only rewrites local config files. Your OpenAI account is unchanged.

If something feels stuck

Keys always live in the left API Keys menu on caiaiu.com.
Mainland URL is https://cn.caiaiu.com, with no /v1.
The three clicks that matter: 保存 → 使用 → 重启 Codex++.
Using Codex in the terminal instead? See Codex CLI below.

Codex

Use with Codex CLI

Official docs

Install Codex CLI

Node.js is required. After install, check that codex starts cleanly.

Terminal

npm install -g @openai/codex
codex --version

Configure ~/.codex/config.toml

Add a custom provider that points at the CaiAI OpenAI-compatible endpoint. Replace the model name with one supported by your key group.

~/.codex/config.toml

model_provider = "caiai"
model = "glm-5.2"
review_model = "glm-5.2"
model_reasoning_effort = "high"
disable_response_storage = true
network_access = "enabled"

[model_providers.caiai]
name = "CaiAI API"
base_url = "https://cn.caiaiu.com"
env_key = "CAIAI_API_KEY"
wire_api = "responses"

[features]
goals = true

Set the API key environment variable

Do not commit real keys. Replace YOUR_API_KEY with the key copied from the dashboard.

macOS / Linux

export CAIAI_API_KEY="YOUR_API_KEY"
codex

PowerShell

$env:CAIAI_API_KEY="YOUR_API_KEY"
codex

Run and verify

Enter your project directory, then run codex.
If auth fails, confirm the environment variable is set in the current shell.
If the model is unavailable, check the key group and available channels in the dashboard.
If the network blocks outbound requests, test the models endpoint with curl first.

curl

curl "https://cn.caiaiu.com/v1/models" \
  -H "Authorization: Bearer YOUR_API_KEY"

Claude Code

Use with Claude Code

Official gateway docs

Install Claude Code

Prefer the official install script. Use npm only if that fits your environment better.

macOS / Linux

curl -fsSL https://claude.ai/install.sh | bash
claude --version

Windows PowerShell

irm https://claude.ai/install.ps1 | iex
claude --version

Temporary environment variables

Good for a first test. Values disappear when the shell closes — write them into a user-level config once they work.

macOS / Linux

export ANTHROPIC_BASE_URL="https://cn.caiaiu.com"
export ANTHROPIC_AUTH_TOKEN="YOUR_API_KEY"
export CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1
export CLAUDE_CODE_ATTRIBUTION_HEADER=0
claude

PowerShell

$env:ANTHROPIC_BASE_URL="https://cn.caiaiu.com"
$env:ANTHROPIC_AUTH_TOKEN="YOUR_API_KEY"
$env:CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC="1"
$env:CLAUDE_CODE_ATTRIBUTION_HEADER="0"
claude

Write ~/.claude/settings.json

This is the user-level config for long-term use. Do not put real keys into a project-local .claude/settings.json.

~/.claude/settings.json

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://cn.caiaiu.com",
    "ANTHROPIC_AUTH_TOKEN": "YOUR_API_KEY",
    "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": "1",
    "CLAUDE_CODE_ATTRIBUTION_HEADER": "0"
  }
}

Cherry Studio

Use with Cherry Studio

Official docs

Add an OpenAI-compatible provider

Open Cherry Studio provider settings and add a custom OpenAI-compatible provider. Use the /v1 Base URL and the API key from your dashboard.

Provider

Provider: OpenAI Compatible / Custom OpenAI
API Key: YOUR_API_KEY
Base URL: https://cn.caiaiu.com/v1
Model: glm-5.2

Models and verification

After saving, add a model name supported by your key group, such as glm-5.2. If the model list fails to load, verify Base URL and API key with curl first.

curl

curl "https://cn.caiaiu.com/v1/models" \
  -H "Authorization: Bearer YOUR_API_KEY"

TRAE

Use with TRAE

Official docs

Configure a custom model

In TRAE model or AI settings, choose a custom OpenAI-compatible provider. Use the /v1 Base URL and your dashboard API key.

Provider

Provider: OpenAI Compatible / Custom OpenAI
API Key: YOUR_API_KEY
Base URL: https://cn.caiaiu.com/v1
Model: glm-5.2

Recommended checks

The model name must match a model supported by the key group.
If your TRAE build has no custom provider entry, upgrade to a version that supports custom providers first.

Hermes

Use with Hermes

Official docs

Provider configuration

Point Hermes at an OpenAI-compatible endpoint. If the UI exposes baseUrl, fill in the /v1 address. Keep the same address in env vars or config files.

JSON

{
  "provider": "openai",
  "baseUrl": "https://cn.caiaiu.com/v1",
  "apiKey": "YOUR_API_KEY",
  "model": "glm-5.2"
}

Connection check

Send a short message first instead of a long task.
On failure, check the key group, model name, and /v1 path first.

OpenClaw

Use with OpenClaw

Official docs

Note: OpenClaw cache reuse can be unreliable

Long sessions, frequent model switches, or cross-project jumps may prevent OpenClaw from reusing context cache stably, so real spend can be higher than expected. Validate with small tasks before broader use.

Configure an OpenAI-compatible provider

Add an OpenAI-compatible endpoint in OpenClaw provider or model settings. Use the /v1 Base URL and a dashboard API key.

Provider

Provider: OpenAI Compatible / Custom OpenAI
API Key: YOUR_API_KEY
Base URL: https://cn.caiaiu.com/v1
Model: glm-5.2

Lower billing risk

Create a separate capped key for OpenClaw so cache misses or retries cannot drain the main balance.
Review a few real task charges before raising the cap.

opencode

Use with opencode

Official docs

Note: opencode cache reuse can be unreliable

opencode may replay context or reshape requests during some tasks, which can lower cache hit rate. Use a separately capped key for opencode.

Configure opencode.json

Add a provider in the opencode config and point baseURL at the CaiAI OpenAI-compatible /v1 endpoint. The sample disables store and pins build/plan agents to the same model for more stable cost and behavior.

opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "caiai": {
      "name": "CaiAI API",
      "options": {
        "baseURL": "https://cn.caiaiu.com/v1",
        "apiKey": "YOUR_API_KEY"
      },
      "models": {
        "glm-5.2": {
          "name": "GLM-5.2",
          "options": {
            "store": false
          }
        }
      }
    }
  },
  "agent": {
    "build": {
      "model": "caiai/glm-5.2",
      "options": {
        "store": false
      }
    },
    "plan": {
      "model": "caiai/glm-5.2",
      "options": {
        "store": false
      }
    }
  }
}

Quota advice

Create a dedicated API key for opencode and enable a total spend limit.
If the same task charges repeatedly, lower the key limit or pause that client first.

Manual

Manual setup for other clients

OpenAI SDK / compatible clients

If the client supports a custom OpenAI Base URL, fill in the baseURL below plus your API key.

Node.js

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.CAIAI_API_KEY,
  baseURL: "https://cn.caiaiu.com/v1"
});

const response = await client.chat.completions.create({
  model: "glm-5.2",
  messages: [{ role: "user", content: "Hello" }]
});

console.log(response.choices[0]?.message?.content);

Verify with curl

Confirm network, key, and Base URL with a minimal request before configuring an IDE or CLI tool.

Terminal

curl "https://cn.caiaiu.com/v1/models" \
  -H "Authorization: Bearer YOUR_API_KEY"

Checklist

Common troubleshooting

401 / unauthorized

Check that the API key was copied in full, the environment variable is active in the current shell, and the key is still enabled.

404 / endpoint not found

Confirm whether Base URL has an extra or missing /v1. OpenAI-compatible clients usually need a URL ending in /v1.

model not found

The model name must exist in the current key group. Check recommended models in available channels or the key usage dialog.

quota exceeded

The key limit, account balance, or group quota may be exhausted. Check balance and key limits in the dashboard.