CodeBair 用户部署指南（客户端接入篇）¶

适用对象：需要在本地开发工具/CLI 中接入 CodeBair 模型接口的用户。

统一接入参数（OpenAI 兼容）：

Base URL：https://api.codebair.com/v1
API Key：你在 CodeBair 后台申请的密钥（通常以 sk- 开头）

安全提醒：API Key 仅用于本地开发环境或服务端，不要提交到 Git 仓库。

1. Claude Code 安装与配置¶

1.1 安装方式¶

Homebrew（macOS / Linux）¶

brew install claude-code

NPM 安装（跨平台）¶

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

Windows PowerShell¶

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

Windows CMD¶

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

WSL（Ubuntu）¶

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

1.2 NPM 安装 Windows 额外说明¶

使用管理员权限打开 PowerShell/CMD 可减少全局安装权限问题。
若提示权限错误，可执行：

npm config set prefix "$env:APPDATA\\npm"

安装后若提示命令不存在，重开终端并确认 %APPDATA%\\npm 在 PATH 中。

1.3 Claude Code CLI 配置文件指南¶

常见配置文件位置（不同版本可能存在差异）：

手动配置文件（旧路径）：
Windows: C:\Users\用户名\.claude.json
macOS / Linux: ~/.claude.json
新版目录配置（推荐）：
Windows: C:\Users\用户名\.claude\settings.json
macOS / Linux: ~/.claude/settings.json

示例（settings.json）：

{
  "providers": {
    "openai": {
      "api_key": "sk-xxxx",
      "base_url": "https://api.codebair.com/v1"
    }
  },
  "default_provider": "openai",
  "default_model": "deepseek-chat"
}

1.4 VS Code 集成本地 Claude Code¶

在 VS Code 终端中确保 claude --version 可执行。
如果扩展支持自定义 API 端点，填入：
OpenAI API Key = 你的 CodeBair Key
Override OpenAI Base URL = https://api.codebair.com/v1

1.5 cc-switch 安装（可选）¶

参考发布页：https://github.com/farion1231/cc-switch/releases/tag/v3.12.3

Windows 推荐下载 .msi 普通安装包
安装后按工具向导配置 Claude / OpenAI 兼容端点

2. Gemini CLI 配置指南¶

2.1 前置条件¶

已安装 Gemini CLI（按官方说明）

2.2 CodeBair 接入要点¶

若 Gemini CLI 支持 OpenAI 兼容参数：
API Key = CodeBair Key
Base URL = https://api.codebair.com/v1
若仅支持 Gemini 原生协议，请通过代理/网关转换后再接入。

3. Codex 配置指南¶

3.1 前置条件¶

已安装 Codex CLI

3.2 安装方式¶

npm 全局安装¶

npm install -g @openai/codex

yarn 安装¶

yarn global add @openai/codex

3.3 `config.toml` 配置¶

示例：

provider = "openai"
model = "deepseek-chat"
base_url = "https://api.codebair.com/v1"

常见路径：

Windows: %USERPROFILE%\\.codex\\config.toml
macOS / Linux: ~/.codex/config.toml

3.4 `auth.json` 配置¶

示例：

{
  "api_key": "sk-xxxx"
}

常见路径：

Windows: %USERPROFILE%\\.codex\\auth.json
macOS / Linux: ~/.codex/auth.json

3.5 常见问题¶

Q: 提示认证失败？

检查 auth.json 中密钥是否正确（以 sk- 开头）
确认密钥没有多余空格/换行
确认密钥未过期（后台令牌管理查看）

Q: 如何更换模型？

编辑 config.toml，修改 model 为平台支持模型名即可。

4. Cursor 配置 API Key 指南¶

前置条件：建议使用 Cursor Pro 及以上账户。

操作步骤：

打开 Settings -> Models
启用 OpenAI API Key
填入 OpenAI API Key（CodeBair Key）
启用 Override OpenAI Base URL
填入 https://api.codebair.com/v1
选择模型（如 deepseek-chat）

5. OpenCode 配置教程¶

前置条件：已安装 OpenCode。

5.1 关键配置项¶

在 OpenCode 客户端中，开启并填写以下项目：

启用 OpenAI API Key
填入 OpenAI API Key（CodeBair Key）
启用 Override OpenAI Base URL
填入 https://api.codebair.com/v1
选择模型：deepseek-chat

5.2 配置文件方式（可选）¶

若你习惯手动编辑配置文件，可在 OpenCode 用户配置中设置：

API Key：CodeBair Key
Base URL：https://api.codebair.com/v1
Model：deepseek-chat（或你平台开放的模型名）

5.3 验证¶

建议优先执行一次最小调用验证（见第 7 节），确认 Key 与 Base URL 生效。

6. OpenClaw 配置教程¶

配置原则与 OpenCode 一致：

API Key：CodeBair Key
Base URL：https://api.codebair.com/v1
Model：平台支持模型

若工具区分 OpenAI 与自定义 Provider，选择 OpenAI 兼容模式。

7. 通用连通性验证¶

curl https://api.codebair.com/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_CODEBAIR_API_KEY" \
  -d '{
    "model": "deepseek-chat",
    "messages": [{"role": "user", "content": "ping"}]
  }'

8. 通用排障¶

401：Key 错误或未传鉴权头
403：账号权限/额度不足
429：触发限流，稍后重试
5xx：上游波动，建议退避重试并记录 request id

9. 最佳实践¶

前端不要直连 API，统一走你自己的后端
为不同应用分配不同 API Key，便于审计与吊销
配置超时、重试、日志脱敏与配额告警