跳转至

CodeBair Client Integration Guide

This guide exists for one purpose: connect common clients to https://api.codebair.com / https://api.codebair.com/v1.

中文 Quick Start

1. Shared Parameters

  • Base URL: https://api.codebair.com/v1
  • API Key: CodeBair key (sk-...)
  • Model: use a model returned by /v1/models

Some clients use Anthropic- or Gemini-style variables and may not need /v1. Each section below notes that explicitly.

2. Choose Your Client

Client Best for Key configuration
Claude Code terminal users / developers ANTHROPIC_BASE_URL + ANTHROPIC_AUTH_TOKEN
CC Switch users who want a GUI for Claude config import custom config
Codex terminal users / developers config.toml + auth.json
Cursor IDE users Models settings
Cherry Studio desktop chat client users Anthropic provider
Kilo VS Code / Kilo users Anthropic provider + custom base URL
AstrBot users who want a self-hosted bot connected to CodeBair / NewAPI AstrBot admin panel + OpenAI provider
OpenCode developers opencode.json + OPENCODE_CONFIG
OpenClaw developers openclaw.json
Chatbox desktop chat users OpenAI API config
WorkBuddy enterprise chat / office users custom model / OpenAI-compatible
Gemini CLI CLI users GOOGLE_GEMINI_BASE_URL + GEMINI_API_KEY

3. Claude Code

Install

brew install --cask claude-code

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

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

curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

NPM install

npm install -g @anthropic-ai/claude-code
claude --version

Configure settings.json

  • Windows: C:\Users\<username>\.claude\settings.json
  • macOS / Linux: ~/.claude/settings.json
{
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.codebair.com",
    "ANTHROPIC_AUTH_TOKEN": "sk-xxxxxxxxxxxxxxxx"
  }
}

Do not append /v1 to ANTHROPIC_BASE_URL.

Temporary bootstrap if settings.json is ignored

$env:ANTHROPIC_BASE_URL="https://api.codebair.com"
$env:ANTHROPIC_AUTH_TOKEN="sk-xxxxxxxxxxxxxxxx"
claude

Verify

Run:

claude

If Claude opens and responds normally, setup is complete.

4. CC Switch

  1. Open CC Switch
  2. Switch the group to Claude
  3. Choose 自定义配置 / custom configuration
  4. Paste this config and replace the token
{
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.codebair.com",
    "ANTHROPIC_AUTH_TOKEN": "sk-xxxxxxxxxxxxxxxx"
  }
}
  1. Give it a name such as CodeBair
  2. Click 启用 / Enable

5. Codex

Install

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

config.toml

model_provider = "codebair"
model = "gpt-5.4"

[model_providers.codebair]
name = "codebair"
base_url = "https://api.codebair.com/v1"
wire_api = "responses"
requires_openai_auth = true

Context size (important for Codex)

Codex does not always infer the context window for you. To avoid strange behavior on long-context requests, explicitly set the context size on the Codex side whenever your version/config format supports it.

Recommended value:

  • context_window = 1050000
  • max_output_tokens = 128000

If your Codex version or config format does not support those exact fields, set the equivalent context-size and max-output options in your own wrapper/client instead of assuming auto-detection.

auth.json

{
  "OPENAI_API_KEY": "sk-xxxxxxxxxxxxxxxx"
}

Verify

codex

For consistency, the recommended default reference model for Codex examples in this guide is now:

  • gpt-5.4

6. Cursor

In Settings -> Models:

  1. Enable OpenAI API Key
  2. Paste your CodeBair key
  3. Enable Override OpenAI Base URL
  4. Set it to https://api.codebair.com/v1
  5. Add or enable a supported model

7. Cherry Studio

  1. Open Settings -> Model Services -> Add
  2. Choose provider type Anthropic
  3. Fill in:
  4. API URL: https://api.codebair.com
  5. API Key: CodeBair key
  6. Refresh the model list and add the models you need

8. VS Code Kilo

  1. Choose API provider Anthropic
  2. Enable custom base URL
  3. Set:
  4. Base API URL: https://api.codebair.com
  5. API Key: CodeBair key
  6. Test one reply

9. AstrBot

9.1 Install AstrBot from source

The shortest path is:

  1. Deploy AstrBot locally or on your server
  2. Sign in to the AstrBot admin panel
  3. Add a new OpenAI model provider
  4. Set API Base URL to https://api.codebair.com/v1
  5. Switch the default chat model/provider to that new provider

For CodeBair, you really only need to remember two values:

  • API Base URL: https://api.codebair.com/v1
  • API Key: your CodeBair API key
git clone https://github.com/AstrBotDevs/AstrBot.git
cd AstrBot
uv sync
uv run main.py

If you have many plugins later, you can start it with:

uv run --no-sync main.py

Option B: Python virtual environment

