在 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-routerZCode 是智谱Z.ai生态中一款以桌面应用形态运行的 AI 编程助手。在 Claude Code RouterCCR中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.jsonZCode CLI/App 主配置网关 Provider 与默认模型zcode_home/v2/config.jsonZCode v2 配置追加claude-code-routerProviderzcode_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.1apiKey使用 CCR 为该 Profile 分配的令牌model.main被设置为providerId/model引用。配置字段参考ZCode 固定为 App only因此可配置字段如下。保存后写入的具体含义第三列可在本文「源码佐证」部分找到对应实现。FieldHow to set itEffectAgent选择ZCode在 CCR 中创建一个 ZCode App 启动条目Entry。Config name自由文本例如ZCode - Work标识该 Profile桌面端命令使用ccr-app name appCLI 命令使用ccr name app。Enabled开关关闭后 Profile 不生效也不会作为启动条目被提供。Effect scopeOnly 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 variablesKey/Value 行可选的高级覆盖项常规使用保持为空。Bot选择一个已保存的 Bot将 AgentClaw IM 机器人绑定到该 ZCode App 条目上。关键字段的源码佐证Provider ID 与 Provider name解析逻辑位于 config/config.ts读取providerId/provider字段缺省时回退为claude-code-routerproviderName缺省时回退为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.tomlCCR 会把它归一化回新的默认路径见 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 appCLI 侧则运行ccr ZCode - Work app两条命令中ZCode - Work是 Profile 名称app是形态参数——ZCode 在 CCR 中仅支持app形态这也是defaultProfileOpenSurface()对 zcode 返回app的原因launch-core.ts。ZCode Provider 的模型目录与上下文窗口CCR 写入的 ZCode 配置并不仅仅是「一串模型名」。为了让 ZCode 正确展示可用模型与上下文限制CCR 会为每个模型补齐以下元数据默认上下文窗口128_000128K token默认最大输出 Token8_192能力位支持图片输入textimage、结构化输出与工具调用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默认 baseURLhttps://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 - SystemEffect scope 设为System default全局仅允许一个启用的此类 Profile。CCR 内部通过configFile/codexHome区分不同 Profile 写入的 ZCode 配置文件每个 Profile 对应独立的网关令牌与默认模型引用。AgentClawIM 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 默认后端。常见问题请求绕过了 CCRRequests 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 offlineZCode App 必须保持打开状态。任何关闭 ZCode App 的操作都会立即使 IM 接力离线需要重新从 CCR 启动它。相关文件导航官方指南英文原版docs/src/content/docs/en/configuration/agents/zcode.md中文镜像docs/src/content/docs/zh/configuration/agents/zcode.mdZCode 网关配置写入实现packages/core/src/agents/zcode/profile-config.tsZCode 模型目录构建packages/core/src/agents/zcode/model-catalog.tsZCode 本地配置探测与 API 导入packages/core/src/agents/local-providers/zcode.tsProfile 解析agent 归一化、surface 强制、默认路径packages/core/src/config/config.ts启动形态与命令拼装packages/core/src/profiles/launch-core.ts覆盖性测试packages/core/test/unit/agents/zcode-profile-config.test.mjs【免费下载链接】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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考