在 Claude Code Router 中配置 ZCode：将 ZCode 桌面 App 接入任意 Provider、Fusion 模型与 IM 机器人-迪斯科星球

在 Claude Code Router 中配置 ZCode：将 ZCode 桌面 App 接入任意 Provider、Fusion 模型与 IM 机器人

【免费下载链接】claude-code-routerOne local control plane for every AI agent: route across models, fuse new capabilities, orchestrate tools, and stay fully in control.项目地址: https://gitcode.com/GitHub_Trending/cl/claude-code-router

ZCode 是智谱（Z.ai）生态中一款以桌面应用形态运行的 AI 编程助手。在 Claude Code Router（CCR）中，ZCode 被固定为App only形态，本文围绕官方配置指南（docs/src/content/docs/en/configuration/agents/zcode.md）逐步讲解：如何在 CCR Desktop 中创建 ZCode Profile、把 ZCode App 路由到任意 CCR Provider 或 Fusion 模型、绑定 AgentClaw IM 机器人，并深入源码剖析 CCR 为 ZCode 写入网关配置的底层实现。读完本文，你将能独立完成 ZCode 的接入、多实例管理与排障。

如果你是 CCR 新手，建议先完成 Provider 与模型的添加，再阅读 Agent Config（配置概览）文档，随后回到本文创建 ZCode Profile。

ZCode 在 CCR 中的定位：为什么是 App only

与 Claude Code（可 CLI/App 双形态）、Grok CLI 等不同，ZCode 是一个桌面应用，没有独立的本地 CLI 作为主入口。因此在 CCR 中，ZCode 被归类为App only，即只能通过「CCR Desktop 打开 ZCode App」的方式进入网关。

这一约束在源码中是被强制的，而不是一个可选 UI 状态：

在 profiles/launch-core.ts 中，profileOpenSurfaces()对workbuddy、zcode、claude-design一律返回["app"]，而对grok、kimi、pi、kilo则只返回["cli"]；
同时 config/config.ts 在解析 Profile 时，会将agent === "zcode"的surface直接置为"app"，忽略用户可能写入的entry、frontend等字段。

结论：ZCode Profile 的入口模式（entry mode）在 CCR 中不可编辑，你只能在「从 CCR 打开 ZCode App」这一固定路径下配置其余字段。

前置条件

在创建 Profile 前，请确认以下三项均已满足：

CCR Desktop 正在运行，且至少已配置一个 Provider + 模型（任一网关 Provider 或 Fusion 虚拟模型均可）；
本机已安装 ZCode 桌面应用并完成登录，且 ZCode 的存储目录中存在其配置文件（默认位于~/.zcode/）；
你能访问 CCR 的Agent Config页面，并会使用Add profile按钮。

说明：CCR 会主动探测本机 ZCode 的配置与登录状态。agents/local-providers/zcode.ts 中的zcodeCandidate()会读取~/.zcode/v2/config.json、~/.zcode/cli/config.json以及凭据文件~/.zcode/v2/credentials.json：若检测到 ZCode Provider 的 API Key 与 baseURL，会给出可导入的zcode-api候选；若仅有登录态但没有可用 Key，则候选会处于locked状态并提示原因。这决定了你在 CCR 中看到的 ZCode 接入提示内容。

创建 ZCode Profile

在 CCR Desktop 中按以下步骤创建 Profile：

进入Agent Config，点击Add profile，选择ZCode；
填写Config name（例如ZCode - Work），该名称用于标识 Profile，也用于后续命令行启动；
确认Provider ID、Provider name与ZCode model三项；
仅在本地环境确有需要时，再调整高级设置（例如环境变量）；
如果使用 AgentClaw，请绑定一个Bot；
点击Save保存，然后点击 Profile 卡片上的播放按钮从 CCR 启动 ZCode。

为什么保存动作不只是「存一条记录」

在源码层，点击 Save 会触发 agents/zcode/profile-config.ts 中的writeZcodeGatewayConfig()，它会一次性写入三份 ZCode 配置：

写入目标	作用
`<zcode_home>/cli/config.json`	ZCode CLI/App 主配置：网关 Provider 与默认模型
`<zcode_home>/v2/config.json`	ZCode v2 配置：追加`claude-code-router`Provider
`<zcode_home>/v2/bots-model-cache.v2.json`	模型缓存：更新默认模型、Provider 模型列表与 revision

