
将 Kilo Code 接入 CCR仅 CLI 场景的 Agent 配置全流程与底层原理【免费下载链接】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本指南对应仓库中文文档 docs/src/content/docs/zh/configuration/agents/kilo.md讲解如何在 claude-code-router下称 CCR中为 Kilo Code 创建启动配置让这款采用 OpenAI 兼容供应商模型的编码 Agent 走任意 CCR 供应商或 Fusion 模型并落地为可复用的ccr-app/ccr命令。读完本文你将掌握 Kilo Code 配置的每一步操作、字段语义、系统默认接管机制以及 CCR 底层如何生成并写入 Kilo 的kilo.jsonc。适用场景Kilo Code 是一款采用OpenAI 兼容供应商模型的编码 Agent。在 CCR 中它与 Grok CLI、Kimi CLI 一样属于仅支持 CLICLI only的一类没有 App 桌面入口。这一点在代码中也有直接体现profileOpenSurfaces()将 grok、kimi、pi、kilo 四类 Agent 固定返回[cli]见 packages/core/src/profiles/launch-core.ts。因此当你希望做到以下任一点时就适合使用本文的配置方式让 Kilo Code 的请求走 CCR 网关路由到某个 CCR 供应商的模型让 Kilo Code 使用 CCR 创建的Fusion 模型在不改动系统上直接打开的 Kilo 的前提下从 CCR 单独启动一个“受管”的 Kilo 实例创建多个 Kilo 配置实现不同项目 / 用途使用不同模型与供应商。首次使用 CCR请先完成“接入供应商”与模型参见 接入供应商对 Agent 配置的通用概念配置名称、启用开关、作用范围、多开等还不熟悉先阅读 Agent 配置总览。前置条件CCR Desktop 正在运行且已配置至少一个供应商与模型若还没有先按 接入供应商 操作。已安装 Kilo Code并且其可执行文件kilo位于PATH中——注意它需要能在启动 CCR Desktop 的那同一个 shell 环境里被找到。进入 CCR 的Agent 配置页面点击添加配置。创建配置在Agent 配置页面按以下顺序完成一个 Kilo Code 配置点击添加配置在 Agent 列表中选择Kilo Code。此时 CCR 会固定该 Agent 的入口模式为仅 CLI不可编辑为 App。填写配置名称例如Kilo - Work。该名称用于标识配置也是后续命令的定位参数支持空格CCR 在复制命令时会自动加引号。选择生效范围即作用范围仅从 CCR 打开时生效或系统默认二者只能影响从 CCR 打开的 Kilo后者还会接管你直接打开的 Kilo。确认供应商 ID、供应商名称与Kilo 模型三个字段详见下文“配置项详解”。只有本机环境确有特殊要求时再进入高级设置调整如自定义环境变量或可执行文件路径。点击保存然后复制并运行配置卡片上给出的命令即可启动。配置项详解Kilo Code 固定为仅 CLI因此入口模式不可编辑界面里也只会暴露与该模式相关的字段。可配置字段及效果如下字段如何配置效果Agent选择Kilo Code在 CCR 中创建 Kilo Code 启动入口配置生成逻辑会按kiloAgent 走专门的配置文件写入与启动封装流程。配置名称自由文本例如Kilo - Work标识该配置。桌面端命令使用ccr-app 名称CLI 命令使用ccr 名称。启用开关关闭的配置不会被应用也不会出现在启动入口中等价于不作为有效的启动配置。生效范围仅从 CCR 打开时生效/系统默认前者只影响从 CCR 打开的 Kilo后者会作为系统默认 Kilo 配置也会影响直接打开的 Kilo。同一 Agent 只允许一个启用的系统默认配置。供应商 ID默认claude-code-router当前 Kilo 配置使用的供应商引用。它会作为写入 Kilo 配置中的 provider 键名。供应商名称自由文本默认Claude Code Router在 Kilo 中显示的名称。Kilo 模型供应商模型或 Fusion 模型Kilo 通过 CCR 使用的默认模型通常写作供应商/模型形式。配置文件路径用于系统默认 Kilo 配置指定后 CCR 写入该真实文件留空则自动落到 Kilo 自己的默认配置位置。环境变量键值对可选高级设置普通使用保持为空。打开与使用保存配置后从Agent 配置的卡片上取命令桌面端配置卡片复制出的命令同时适用于拥有 CCR Desktop 图形界面的环境ccr-app Kilo - Work纯 CLI 环境请执行ccr Kilo - Work两条命令的本质都是找到名为Kilo - Work或对应 ID的已启用配置并为其构建启动计划。CCR 会先按名称或 ID 做精确匹配再做归一化模糊匹配若多个配置同名会提示“配置有歧义请改用配置 ID”见 packages/core/src/profiles/launch-core.ts。配置名称允许空格复制出的命令中 CCR 已经根据平台处理好引号直接粘贴运行即可。底层原理CCR 如何把 Kilo 接到网关理解“配置卡片保存后发生了什么”能帮你更好地排查问题。以scope: ccr即仅从 CCR 打开时生效为例CCR 会把配置编译成一个独立的受管配置目录与一个启动 wrapper整个过程分布在两个文件中。1. 生成 Kilo 的 OpenAI 兼容供应商配置在 packages/core/src/agents/kilo/profile-config.ts 中writeKiloGatewayConfig()负责把配置编译为 Kilo 可读取的kilo.jsonc配置文件落点resolveKiloConfigFile()按作用范围选择路径。ccr/custom范围写到 CCR 受管目录configDir/profiles/slug/kilo/kilo.jsonccustom再嵌套一层custom/global系统默认范围优先使用你填的配置文件路径否则按XDG_CONFIG_HOME缺省~/.config定位kilo/kilo.jsonc若存在kilo.json、opencode.jsonc、opencode.json也会被识别为候选并命中第一个存在的文件。供应商与端点以默认供应商 IDclaude-code-router为键写入 providernpm使用ai-sdk/openai-compatiblebaseURL指向 CCR 本地网关的/v1如http://127.0.0.1:端口/v1API Key 填入为本次配置签发的 CCR token。请求标记请求头写入x-ccr-client: kilo与x-ccr-profile: profile这样网关侧能识别请求确实来自“由 CCR 托管的 Kilo”方便请求日志归因。主模型与小模型model与small_model都指向${providerId}/${model}形态的模型引用确保 Kilo 的主模型和轻量模型都经由 CCR 提供。保留用户既有设置读取已存在的 JSONC 文件时会合并保留原有的$schema、autoupdate等用户设置只新增 / 覆盖 provider 与模型字段避免破坏用户手动维护的其他选项。下面的 JSON 是该函数写入结果的结构示意字段以 packages/core/test/unit/agents/kilo-profile-config.test.mjs 中断言的输出为准端口等按测试环境示例{ $schema: kilo 官方配置 schema来自源码默认值, model: claude-code-router/Provider/model-a, small_model: claude-code-router/Provider/model-a, provider: { claude-code-router: { name: Claude Code Router, npm: ai-sdk/openai-compatible, models: { Provider/model-a: { name: Provider/model-a } }, options: { apiKey: 本次签发的 CCR token, baseURL: http://127.0.0.1:4567/v1, headers: { x-ccr-client: kilo, x-ccr-profile: kilo-main } } } } }2. 模型值的两种写法配置界面的Kilo 模型既可以直接选供应商模型 / Fusion 模型也可以接受形如供应商,模型名的写法。normalizeClientModel()会把Provider,model-a这类“逗号分隔”写法转换为Provider/model-a再拼接为最终的claude-code-router/Provider/model-a引用见 packages/core/src/agents/kilo/profile-config.ts。如果你发现“模型不对”优先检查该字段最终是否解析成了 CCR 确实能提供的模型。3. 生成启动 wrapper在 packages/core/src/profiles/service.ts 中CCR 会为每个 Kilo 配置生成一个专属 wrapper类 Unix 下为configDir/bin/ccr-kilo-wrapper-slugWindows 下为同名的.cmd。wrapper 的核心行为export KILO_CONFIG指向刚生成的 kilo.jsonc export KILO_CONFIG_CONTENT内联配置 JSON export CCR_PROFILE_SURFACEcli exec kilo $即通过KILO_CONFIG/KILO_CONFIG_CONTENT把受管配置注入 Kilo然后原地替换进程执行真实的kilo。与此同时 packages/core/src/profiles/launch-core.ts 的buildKiloLaunchPlan()会确定 wrapper 路径并显式拒绝非 CLI 打开方式。4. 安全性与回滚保护写配置时 CCR 会做两类保护测试覆盖见 packages/core/test/unit/agents/kilo-profile-config.test.mjs权限收紧生成的配置文件及相关产物在非 Windows 平台被chmod为0600因为它们内含 CCR token原文件快照首次接管用户的真实 Kilo 配置文件前会保留一份.ccr-original快照每次写入前还会生成带时间戳的.ccr-backup-*备份若两次写入内容完全一致则判定changed: false不做重复写入。环境变量与自定义可执行文件普通使用场景下环境变量保持为空即可。CCR 会把你在界面中填写的键值对透传进 wrapper 环境会自动剔除以下受管键避免覆盖受管配置CCR_KILO_BIN、KILO_BIN、KILO_CONFIG、KILO_CONFIG_CONTENT、KILO_CONFIG_DIR、KILO_PROVIDER、CCR_PROFILE_SURFACE。其中较有实用价值的是CCR_KILO_BIN也兼容KILO_BIN当你的kilo不在PATH默认位置、或希望该配置指向特定版本的 Kilo 时可用它显式指定可执行文件路径wrapper 会exec该路径而非命令名kilo。多实例需要不同模型或供应商时创建多个 Kilo 配置即可——这是 CCR 的通用“多开”模型每个配置都是独立的启动入口与独立的受管kilo.jsonc互不覆盖。例如可以同时拥有Kilo - Work生效范围仅从 CCR 打开时生效主模型为公司内部供应商 AKilo - Fusion同一配置下选择某个 Fusion 模型供日常轻量任务使用Kilo - Personal模型指向个人 API 供应商。需要哪个场景就运行哪个配置的命令不同配置之间通过各自独立的配置文件隔离不会互相串模型。提示若某个配置需要作为系统默认即直接打开 Kilo 也生效要保证同一时刻只存在一个“启用”的该系统默认配置否则 CCR 会拒绝重复接管。验证完成配置后按以下顺序确认整条链路可用运行配置卡片复制的命令桌面端ccr-app Kilo - Work或 CLIccr Kilo - Work。在 Kilo 中发送一条消息确认能正常收到回复。打开 CCR 的请求日志确认该请求已经经过 CCR 网关。由于 CCR 在写入配置时带有x-ccr-client: kilo标记头请求日志中可按 Agent 类型kilo过滤即可快速确认它确实走了网关而不是直连上游。若只做到第 2 步而第 3 步查不到记录说明请求很可能绕过了 CCR请回看下文的常见问题。常见问题请求绕过了 CCR确认该配置处于启用状态并且你是通过 CCR 生成的配置命令ccr-app/ccr启动的 Kilo若生效范围不是系统默认直接双击/命令行打开 Kilo 不会应用该配置属于预期行为。找不到kilo确认 Kilo Code 已安装并且启动 CCR Desktop 的同一 shell 环境可以解析到kilowrapper 只是继承启动环境的PATH。若 Kilo 装在非标准位置可在配置的环境变量中用CCR_KILO_BIN显式指定完整路径。模型不对确认Kilo 模型字段最终能解析为 CCR 可以提供的模型——普通供应商模型应为供应商/模型形式若填写的是 Fusion 模型确认其已创建并处于可用状态。怀疑配置被改坏CCR 会在接管真实 Kilo 配置文件前生成.ccr-original快照并在每次写入前生成.ccr-backup-*可据此回滚受管配置文件也会被自动设为本用户可读写权限0600以保护其中的 token。更多参考本文档英文版docs/src/content/docs/en/configuration/agents/kilo.mdAgent 配置通用字段与多开说明Agent 配置总览供应商与模型接入前置步骤接入供应商配置生成实现packages/core/src/agents/kilo/profile-config.ts、启动计划与范围判定packages/core/src/profiles/launch-core.ts、wrapper 生成packages/core/src/profiles/service.ts行为测试packages/core/test/unit/agents/kilo-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),仅供参考