常见问题

账号与密钥

一个密钥能同时用于所有客户端吗？

能。 ZiAI 的密钥与客户端无关，同一个密钥可以填进 ChatBox、CherryStudio、Claude Code、Codex、ZCode、WorkBuddy。

但不建议共用一个密钥：

• 无法按工具统计花费（日志里只能看到密钥维度）
• 泄露时要全部重配
• 无法给某个工具单独设配额上限

推荐做法：按用途建多个密钥（claude-code、codex、chatbox-日常、test）， 给不信任的用途设「剩余配额」上限与 IP 白名单。见获取 API 密钥。

配置了 ZiAI 之后，还会消耗我的官方订阅吗？

不会。

• Claude Code：设置 ANTHROPIC_BASE_URL 后，所有模型（包括官方预设模型名）都走 ZiAI，不再使用 Claude Pro / Max 订阅额度
• Codex：model_provider 指向自定义 provider 后，请求发往 ZiAI 而非 OpenAI

这也是为什么建议用 CC-Switch 管理 —— 可以在 ZiAI 与官方登录之间一键切换。

怎么切回官方账号？

Claude Code

取消设置相关环境变量，或从 ~/.claude/settings.json 的 env 块中删除这几项：

unset ANTHROPIC_BASE_URL ANTHROPIC_AUTH_TOKEN ANTHROPIC_MODEL

然后重启 Claude Code，按提示重新登录（/login）。

用一键脚本配置过的话，还要清掉写进 shell 配置的行：

grep -n ANTHROPIC ~/.bashrc ~/.zshrc
# 手动删除对应行后 source 生效

Codex

把 ~/.codex/config.toml 里的 model_provider 改回 openai（或删掉该行，默认就是 openai）， 然后 codex login 重新走官方登录流程。

自定义 provider 定义可以保留不删 —— 只要没有 wire_api = "chat"，留着不影响启动。

CC-Switch

添加一个「官方登录」预设供应商，切换过去后执行一遍 Log out / Log in 流程即可。 之后就能在官方与 ZiAI 之间随意切换。Codex 还支持在多个官方账号之间切换（便于多个 Plus / Team 账号）。

图形客户端

ChatBox / CherryStudio / ZCode / WorkBuddy 都支持同时保留多个服务商， 在模型选择器里换回原来的服务商即可，无需删除 ZiAI 配置。

CherryStudio 注意：换回后确认目标服务商的启用开关是打开的。

密钥泄露了怎么办？

1. 立刻在控制台禁用或删除该密钥
2. 新建一个密钥，更新到各客户端
3. 查日志页，确认是否有异常调用与额度损失
4. 检查密钥是否被提交进了 Git 仓库（含私有仓库）；若已提交，仅删除文件不够，需清理历史记录
5. 给新密钥设置 IP 白名单与配额上限，降低再次泄露的影响面

本站永远不会向你索取密钥

文档、工单、客服都不需要你的完整密钥。排查问题时提供前 6 位 + 后 4 位即可（如 sk-abc...wxyz）。

额度用完了是什么表现？

不同客户端提示差异很大，容易误判为配置错误：

你看到的	实际原因
insufficient_quota / 额度不足 / 余额不足	账户或密钥配额已用尽
401 / 403（此前一直正常）	密钥过期、被禁用，或配额耗尽后被停用
操练场能用、客户端不能用	客户端填的模型 ID 不在该密钥的模型限制内
某模型突然 404	站长下线了该渠道，或改了模型映射

判断方法：先开操练场发一句话。 操练场能通就说明账号、额度、密钥都没问题，故障在客户端配置。

客户端支持

支持哪些客户端？

本站提供 7 个工具的完整教程：

工具	协议	教程
CC-Switch	两者皆可	CC-Switch
Claude Code	Anthropic Messages	接入 Claude Code
Codex	OpenAI Responses	接入 Codex
ChatBox	OpenAI 兼容	接入 ChatBox
CherryStudio	OpenAI 兼容	接入 CherryStudio
ZCode	OpenAI / Anthropic	接入 ZCode
WorkBuddy	OpenAI 兼容	接入 WorkBuddy

其他工具能不能接？ 只要它支持「自定义 OpenAI 兼容端点」或「自定义 Anthropic 端点」，原则上都能接：

• 走 OpenAI 兼容 → 填 https://api.ziai.lol/v1
• 走 Anthropic → 填 https://api.ziai.lol（不带 /v1）
• 走 Responses → 填 https://api.ziai.lol/v1，端点为 /v1/responses

Cursor、Cline、Continue、OpenCode、Gemini CLI、Dify、各类 SDK 都属于这一类。

能用代码 / SDK 直接调用吗？

可以，ZiAI 是标准 OpenAI / Anthropic 兼容接口。

Python (OpenAI SDK)

from openai import OpenAI

client = OpenAI(
    api_key="sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    base_url="https://api.ziai-demo.com/v1",
)

resp = client.chat.completions.create(
    model="模型ID",
    messages=[{"role": "user", "content": "你好"}],
)
print(resp.choices[0].message.content)

Python (Anthropic SDK)

from anthropic import Anthropic

client = Anthropic(
    api_key="sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    base_url="https://api.ziai-demo.com",   # 不带 /v1
)

msg = client.messages.create(
    model="模型ID",
    max_tokens=1024,
    messages=[{"role": "user", "content": "你好"}],
)
print(msg.content[0].text)

Node.js