写入前会做一次性原始快照备份（.ccr-original/.ccr-original-missing后缀），每次改动还会生成带时间戳的.ccr-backup-<timestamp>副本，保证用户原始 ZCode 配置可追溯、可恢复。写入内容把 CCR 网关描述为一个kind: "anthropic"的 Provider，其baseURL指向本机网关（默认http://127.0.0.1:<gateway.port>，若网关监听0.0.0.0会自动归一为127.0.0.1），apiKey使用 CCR 为该 Profile 分配的令牌，model.main被设置为providerId/model引用。

配置字段参考

ZCode 固定为 App only，因此可配置字段如下。保存后写入的具体含义（第三列）可在本文「源码佐证」部分找到对应实现。

Field	How to set it	Effect
Agent	选择ZCode	在 CCR 中创建一个 ZCode App 启动条目（Entry）。
Config name	自由文本，例如`ZCode - Work`	标识该 Profile；桌面端命令使用`ccr-app "<name>" app`，CLI 命令使用`ccr "<name>" app`。
Enabled	开关	关闭后 Profile 不生效，也不会作为启动条目被提供。
Effect scope	`Only opened from CCR`/`System default`	将 Profile 限制为仅 CCR 启动时生效，或将其设为系统默认 ZCode Profile；同一时刻只允许存在一个启用的 System default ZCode Profile。
Provider ID	默认`claude-code-router`	该 ZCode Profile 引用的 Provider 标识。
Provider name	自由文本，默认`Claude Code Router`	显示在 ZCode 中的 Provider 名称。
ZCode model	某个 Provider 模型或 Fusion 模型	ZCode App 打开时使用的默认模型。
Config file	路径	仅用于 System default ZCode Profile；默认路径为`~/.zcode/cli/config.json`。
Environment variables	Key/Value 行	可选的高级覆盖项，常规使用保持为空。
Bot	选择一个已保存的 Bot	将 AgentClaw IM 机器人绑定到该 ZCode App 条目上。

关键字段的源码佐证

Provider ID 与 Provider name：解析逻辑位于 config/config.ts，读取providerId/provider字段，缺省时回退为claude-code-router；providerName缺省时回退为Claude Code Router。

ZCode model：该字段是一个路由选择器（形如Provider/Model或 Fusion 模型别名）。在写入 ZCode 配置前，CCR 会用 agents/zcode/model-catalog.ts 的buildZcodeModelCatalog()解析出该模型对应的物理 Provider 与真实模型，并据此生成 ZCode 侧可用的模型清单（见下文「模型目录与上下文窗口」一节）。

Config file / 旧版路径兼容：默认配置路径在 config/config.ts 中被定义为~/.zcode/cli/config.json；如果 Profile 中显式填了旧的 TOML 路径~/.zcode/config.toml，CCR 会把它归一化回新的默认路径（见 profile-config.ts 与 config/config.ts），保证不会误写旧格式。

Enabled 与启动入口：被禁用（enabled: false）的 Profile 不会出现在启动候选里，profiles/launch-core.ts 中按名称查找 Profile 时会直接以「not found or disabled」拒绝。CCR 对 ZCode 统一走app形态的启动计划，其最终启动命令由profileOpenCommand()（launch-core.ts）拼装为<command> "<name>" app。

打开并使用 ZCode

点击 Profile 卡片上的播放按钮即可用该 Profile 指定的 Provider 与模型打开 ZCode；再次打开同一 Profile 时会激活已存在的 ZCode 窗口，而不是另起新实例。

从 Profile 卡片可直接复制桌面端启动命令：

ccr-app "ZCode - Work" app

CLI 侧则运行：

ccr "ZCode - Work" app

两条命令中，"ZCode - Work"是 Profile 名称，app是形态参数——ZCode 在 CCR 中仅支持app形态，这也是defaultProfileOpenSurface()对 zcode 返回"app"的原因（launch-core.ts）。

ZCode Provider 的模型目录与上下文窗口

CCR 写入的 ZCode 配置并不仅仅是「一串模型名」。为了让 ZCode 正确展示可用模型与上下文限制，CCR 会为每个模型补齐以下元数据：

默认上下文窗口：128_000（128K token）；
默认最大输出 Token：8_192；
能力位：支持图片输入（text+image）、结构化输出与工具调用（tool_call: true）。