macOS / Linux / WSL
git clone https://github.com/AstrBotDevs/AstrBot.git
cd AstrBot
python3 -m venv ./venv
source venv/bin/activate
python -m pip install -r requirements.txt -i https://mirrors.tuna.tsinghua.edu.cn/pypi/web/simple
python main.py
Windows PowerShell
git clone https://github.com/AstrBotDevs/AstrBot.git
cd AstrBot
python -m venv .\venv
.\venv\Scripts\Activate.ps1
python -m pip install -r requirements.txt -i https://mirrors.tuna.tsinghua.edu.cn/pypi/web/simple
python main.py

9.2 Default access

  • Default admin panel: http://localhost:6185
  • Default username: astrbot
  • Default password: astrbot

If you deploy on a server, replace localhost with your server IP or domain.

9.3 Connect AstrBot to CodeBair / NewAPI

  1. Create an API key in CodeBair
  2. Open the AstrBot admin panel and go to Model Providers
  3. Click Add Model Provider
  4. Choose provider type OpenAI
  5. You can name this provider CodeBair

  6. Fill in:

  7. API Base URL: https://api.codebair.com/v1

  8. API Key: your CodeBair API key

Keep the URL exactly like this and do not omit /v1.

Provider name: CodeBair
Provider type: OpenAI
API Base URL: https://api.codebair.com/v1
API Key: sk-xxxxxxxxxxxxxxxx

If you are using your own self-hosted NewAPI instance, you can also use a local address such as:

http://localhost:3000/v1

9.4 Apply the provider

  1. Go to Config
  2. Find the Models section
  3. Set the default chat model/provider to the one you just created
  4. Save the configuration

Once this is saved, AstrBot will send model requests through CodeBair.

9.5 Quick checks

  • AstrBot admin panel opens normally
  • The model provider saves successfully
  • The API Base URL ends with /v1
  • The API key can call models successfully
  • The default chat model/provider has been switched to the new provider

If it does not work, check these three items first:

  • The API URL is exactly https://api.codebair.com/v1
  • The API key is still valid
  • The default model/provider is already switched to CodeBair

9.6 Common mistakes

  • Missing /v1 in the Base URL
  • Extra spaces in the API key, or using a non-CodeBair key
  • The provider was added, but the default chat model/provider was never switched to CodeBair
  • Mixing up https://api.codebair.com and https://api.codebair.com/v1

9.7 References

  • AstrBot deployment: https://docs.astrbot.app/deploy/astrbot/cli.html
  • AstrBot NewAPI provider: https://docs.astrbot.app/providers/newapi.html

10. OpenCode

Create C:\Users\<username>\opencode.json:

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "zenchao": {
      "models": {
        "gpt-5.4": {
          "name": "gpt-5.4",
          "contextWindow": 1050000,
          "maxTokens": 128000
        }
      },
      "npm": "@ai-sdk/openai-compatible",
      "options": {
        "apiKey": "sk-***",
        "baseURL": "https://api.codebair.com/v1"
      }
    }
  }
}

Recommended OpenCode defaults:

  • Model: gpt-5.4
  • Context window: 1050000
  • Max output tokens: 128000

This reduces ambiguity in client-side defaults, especially for longer-context sessions.

Set environment variable:

  • OPENCODE_CONFIG = C:\Users\<username>\opencode.json

Save auth:

opencode auth login
  • Provider ID: codebair
  • Choose Other

Verify:

opencode

Then run /models.

If you add more models later, keep gpt-5.4 as the primary example and append the others after it.

11. OpenClaw

Open config:

openclaw dashboard

or

nano ~/.openclaw/openclaw.json

Use the same JSON structure as the Chinese guide, with provider base URL https://api.codebair.com and your CodeBair API key.

Apply changes:

openclaw gateway restart

12. Chatbox

  • Provider: OpenAI API
  • Base URL: https://api.codebair.com/v1
  • API Key: CodeBair key
  • Model: any supported model from /v1/models

13. WorkBuddy

Look for:

  • custom model
  • OpenAI-compatible
  • custom API

Use:

  • Base URL: https://api.codebair.com/v1
  • API Key: CodeBair key
  • Model: a supported model from /v1/models

14. Gemini CLI

Install

npm install -g @google/gemini-cli
gemini --version

Environment variables

export GOOGLE_GEMINI_BASE_URL="https://api.codebair.com"
export GEMINI_API_KEY="sk-xxxxxxxxxxxxxxxx"

or on Windows PowerShell:

$env:GOOGLE_GEMINI_BASE_URL="https://api.codebair.com"
$env:GEMINI_API_KEY="sk-xxxxxxxxxxxxxxxx"

.env file

  • Windows: C:\Users\<username>\.gemini\.env
  • macOS / Linux: ~/.gemini/.env
GOOGLE_GEMINI_BASE_URL="https://api.codebair.com"
GEMINI_API_KEY="sk-xxxxxxxxxxxxxxxx"

Verify

gemini

14. Troubleshooting

Error Common reason Fix
401 wrong key / extra spaces / not a CodeBair key recopy the key
403 not enough permission / no balance / restriction check account and balance
404 wrong Base URL confirm whether the client needs /v1
429 rate limit retry later with lower concurrency
5xx upstream instability retry with backoff
Model not found wrong model name use a model from /v1/models