配置速查表

本页不做工具推荐，只做字段对照。 找到你正在用的工具，照表填即可；详细步骤点工具名进入对应教程。

全客户端字段对照

客户端	协议	配置入口	地址字段 → 填什么	密钥字段	模型字段	改完是否需重启
ChatBox	OpenAI 兼容	设置 → 模型提供方 → 添加	API 主机 → https://api.ziai.lol	API 密钥	模型列表（手动添加）	否，点「检查」即可
CherryStudio	OpenAI 兼容 / Anthropic	设置 → 模型服务 → + 添加	API 地址 → https://api.ziai.lol/v1	API 密钥	获取模型列表 → 点 + 加入	否，点「检测」即可
CC-Switch	两者皆可（可本地转换）	主界面右上 + → 添加供应商	Base URL / 上游格式 → https://api.ziai.lol/v1 或 https://api.ziai.lol	API Key	模型列表	Claude Code 免重启；Codex 需重启终端
Claude Code	Anthropic Messages	~/.claude/settings.json	ANTHROPIC_BASE_URL → https://api.ziai.lol	ANTHROPIC_AUTH_TOKEN	ANTHROPIC_MODEL	重启 CLI
Codex	OpenAI Responses	~/.codex/config.toml	[model_providers.ziai] base_url → https://api.ziai.lol/v1	~/.codex/auth.json 的 OPENAI_API_KEY	model	重启终端
ZCode	OpenAI 兼容 / Anthropic	模型选择器 → 管理模型 → 添加供应商	OpenAI 接口地址 / Anthropic 接口地址 → https://api.ziai.lol/v1 或 https://api.ziai.lol	API Key	添加模型（必须手填 ID）	新开会话生效
WorkBuddy	OpenAI 兼容	设置 → 模型 → 添加模型 → 自定义	URL → https://api.ziai.lol/v1	API Key	模型名（手动填写）	保存即生效

表中地址的含义

示例域名为 https://api.ziai.lol，请替换为你的实际站点域名。

• https://api.ziai.lol/v1 = 根地址 + /v1，用于 OpenAI 兼容与 Responses 协议
• https://api.ziai.lol = 根地址，用于 Anthropic Messages 协议
• https://api.ziai.lol = 根地址，用于会自动拼接版本路径的客户端（如 ChatBox 的默认 API 路径）

按协议反查

ZiAI 端点	协议	用它的客户端
https://api.ziai.lol/v1/chat/completions	OpenAI Chat Completions	ChatBox、WorkBuddy、ZCode（OpenAI 地址）、CherryStudio
https://api.ziai.lol/v1/responses	OpenAI Responses	Codex、ZCode（部分场景）、CherryStudio
https://api.ziai.lol/v1/messages	Anthropic Messages	Claude Code、ZCode（Anthropic 地址）、CherryStudio
https://api.ziai.lol/v1/embeddings	Embeddings	向量检索 / RAG 类应用
https://api.ziai.lol/v1/models	模型列表	核对可用模型 ID

完整说明见端点与协议。

通用准备（所有客户端都一样）

1. 拿到密钥 —— 控制台创建，形如 sk-xxxxxxxx，见获取 API 密钥
2. 确认模型 ID —— 打开操练场看下拉框，或请求 https://api.ziai.lol/v1/models
3. 先用 curl 打通基线 —— 命令行能通，再去配客户端；命令行不通就是密钥或额度问题，与客户端无关

curl https://api.ziai.lol/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -d '{"model":"模型ID","messages":[{"role":"user","content":"你好"}]}'

三条最容易踩的通用坑

填错地址的三种典型形态

1. /v1 重复 → 请求变成 /v1/v1/chat/completions → 404 （ChatBox 里主机带 /v1 且 API 路径又保留默认值时最常见）
2. /v1 缺失 → 请求变成 /chat/completions → 404 （Codex、WorkBuddy、ZCode 只填根域名时最常见）
3. 协议选错 → 给 Codex 填了 Chat 地址、给 Claude Code 填了 OpenAI 地址 → 404 或 400

判断方法：用上面的 curl 命令逐个端点试，能通的那个就是正确形态。

模型 ID 必须逐字复制

大小写、短横线、点号、日期后缀都要一致。gpt-5.2 与 GPT-5.2、claude-sonnet-4-5 与 claude-sonnet-4.5 是不同的 ID。 ZiAI 还支持模型重定向，所以以 ZiAI 控制台展示的 ID 为准，不要凭印象填官方名称。

同时用 Claude Code 和 Codex？

直接用 CC-Switch 管理这两个工具的供应商配置，可以避免手改 JSON / TOML 的绝大多数坑， 并在 ZiAI 缺少某个协议通道时用本地代理转换。

客户端教程

• 接入 ChatBox —— 跨平台聊天客户端，图形界面填 3 个字段
• 接入 CherryStudio —— 自定义 OpenAI 兼容服务商，支持多 Key 轮询
• 接入 Claude Code —— 终端编程 Agent，Anthropic 协议
• 接入 Codex —— 终端编程 Agent，Responses 协议
• 接入 ZCode —— Z.ai 桌面 Agent，自定义供应商
• 接入 WorkBuddy —— 腾讯桌面 Agent，自定义模型
• CC-Switch —— 供应商管理器，推荐用于 Claude Code + Codex

配好后遇到问题：常见报错速查 ｜ 协议不匹配详解