ZCode 是 Z.ai（智谱）官方的 AI 编码开发工具，支持添加「自定义供应商」接入本网关：
1. 打开 ZCode，点击对话框中的模型名称打开 模型选择器，在列表底部点 管理模型，进入 设置 → 模型设置。
2. 在左侧供应商列表底部点 添加供应商；若表单有「API 格式 / 协议类型」字段，选 Chat（OpenAI Chat Completions 格式）（ZCode 默认 Anthropic 协议，需切到 Chat；新版自动识别可跳过）。
3. API 基础 URL 填 https://ai.shimiaocheng.top/v1（带 /v1）。
4. API Key 填页面顶部「你的 Key」框里的 sk-... 值。
5. 模型名称 填 GLM-5.3。
6. 打开该供应商的启用开关并保存。
7. 回到对话框，选中 GLM-5.3 发一句话测试连通性。
ZCode 供应商协议仅有 Chat 与 Anthropic 两种且默认后者：本网关选 Chat，Base URL 带 /v1。Anthropic 格式需额外配置 Header，链路较长。

✅ 原生支持：本网关已原生兼容 Anthropic Messages API（/v1/messages），Claude Code 可直接接入，无需中转代理。

Base URL 不带 /v1：Claude Code 会自动拼接 /v1/messages，多填会导致路径重复 404。填 https://ai.shimiaocheng.top 即可（见下方配置）。

将以下 settings.json 配置复制即用（sk-你的子Key 换成页面顶部「你的 Key」里的值）：
模型名统一填 GLM-5.3（智谱卡实际调用的就是智谱 GLM-5.3；DeepSeek 卡请填上方高亮的当前池模型）。个别老版本 Claude Code 若模型列表为空，可把这三个变量分别填 claude-sonnet-4-20250514 / claude-opus-4-20250514 / claude-haiku-4-20250514。

{
  "ANTHROPIC_BASE_URL": "https://ai.shimiaocheng.top",
  "ANTHROPIC_API_KEY": "sk-你的子Key",
  "ANTHROPIC_CUSTOM_HEADERS": "x-api-key: sk-你的子Key",
  "ANTHROPIC_DEFAULT_SONNET_MODEL": "GLM-5.3",
  "ANTHROPIC_DEFAULT_OPUS_MODEL": "GLM-5.3",
  "ANTHROPIC_DEFAULT_HAIKU_MODEL": "GLM-5.3"
}

配置后完全退出并重启 Claude Code。模型列表里会出现 GLM-5.3，直接用 /model 选中它即可对话。智谱卡无论填 GLM-5.3 还是兼容写法的 claude-* 名，网关都会统一用智谱 GLM-5.3 为你服务（DeepSeek 卡必须填当前池模型名，claude-* 兼容名不适用）。

CC Switch 是 Claude Code 的图形化管理器（GUI）。请用「OpenAI Chat Completions」格式接入（链路短、配置少、最稳），不要用 Anthropic Messages 格式——后者需额外填自定义 Header 且对客户端版本要求高，容易卡：
1. 点 + 添加供应商 新建时，API 格式选择 OpenAI Chat Completions（需开启路由）。
2. Base URL（请求地址）填 https://ai.shimiaocheng.top/v1（必须带 /v1）。
3. 认证字段（API Key / 令牌）填页面顶部「你的 Key」框里的 sk-... 值（无需自定义 Header）。
4. 模型填 GLM-5.3，保存后切换到该供应商即可对话。
CC Switch 走 OpenAI 格式时 Base URL 需带 /v1（与 Claude Code CLI 相反）。修改后建议重启客户端生效。

