
在 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),僅供參考