import OpenAI from 'openai';

const client = new OpenAI({
  apiKey: process.env.ZIAI_API_KEY,
  baseURL: 'https://api.ziai-demo.com/v1',
});

const resp = await client.chat.completions.create({
  model: '模型ID',
  messages: [{ role: 'user', content: '你好' }],
});
console.log(resp.choices[0].message.content);

环境变量约定

export ZIAI_API_KEY="sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
export ZIAI_BASE_URL="https://api.ziai-demo.com/v1"
export ZAI_API_KEY="$ZIAI_API_KEY"        # 部分 SDK 读取的变量名
export OPENAI_BASE_URL="$ZIAI_BASE_URL"   # OpenAI SDK 默认识别
export ANTHROPIC_BASE_URL="https://api.ziai-demo.com"
export ANTHROPIC_AUTH_TOKEN="$ZIAI_API_KEY"

多数 SDK 支持从环境变量读取 base_url 与密钥，这样代码里不出现明文。

LangChain 等框架的 base_url 陷阱

部分框架要求 base_url 必须包含 /v1，只给域名会报 404。 按框架文档确认它期望的层级，或用 curl 先验证端点。

团队与多人使用

可以多人共用一个密钥吗？

技术上可以，但不建议：

• 无法区分谁在花额度，出问题难追责
• 任何人泄露都会影响所有人
• 无法针对个人设配额与 IP 白名单

推荐：每人一个密钥，用「剩余配额」做预算隔离，用日志页按密钥对账。

团队统一配置怎么做？

• Claude Code：把配置写进项目仓库的 .claude/settings.json（可提交版本库）， 但密钥不要写进去 —— 用 env_key 式的环境变量或 apiKeyHelper
• Codex：provider 必须写在用户级 ~/.codex/config.toml，项目级会被忽略； 可以用 $CODEX_HOME/团队名.config.toml + --profile 统一下发
• CC-Switch：用「导出配置」生成 .sql 备份分发给团队成员导入； 或由站长生成 ccswitch:// Deep Link，成员点一下即完成配置
• 通用：把本页的域名与模型 ID 固化到团队内部文档，避免口口相传出错

数据安全与合规

ZiAI 会记录我的对话内容吗？

ZiAI 作为网关会记录调用元数据（时间、模型、Token 数、费用、密钥）用于计费与排障，这是网关的基本功能。 对话正文是否留存、留存多久，取决于站长的部署配置与上游服务商的策略。

不同客户端的边界也不同，例如 WorkBuddy 官方明确：配置（含 API Key）仅保存在本地 workbuddy/models.json， 它只作为通信链路把输入转发给你配置的模型，输出由该模型直接返回。

敏感数据的建议

• 不要把密钥、生产数据库凭据、客户隐私数据直接贴进对话
• 涉及合规要求的场景，先向站长确认数据留存策略与上游渠道
• 需要数据不出本机时，改用本地模型（Ollama 等），WorkBuddy 与 ZCode 都支持本地部署接入

使用 ZiAI 合规吗？

ZiAI 属于第三方 API 网关。请你自行确认：

1. 你对所使用的上游模型拥有合法使用授权
2. 使用方式符合上游服务条款与平台规则
3. 符合你所在地区的法律法规与所在组织的内部规定

本站只提供技术接入说明，不构成对任何使用行为的授权或背书。

关于本文档

ZiAI 的地址是什么？

API 与控制台同域：https://api.ziai.lol。

用途	应该填 / 访问
OpenAI 兼容、Responses（Codex）	https://api.ziai.lol/v1
Anthropic Messages（Claude Code）	https://api.ziai.lol —— 不带 /v1
控制台密钥页	https://api.ziai.lol/console/token
操练场	https://api.ziai.lol/console/playground
用量日志	https://api.ziai.lol/console/log

本站所有示例命令均已使用该域名，可直接复制。完整对照见端点与协议。

文档里的截图为什么有的是虚线框？

标着「待补插图」的虚线框是占位组件（src/components/ImgPlaceholder.astro），说明这里需要一张截图、以及建议的画面内容与尺寸。 站点维护者可以用下面的命令统计还差哪些图：

# 源码中统计占位组件（当前 7 处）
grep -rn "<ImgPlaceholder" src/content/docs

# 构建产物中统计渲染出的标记（带稳定 id）
npm run build
grep -rho 'IMG-TODO: [^"]*' dist --include=*.html | sort -u

客户端版本有要求吗？

工具	版本注意
CC-Switch	≥ v3.20.1（修复 Codex ≥ 0.149 切换后 401）；实测最新 v3.20.3
Codex CLI	新版仅支持 wire_api = "responses"；旧配置里的 chat 会导致所有命令启动失败
Claude Code	网关兼容开关（如 CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY）需要较新版本
CherryStudio	自定义服务商的 # 结尾完整地址写法需要较新版本
ZCode	自定义供应商配置文件为 ~/.zcode/v2/config.json
ChatBox / WorkBuddy	无特殊要求

各页面顶部会标注实测版本。版本更新较快，行为以你实际安装的版本为准。

文档有误或需要补充？

请通过 ZiAI 官方渠道反馈。反馈时附上：客户端与版本、模型 ID、完整报错文案、HTTP 状态码与 x-request-id、发生时间。 不要附完整密钥。

相关页面

• ZiAI 是什么
• 端点与协议
• 配置速查表
• 常见报错速查
• 模型清单与能力