快速开始

Claude Code

Claude Code 走 Anthropic 原生协议，提示词缓存、扩展思考、工具调用都会完整保留。Base URL 用根地址（不带 /v1），Claude Code 会自己拼 /v1/messages。

1. 推荐写进用户级配置文件 ~/.claude/settings.json（Windows：%USERPROFILE%\.claude\settings.json），终端和 IDE 里启动的 Claude Code 都会读取。也可以用环境变量，见下方 bash / PowerShell 标签。
2. 密钥用 ANTHROPIC_AUTH_TOKEN（以 Authorization: Bearer 发送）。用 ANTHROPIC_API_KEY 也可以，但首次启动会弹窗让你确认是否使用该密钥，选「否」之后会被静默忽略。
3. 把 ANTHROPIC_DEFAULT_OPUS_MODEL / SONNET / HAIKU 设成模型页或 GET /v1/models 里存在的 claude-* 模型。Claude Code 默认会请求最新的官方模型名，本站没有对应模型时会报 404；HAIKU 用于后台小任务，可换成更便宜的模型。
4. 启动 claude 后输入 /status，看到「Anthropic base URL」一行显示本站地址、「Auth token」一行显示 ANTHROPIC_AUTH_TOKEN，就说明已经走 Thklumi。
5. VS Code 扩展：在 VS Code 的用户设置（settings.json）里加 claudeCode.environmentVariables，这是官方推荐的可靠位置。
6. 排查时可以先用最下面的 cURL 直接请求一次：返回 {"id":"msg_…"} 说明地址和密钥都对；返回 401 说明密钥或请求头不对。

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.thklumi.com",
    "ANTHROPIC_AUTH_TOKEN": "sk-你的密钥",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "claude-opus-4-8",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "claude-sonnet-4-6",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "claude-sonnet-4-6"
  }
}

"claudeCode.environmentVariables": [
  { "name": "ANTHROPIC_BASE_URL", "value": "https://api.thklumi.com" },
  { "name": "ANTHROPIC_AUTH_TOKEN", "value": "sk-你的密钥" },
  { "name": "ANTHROPIC_DEFAULT_SONNET_MODEL", "value": "claude-sonnet-4-6" }
]

curl -sS https://api.thklumi.com/v1/messages \
  -H "Authorization: Bearer sk-你的密钥" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model":"claude-sonnet-4-6","max_tokens":16,"messages":[{"role":"user","content":"ping"}]}'

• 不要把密钥写进项目里的 .claude/settings.json（会被提交到 Git），用用户级配置或 .claude/settings.local.json。
• 配置文件里的 env 会覆盖终端里 export 的同名变量。
• 要切回 Claude 官方账号：删掉上面这些变量，在 Claude Code 里执行 /logout，再 /login。
• Claude 桌面应用不读取这些环境变量和 settings.json，需在应用内 Help → Troubleshooting → Enable Developer Mode 后，到 Developer → Configure Third-Party Inference 里配置。
• 如果遇到 anthropic-beta 相关的「Unexpected value」报错，可加环境变量 CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1。

Codex（CLI / IDE 扩展 / ChatGPT 桌面版 Codex 模式）

Codex 只支持 OpenAI Responses 协议（wire_api = "chat" 已被官方移除），因此只能使用支持 Responses 的模型，目前主要是 GPT 系列。CLI、IDE 扩展和 ChatGPT 桌面版里的 Codex 模式共用同一个配置文件。

1. 编辑用户级配置 ~/.codex/config.toml（Windows：%USERPROFILE%\.codex\config.toml），加入下面的 model_provider 配置。注意 model_provider 写在项目里的 .codex/config.toml 不生效。
2. base_url 要带 /v1，Codex 会自己拼 /responses；model 填模型页里支持 Responses 的模型 id，例如 gpt-5.5。
3. 把密钥放进环境变量 THKLUMI_API_KEY（名字要和 env_key 一致），不要写进 config.toml。
4. 从桌面图标打开的 Codex / ChatGPT 应用读不到终端里 export 的变量，推荐写进 ~/.codex/.env，或用 PowerShell 设成用户级环境变量后完全重启应用。
5. 改完配置后重启 Codex（CLI 重开终端，IDE 扩展重启 VS Code，桌面应用完全退出再打开）。

# 顶层字段必须写在第一个 [表] 之前
model = "gpt-5.5"
model_provider = "thklumi"

[model_providers.thklumi]
name = "Thklumi"
base_url = "https://api.thklumi.com/v1"
wire_api = "responses"
env_key = "THKLUMI_API_KEY"

# 写进 ~/.zshrc 或 ~/.bashrc
export THKLUMI_API_KEY="sk-你的密钥"

codex

• ~/.codex/.env 里以 CODEX_ 开头的变量会被忽略，所以变量名不要用 CODEX_ 前缀。
• provider id 不能用 openai、ollama、lmstudio 这几个保留名；第三方网关不要设置 requires_openai_auth。
• Codex 0.134.0 起 --profile 读取的是 ~/.codex/<名字>.config.toml，旧教程里写在 config.toml 内的 [profiles.x] 已不生效。
• Codex 云端任务必须登录 ChatGPT 账号，无法走 Thklumi。

