客户端接入总览

qimoq 对外提供 OpenAI 兼容接口，同时也兼容部分 Claude、Gemini 和 Codex 类客户端的接入习惯。配置前先确认三件事：API Key、Endpoint、模型 ID。

选择客户端

客户端	推荐方式	Endpoint 填写
Codex CLI / 桌面端 / IDE 扩展	CC Switch 导入	站点根地址
Claude Code	CC Switch 导入	站点根地址
VS Code	复用 Codex 或 Claude Code 配置	由本机 CLI 配置决定
Gemini CLI	CC Switch 导入或手动配置	站点根地址 + `/v1beta`
OpenCode / OpenClaw / Hermes	OpenAI Compatible Provider	`/v1`
Cursor / Cherry Studio	自定义 OpenAI Provider	`/v1`

控制台里展示的 Base URL、凭证分组和模型名称优先级最高；文档里的示例用于说明字段位置。

Base URL 怎么填

不同客户端对 Base URL 的要求不完全相同：

场景	示例	说明
OpenAI Compatible	`/v1`	用于 OpenAI SDK、OpenCode、Cherry Studio、Cursor 等
Codex / Claude Code	`https://你的 qimoq 站点域名`	这类客户端通常由导入工具写入根 Endpoint
Gemini CLI	`https://你的 qimoq 站点域名/v1beta`	Gemini 兼容接口使用 v1beta 路径
Chat Completions 请求	`/v1/chat/completions`	curl 或 OpenAI SDK 的实际请求路径

如果客户端已经自动拼接 /v1，Base URL 不要重复写成 /v1/v1。如果客户端要求完整接口路径，再按它的提示补齐。

访问凭证、分组和模型

访问凭证不只是调用身份，也会影响可用模型和调用限制。创建或选择凭证时建议按用途拆分：

用途	建议
Codex / OpenAI 兼容客户端	使用能调用 GPT / Codex 模型的凭证
Claude Code	使用能调用 Claude 模型的凭证
Gemini CLI	使用能调用 Gemini 模型的凭证
自动化脚本	单独创建凭证，并设置额度或速率限制

模型 ID 必须从「模型广场」复制，例如 gpt-5.5、claude-sonnet-4-5、gemini-2.5-pro。不要填写供应商展示名，也不要把分组名当作模型名。

CC Switch 与手动配置

支持 CC Switch 的客户端优先使用一键导入，可以减少凭证、Endpoint 和模型名填错的概率。

安装并打开 CC Switch。
进入 qimoq「访问凭证」页面。
找到用途匹配的凭证，点击导入配置。
选择目标客户端，并确认主模型、快速模型或备用模型。
浏览器询问是否打开 CC Switch 时选择允许。
保存后重启终端、CLI 或 IDE 插件。

不要分享 ccswitch:// 导入链接；链接里可能包含完整 API Key。

VS Code 接入方式

VS Code 自身通常不是直接填 API Endpoint 的地方。推荐先在本机把 Codex CLI 或 Claude Code 配好，再安装对应 VS Code 扩展复用同一份配置。

目标	做法
使用 Codex IDE 扩展	先完成 Codex 接入，再登录或打开扩展
使用 Claude Code VS Code 扩展	先完成 Claude Code 接入，再从 VS Code 中调用
两者都装	分别用不同凭证，避免错误模型被错误客户端调用

验证与排查

最简单的验证方式是先用 curl 请求一次 Chat Completions：

curl --location --request POST '/v1/chat/completions' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "model": "gpt-5.5",
    "messages": [
      { "role": "user", "content": "请用一句话确认接入成功" }
    ]
  }'

常见问题通常来自四处：凭证分组不匹配、模型 ID 写错、Base URL 多写或少写路径、余额或凭证限制不足。失败后先看「使用日志」，再按状态码定位。

下一步

目标	文档
配置 Codex	Codex 接入
配置 Claude Code	Claude Code 接入
配置 VS Code	VS Code 接入
配置 Gemini CLI	Gemini CLI 接入
配置 OpenCode	OpenCode 接入
其它客户端	更多客户端
手动复制配置	手动配置模板