🧩 同时接入 Codex（Codex CLI 走 Responses API，填法与 Claude 不同）
1. 顶部切到 Codex 标签页（不是 Claude 标签），点 + 添加供应商，格式选「自定义配置 / Custom」——不要选 DeepSeek / Kimi 这类内置预设，选了它会要求「路由转换」（见下方警告）。
2. Base URL 填 https://ai.shimiaocheng.top/v1；API Key 填页面顶部「你的 Key」里的 sk-...；模型填 GLM-5.3。
3. 保存后检查生成的 ~/.codex/config.toml，必须含 wire_api = "responses"（Codex 只认 Responses API，本网关已原生支持）。若被写成了 Chat 格式，点该供应商的「编辑配置」手动补这一行。
4. 保存 → 在供应商列表点「启用」→ 完全退出并重启 Codex。
⚠️ 下面三种提示都不是你的 Key 有问题：
· 「需要路由」→ 弹 502 error：该供应商是按 Chat 格式配的，CC Switch 要走本地代理（默认 127.0.0.1:15721）转换协议，代理没起来或地址填错就 502。改「自定义配置」+ wire_api = "responses" 直连即可绕过。
· 「查询失败」：CC Switch 去查 OpenAI 的旧余额接口（/dashboard/billing/subscription），本网关没有这个接口，不影响对话；想看剩余额度用下面的「用量查询」脚本。
· 「OpenAI Official 不支持路由」：那是 CC Switch 自带的官方条目，与本站无关，忽略即可。

📊 在 CC Switch 卡片上直接显示剩余额度（用量查询）
CC Switch 支持自定义「用量查询」脚本，配置后卡片底部会常驻显示你的剩余额度，无需打开本面板：
1. 悬停本网关的供应商卡片，点 「用量查询」按钮（📊 图标）。
2. 打开顶部 「启用用量查询」 开关，模板选 「自定义」。
3. 把下面整段脚本复制进去（Base URL / API Key 参数留空即可，脚本会用供应商本身配置的凭据；若要填，Base URL 填 https://ai.shimiaocheng.top/v1）：
💡 脚本里的 {{apiKey}} 是 CC Switch 官方占位符，运行时自动替换成你配置的 Key——脚本一个字都不用改。若测试失败，检查用量查询配置面板的「API Key」框是否留空（留空则复用供应商本身的 Key，推荐）或填了正确的 Key。
4. 点 「测试脚本」，卡片应显示「套餐余额 剩余 xxx tokens」。
5. 「自动查询间隔」建议 30–60 分钟（填 0 关闭自动刷新）；保存后供应商处于「当前启用」状态才会后台自动刷新。
💡 点数卡用户：把脚本里的 URL 换成 https://ai.shimiaocheng.top/dc/v1/quota，extractor 改为 return { planName: "点数余额", remaining: response.points_balance_cny, unit: "¥" };，其余步骤相同（Key 用点数 Key）。

Trae 支持 OpenAI 兼容的自定义模型Provider。
1. 打开聊天面板右上角 Settings（设置） → Models（模型）。
2. 点 ＋ 添加模型，选「自定义模型」，API 格式选 OpenAI Chat Completions。
3. 自定义请求地址 填 https://ai.shimiaocheng.top/v1。
4. API 密钥 填页面顶部「你的 Key」框里的 sk-... 值。
5. 模型 ID 填 GLM-5.3，保存后即可选用。 「完整 URL / Full URL」开关保持关闭（默认即为关闭）：开启后 Trae 不再自动拼接 /chat/completions，对话将全部 404。

✅ 原生支持：本网关已实现 OpenAI Responses API 翻译层（/v1/responses），OpenAI Codex CLI 可直接接入，无需中转代理。Codex（2026）只走 Responses API，普通「OpenAI 兼容」填法（仅填 /v1）对它无效。

1. 安装 Codex CLI（需 Node 22+）：
npm install -g @openai/codex
2. 编辑配置文件 ~/.codex/config.toml（不存在则新建），填入以下内容（sk-你的子Key 换成页面顶部「你的 Key」里的值）：

model = "GLM-5.3"
model_provider = "shimiaocheng"

[model_providers.shimiaocheng]
name = "我的网关"
base_url = "https://ai.shimiaocheng.top/v1"
env_key = "GW_API_KEY"
wire_api = "responses"
requires_openai_auth = false

3. 在终端把 Key 注入环境变量（sk-你的子Key 同上）：
export GW_API_KEY="sk-你的子Key"
4. 运行 codex 即可开始对话。Codex 会自动向 /v1/responses 发起请求，网关将其翻译为上游模型并返回。
说明：model_provider 的 id 不能用 openai / ollama 等保留字；智谱卡 model 填 GLM-5.3 即可（填其他名称也会被统一映射为智谱默认模型）；DeepSeek 卡必须填 GLM-5.3（当前池模型，填其他名称会被拒绝，请从上方「支持的模型」复制）。

