ZCode

ZCode 桌面编程 Agent。通过 ~/.zcode/v2/config.json 写入 Trinity 供应商，用 xh-... Key 调用 模型广场 中的模型。

---

获取 API Key

1. 在 控制台 · API 密钥 创建 Key（xh-...）。
2. 见 管理 API 密钥。

模型 ID 见 模型广场。

---

快速配置

写入 ~/.zcode/v2/config.json，同时写入 kind 与 apiFormat（例如 gpt-5.4 → kind: openai + apiFormat: openai-responses）。仅写 baseURL 时 ZCode 会推断为 Chat Completions。

npx -y trinity-config@latest --type zcode -k xh-你的key --model gpt-5.4

修改配置后重启 ZCode，并在应用设置中启用 Trinity 供应商。

---

手动配置

编辑 ~/.zcode/v2/config.json。Provider id 为 trinity，模型引用为 trinity/<model_code>。

协议	kind	apiFormat	options.baseURL
Anthropic Messages	anthropic	anthropic-messages	https://api.trinitydesk.ai（不带 /v1）
Responses	openai	openai-responses	https://api.trinitydesk.ai/v1
Chat Completions	openai-compatible	openai-chat-completions	https://api.trinitydesk.ai/v1

Responses 示例（gpt-5.4）：

{
  "model": "trinity/gpt-5.4",
  "provider": {
    "trinity": {
      "enabled": true,
      "name": "Trinity",
      "source": "custom",
      "kind": "openai",
      "defaultKind": "openai",
      "apiFormat": "openai-responses",
      "npm": "@ai-sdk/openai",
      "options": {
        "baseURL": "https://api.trinitydesk.ai/v1",
        "apiKey": "xh-你的key"
      },
      "models": {
        "gpt-5.4": {
          "name": "gpt-5.4",
          "kinds": ["openai"],
          "defaultKind": "openai"
        }
      }
    }
  }
}

重启 ZCode 后，在模型设置中启用 Trinity 供应商并选择 trinity/gpt-5.4。

故障排查

问题	排查
401 Unauthorized	确认 API Key 以 xh- 开头且未过期
403 model_not_allowed	在控制台确认 Key 有该模型的调用权限
连接超时	确认 Base URL 正确（Anthropic 不带 /v1，其余带 /v1）
模型未找到	在 模型广场 核对模型 ID

WARNING

不要将 API Key 提交到 Git 仓库。使用环境变量或配置文件管理 Key，定期轮换。