Gemini CLI

Gemini CLI 走 Gemini 原生协议。Base URL 用根地址，CLI 会自己拼 /v1beta/models/…。

1. 设置 GOOGLE_GEMINI_BASE_URL、GEMINI_API_KEY 两个环境变量。
2. 额外设置 GEMINI_API_KEY_AUTH_MECHANISM=bearer，让 CLI 用 Authorization: Bearer 发送密钥。
3. 启动时用 -m 指定模型页里存在的 Gemini 模型，例如 gemini -m gemini-3.5-flash。

export GOOGLE_GEMINI_BASE_URL="https://api.thklumi.com"
export GEMINI_API_KEY="sk-你的密钥"
export GEMINI_API_KEY_AUTH_MECHANISM="bearer"

gemini -m gemini-3.5-flash

• 不要用 Google 账号登录方式启动，那样请求会直接发到 Google，不经过 Thklumi。

Cherry Studio

Cherry Studio 支持多种提供商类型，同一把密钥可以按模型分别建 OpenAI、Anthropic、Gemini 三个提供商，各走原生协议。

1. 打开 设置 → 模型服务 → 添加，填写名称，并选择提供商类型： · OpenAI：DeepSeek、GLM、Kimi 等大多数模型 · OpenAI-Response：GPT 系列 · Anthropic：Claude 系列 · Gemini：Gemini 系列
2. API 地址统一填 https://api.thklumi.com，Cherry Studio 会自动补上版本路径（OpenAI / Anthropic 补 /v1，Gemini 补 /v1beta）。填之前确认输入框下方的「预览」地址是否正确。
3. API 密钥填 sk- 开头的 Key，然后点击「管理」或「添加」模型，模型 id 填模型页里的 id。
4. 点击「检查」测试连通性，成功后在对话页选这个提供商下的模型即可。

• 地址末尾加 # 表示原样使用、不自动补版本路径，一般不需要。
• 旧版（1.x）文档里「地址以 / 结尾就不补 /v1」的规则在 2.x 已不适用，以预览地址为准。

Cline（VS Code）

Cline 可以走 Anthropic 原生协议（推荐用于 Claude），也可以走 OpenAI 兼容协议（用于其它模型）。

1. 调用 Claude：API Provider 选「Anthropic」，勾选「Use custom base URL」，填 https://api.thklumi.com，API Key 填 sk- 密钥，再选择模型。
2. 调用其它模型：API Provider 选「OpenAI Compatible」，Base URL 填 https://api.thklumi.com/v1，API Key 填 sk- 密钥，Model ID 填模型页里的 id。
3. OpenAI Compatible 模式下可以在 Model Configuration 里补充上下文长度、是否支持图片等信息，Cline 会据此控制上下文。

• Roo Code 已于 2026 年 5 月停止维护，建议迁移到 Cline。

OpenCode

OpenCode 通过自定义 provider 接入，全局配置在 ~/.config/opencode/opencode.json，也可以放在项目根目录的 opencode.json。

1. 按下面的示例添加 provider，options.baseURL 填 https://api.thklumi.com/v1。
2. 密钥用 {env:THKLUMI_API_KEY} 从环境变量读取，不要直接写进配置文件。
3. models 里列出你要用的模型 id（以模型页为准）。

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "thklumi": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Thklumi",
      "options": {
        "baseURL": "https://api.thklumi.com/v1",
        "apiKey": "{env:THKLUMI_API_KEY}"
      },
      "models": {
        "deepseek-v4-flash": { "name": "DeepSeek V4 Flash" },
        "gpt-5.5": { "name": "GPT-5.5" }
      }
    }
  }
}

• GPT 系列如需走 Responses 协议，可把 npm 换成 @ai-sdk/openai。

Cursor

Cursor 对自定义接口的支持有限，只适合在聊天里使用。

Cursor 的自定义密钥只对聊天模型生效，Tab 补全和后台 Agent 仍使用 Cursor 自己的模型；所有请求会先经过 Cursor 的服务器。Agent 模式使用自定义地址时可能发送 Responses 格式请求，部分模型会失败。

1. 打开 Settings → Models，在 OpenAI API Key 处填 sk- 密钥；如果你的版本有「Override OpenAI Base URL」，填 https://api.thklumi.com/v1。
2. 点击「Add model」添加模型页里的模型 id，然后在聊天（Ask 模式）里选择它。

• 部分新版本和套餐已不显示「Override OpenAI Base URL」，这种情况下无法接入。

ChatGPT 网页版 / 桌面版

ChatGPT 的聊天功能（chatgpt.com 和桌面应用的普通对话）不支持自定义 API 地址或第三方密钥，无法接入 Thklumi。

1. ChatGPT 桌面应用里的 Codex 模式会读取 ~/.codex/config.toml，可以按上面「Codex」一节配置后使用。
2. 想要类似 ChatGPT 的聊天界面，可以用本站的「调试台」，或用 Cherry Studio 这类客户端接入。