这些默认值定义在 agents/zcode/profile-config.ts，模型的 limit 结构在zcodeModelConfig()（同文件 #L159-L177）中生成。buildZcodeModelCatalog()则会进一步把模型解析为网关侧的真实上下文窗口：

对普通 Provider 模型，结合模型目录（model-catalog）中登记的context_window/max_context_window取最大值；
对 Fusion 虚拟模型，通过 usage/model-attribution.ts 归因到其物理 Provider/模型后取物理模型的实际窗口；
若某模型是「请求时路由」的动态虚拟模型（当前不存在单一物理模型），则保留基础窗口而不强行猜测。

单元测试 test/unit/agents/zcode-profile-config.test.mjs 验证了这一行为：已知模型按解析出的实际窗口写入（示例中被归并为1_050_000），未知模型回退到默认128_000，输出上限统一为8_192，并且三份文件（cli/config.json、v2/config.json、bots-model-cache.v2.json）中的模型限制一致。

顺带一提：把 ZCode API 导入为 CCR Provider

如果你希望反向使用 ZCode 的模型能力（即把 ZCode / z.ai 作为 CCR 的上游 Provider，让 Claude Code 等其他 Agent 也能调用），CCR 会在检测到 ZCode 本地配置中的 API Key 后，在「Add Provider」界面提供ZCode API候选并支持一键导入：

默认模型候选：GLM-5.2、GLM-5-Turbo；
默认 baseURL：https://zcode.z.ai/api/v1/zcode-plan/anthropic（协议为 Anthropic Messages）；
检测与导入逻辑见 agents/local-providers/zcode.ts。

这条路径与本文主线（把 ZCode 作为 CCR 的客户端接入）方向相反但互补：一个是「ZCode 走 CCR 的模型」，一个是「CCR 走 ZCode 的模型」。

多实例

当你希望用不同模型或不同 Provider 打开 ZCode 时，无需反复修改一个 Profile——直接创建多个 ZCode Profile 即可。例如：

ZCode - Work：绑定工作用 Provider 与模型；
ZCode - GLM：绑定 Fusion/其他 Provider 与 GLM 模型；
ZCode - System：Effect scope 设为System default（全局仅允许一个启用的此类 Profile）。

CCR 内部通过configFile/codexHome区分不同 Profile 写入的 ZCode 配置文件，每个 Profile 对应独立的网关令牌与默认模型引用。

AgentClaw（IM Bot 接力）

ZCode 桌面 App 天然是一个可以承载对话的客户端。若满足以下两个条件：

在 Profile 上绑定了一个已保存的 AgentClawBot；
该 ZCode 是从 CCR 打开的（而非独立启动），

则 ZCode 可以通过所选 IM 渠道（如飞书、钉钉、Discord、Telegram 等）接力转发对话。值得注意的是：关闭 ZCode App 会立刻使接力（Relay）离线——因为中继依赖 App 进程本身存活。AgentClaw 的整体概念与渠道接入，可阅读 agentclaw.md 及对应的 IM 平台子页面（agentclaw 渠道文档）。

验证接入是否成功

接入完成后，建议按以下三步验证端到端链路：

从 CCR 打开 ZCode（务必点击 CCR 里的播放按钮，而不是直接双击系统里的 ZCode 图标）；
发送一条消息并确认能收到回复；
回到 CCR 打开Request logs，确认这条请求确实经过了网关（能看到该请求对应的路由与 Provider 命中记录），而不是直连了 ZCode 默认后端。

常见问题

请求绕过了 CCR（Requests bypass CCR）：先确认 Profile 处于Enabled状态，且你是从 CCR 打开的 ZCode。若 ZCode 之前已被独立启动，请先关闭它，再从 CCR 重新打开——否则已运行的窗口不持有 CCR 注入的网关配置。
App 内模型不对（Wrong model in the App）：检查 Profile 中的ZCode model字段是否填成了你期望的路由选择器；同时可在 CCR 的 Request logs 中核对实际命中的 Provider/模型。
Bot 接力掉线（Relay went offline）：ZCode App 必须保持打开状态。任何关闭 ZCode App 的操作都会立即使 IM 接力离线，需要重新从 CCR 启动它。

企业官网建设流程全解析