用 CC Switch 图形化管理配置？可以，但 Codex 在 CC Switch 里的填法与 Claude 不同（要选「自定义配置」并确保 wire_api = "responses"，否则会因「需要路由」弹 502）。 查看 CC Switch 教程的 Codex 部分 →

Cursor 是 OpenAI 兼容客户端，可直接自定义 Base URL。
1. 打开 Settings（设置） → Models（模型）。
2. 勾选 Override OpenAI Base URL，填入 https://ai.shimiaocheng.top/v1。
3. API Key 填页面顶部「你的 Key」框里的 sk-... 值。
4. Model 填 GLM-5.3。
5. 点击 Verify 验证通过后即可对话。

ChatBox 是支持 OpenAI 兼容协议的通用聊天客户端（Windows / macOS / 手机端均可）。
1. 打开 ChatBox，点击侧边栏 设置（齿轮图标）→ 模型提供方（Model Provider）→ 点底部 添加。（首次启动欢迎页可直接选「使用自己的 API Key 或本地模型」进入）
2. API 模式 选 OpenAI API 兼容（OpenAI API Compatible）。
3. API 域名 填 https://ai.shimiaocheng.top/v1（末尾 /v1 不可省略）。
4. API 密钥 填页面顶部「你的 Key」框里的 sk-... 值。
5. 模型 填 GLM-5.3；若下拉列表没有该模型，手动添加模型名即可。
6. 点击 保存，点「Check 检查」确认连接成功；新建对话发一句「你好」测试，能正常回复即配置成功。

OpenCode 是开源 AI 编码 agent，通过配置文件接入 OpenAI 兼容 Provider。
1. 编辑配置文件 ~/.config/opencode/opencode.json（不存在则新建）。
2. 在 providers 中新增一个 openai-compatible 类型的 Provider：
baseUrl 填 https://ai.shimiaocheng.top/v1；
apiKey 填页面顶部「你的 Key」框里的 sk-... 值；
在 models 里添加一项名称为 GLM-5.3。
3. 重启 OpenCode，选择该 Provider 与 GLM-5.3 模型即可。

WorkBuddy 支持添加「自定义模型服务」，以 OpenAI 兼容格式接入本网关：
1. 打开 WorkBuddy → 设置 → 模型服务（模型 Provider）。
2. 点击 添加自定义 Provider，类型选择 OpenAI Compatible。
3. API Base URL 填 https://ai.shimiaocheng.top/v1（带 /v1）。
4. API Key 填页面顶部「你的 Key」框里的 sk-... 值。
5. 模型 填 GLM-5.3，保存后选用该模型对话即可。
若客户端要求逐模型添加，条目名称须与上方「支持的模型」一致。

CodeBuddy 通过 models.json 自定义模型，仅支持 OpenAI 接口格式：
1. 打开配置文件：用户级 ~/.codebuddy/models.json（国内版为 ~/.codebuddycn/models.json），不存在则新建；也可在 VS Code 命令面板执行 CodeBuddy: Open Model Configuration 直接打开。
2. 在 models 数组里新增一项（sk-你的子Key 换成页面顶部「你的 Key」里的值）：

{
  "models": [
    {
      "id": "GLM-5.3",
      "name": "GLM-5.3",
      "vendor": "OpenAI",
      "apiKey": "sk-你的子Key",
      "url": "https://ai.shimiaocheng.top/v1/chat/completions",
      "supportsToolCall": true
    }
  ]
}

3. 保存后配置会自动热重载（约 1 秒），在模型下拉里选中 GLM-5.3 即可对话。
url 需为完整接口路径（以 /chat/completions 结尾），CodeBuddy 不自动拼接。模型 id / name 可自定义，建议与「支持的模型」一致；如需限制下拉列表，可加 "availableModels": ["GLM-5.3"]。

Pi 是开源终端 AI 编码 agent（pi-mono），通过 models.json 注册自定义供应商接入本网关（OpenAI 兼容）：
1. 安装（需 Node 20+）：npm install -g @mariozechner/pi-coding-agent，运行 pi --version 验证。
2. 编辑配置文件 ~/.pi/agent/models.json（不存在则新建），填入以下内容（sk-你的子Key 换成页面顶部「你的 Key」里的值）：

{
  "providers": {
    "molitoken": {
      "baseUrl": "https://ai.shimiaocheng.top/v1",
      "api": "openai-completions",
      "apiKey": "sk-你的子Key",
      "models": [
        {
          "id": "GLM-5.3",
          "name": "GLM-5.3",
          "reasoning": false,
          "input": ["text"],
          "cost": { "input": 0, "output": 0, "cacheRead": 0, "cacheWrite": 0 },
          "contextWindow": 1000000,
          "maxTokens": 128000
        }
      ]
    }
  }
}

3. 进入项目目录运行 pi，输入 /model 打开模型选择器，选 molitoken → GLM-5.3 即可开始对话。
baseUrl 带 /v1（OpenAI 兼容端点）；api 选 openai-completions；apiKey 支持 "$ENV_VAR" 环境变量引用。配置文件在打开 /model 时热重载。

✅ 原生支持：DeepSeek Harness（命令行 dsh，本地 Web UI 图形化配置，无需改文件）支持添加「自定义模型 API」，以 OpenAI 兼容格式接入本网关。
1. 安装（需 Node 18+）：npx @deepseek-ai/dsh web，浏览器打开 http://127.0.0.1:3080。
2. 点开左下角头像菜单 → 设置：
🔍 点击看大图 ① 左下角头像菜单 → 设置（图中红色箭头为点击位置）。 3. 左侧选 模型，点 ＋ 添加模型提供商：
🔍 点击看大图 ② 左侧 模型 → ＋ 添加模型提供商。 4. 把卡片切到 自定义模型 API 页，按下图逐项填写：
🔍 点击看大图 ③ 切到 自定义模型 API 页：Provider ID 填小写名（如 molitoken，保存后不可更改）· 显示名称 随意 · API 地址 填 https://ai.shimiaocheng.top/v1（必须带 /v1）· API 协议 选 OpenAI Chat Completions · API 密钥 填页面顶部「你的 Key」框里的值。 🔍 点击看大图 ④ 同一页下半部：模型目录 点 获取可用模型 自动拉取清单（拉不到就手填模型 ID，效果一样）；输入类型 勾上 文本 与 图片（本网关支持识图）；确认后点 创建提供商。 模型名按你当前这张卡可用的模型填（截图中为 deepseek 卡示例，仅作演示）：GLM-5.3。 5. 保存后点 Choose workspace 选一个项目目录（不选工作区，输入框是灰的、无法对话），再在模型选择器里选中刚配的模型即可开始。
每个 Provider 仅支持一种协议，本网关选 OpenAI Chat Completions；如需 Anthropic 协议另建 Provider（Base URL 不带 /v1）。Harness 为开发者预览版（0.2.0-rc），界面字段可能随版本调整。

✅ 已上线：GLM-5.3-FLASH 是智谱新一代原生多模态模型（支持图片/视频/文件输入），上下文 1M。计量计费与 GLM-5.3 完全一致（按时段倍率、按 token 统一计），智谱侧更省配额——同样额度用得更久。

怎么用：任一 OpenAI 兼容客户端里，把模型名从 GLM-5.3 改成 GLM-5.3-FLASH 即可，Base URL 和 Key 都不变（模型名见配置教程第 3 步「支持的模型」）。
快速验证（curl）：

curl https://ai.shimiaocheng.top/v1/chat/completions \
  -H "Authorization: Bearer sk-你的子Key" \
  -H "Content-Type: application/json" \
  -d '{"model":"GLM-5.3-FLASH","messages":[{"role":"user","content":"你好"}]}'

✅ 适用范围：Claude Code 与 Codex 也可用 flash——在这两类客户端的配置里把模型名填成 GLM-5.3-FLASH 即可（不填或填 claude-* / gpt-* 等其他名字仍走 GLM-5.3）。Cursor / ChatBox / Trae / OpenCode 等所有手动填模型的客户端同样支持。

💡 视觉 Coding 玩法：flash 原生多模态，可以把页面截图发给它让它复刻界面，或丢文档进去问问题——写代码 + 看图两不误。

状态列即 HTTP 状态码，共 7 种。按出现频率从高到低：

✓ 200 成功：调用正常完成，Token 正常计量，无需任何处理。

✕ 429 请求被拒：最常见的一类，细分 5 种语义，见下一个问题。

✕ 400 请求无效：请求体 JSON 格式错误，或模型名不在白名单内。检查请求体语法；模型名填 GLM-5.3。

✕ 502 网关超时：上游服务响应超时，多见于超长上下文的请求。稍后重试或减小单次请求规模。

✕ 500 / 503 上游异常：上游服务商内部错误或临时维护/过载。属于偶发，稍后重试即可。

✕ 401 认证失败：Key 填写错误或已失效。核对客户端中填写的 Key 与本页「我的Key」是否一致。

429 有 5 种细分场景，客户端收到的报错文案可以直接区分：

1. 本周 Token 已超限（最常见）：周额度已用尽。等概览页显示的周重置时间自动恢复，或用「续费/升级」tab 绑定新码续费。

2. 并发数超限（concurrency_limit_exceeded）：同时在途的请求数超过账户并发上限。降低客户端并发（如关掉并行子任务）后自动恢复。ℹ️ 并发拒绝不扣 Token，只记一条审计行，不用担心额度损失。

3. 5 小时内 Token 已超限：5 小时滚动窗口额度用尽。窗口从你首次消耗时刻起每 5 小时滚动回补，到概览页显示的重置时间自动恢复；也可续费提高额度。

4. 上游限流（Upstream returned 429）：上游服务商临时限流，与你账户额度无关。稍等片刻自动恢复，无需处理。

5. Token 额度已用尽：总量用尽。用「续费/升级」tab 续费——有效期内续费总额度累加，账户到期后续费按新码额度从头起算。

高峰期（周一至周五 14:00–18:00（UTC+8））所有调用按 3× 倍率计量，其余时间 1×。也就是说高峰期一次消耗 10,000 token 的请求，会实际扣减 30,000 的额度。「调用记录」的倍率列会标注每笔的倍率，>1× 的会橙色高亮。
💡 想省额度：把大批量任务挪到高峰时段之外跑，消耗直接降为 1/3。

三个维度各自独立重置，具体时间点见「配额概览」每个卡片右侧的重置时间：
· 5 小时窗口：每用户滚动窗口——从你首次消耗的时刻起每 5 小时滚动回补（与上游智谱的动态刷新机制一致），各用户的重置时刻因而不尽相同；
· 周额度：按周对齐重置；
· 总额度：不按周期重置——有效期内持续累计，账户到期时随账户一起清零，续费后按新码额度起算。
兑换码续费会把有效期从续费日重算、总/周额度累加（到期后按新码重起），Key 保持不变。

1. 核对客户端里填的 Key 与本页「我的Key」完全一致（注意前后空格）；
2. 账户到期后 Key 会被禁用——在「续费/升级」tab 绑定新码即可恢复，Key 不变；
3. 若确认 Key 无误仍 401，带上状态码与时间联系我们。

绝大多数是 Base URL 填法问题，不同客户端规则不同（详见「客户端配置」tab）：
· OpenAI 兼容客户端（Cursor / ChatBox / Trae / CC Switch / Codex 等）：https://ai.shimiaocheng.top/v1（带 /v1）；
· Claude Code CLI（Anthropic 格式）：https://ai.shimiaocheng.top（不带 /v1）；
· Trae 专属：「完整 URL / Full URL」开关保持关闭，开启后将不再自动拼接 /chat/completions，对话全部 404。

套餐（智谱卡）到期后：配额概览的「智谱套餐有效期」行会变红、智谱卡 Key 的请求被拒（提示智谱套餐已过期），绑定新兑换码即可续期，客户端配置不变；点数 Key 与点数钱包不受影响（账户永不过期，预付余额在即可继续用）。账户被禁用则全部 Key 停用。