Kilo Code 接入 Atomic Chat 本地模型OpenAI 兼容 API 配置与源码级原理解析【免费下载链接】kilocodeKilo is the all-in-one agentic engineering platform. Build, ship, and iterate faster with the most popular open source coding agent.项目地址: https://gitcode.com/GitHub_Trending/ki/kilocodeKilo Code 通过内置的kilocode/plugin-atomic-chat插件将 Atomic Chat与仓库源码完整讲解在 VS Code 与 CLI 两种形态下的配置步骤、自定义模型注册、禁用方法并从源码层面剖析默认不访问 localhost的 opt-in 机制、模型自动发现与加载状态校验的实现原理。前置条件在配置 Kilo Code 之前需要先完成 Atomic Chat 侧的准备工作安装 Atomic Chat 桌面应用支持 macOS 与 Windows。在应用内下载并加载load一个模型。开启应用内的local API server本地 API 服务器默认端口为1337。验证 API 已正常响应curl http://127.0.0.1:1337/v1/models该命令会返回 Atomic Chat 已加载模型的 JSON 列表其结构与 OpenAI 的/v1/models兼容。从源码看插件所消费的响应类型正是 OpenAI 风格的结构// packages/plugin-atomic-chat/src/types/index.ts export interface AtomicChatModel { id: string object: string created: number owned_by: string } export interface AtomicChatModelsResponse { object: string data: AtomicChatModel[] }也就是说插件只依赖data[].id作为模型的唯一标识curl输出中的id字段将直接用于后续的模型引用。安全默认默认不访问 localhostkilocode/plugin-atomic-chat随 Kilo Code 默认内置对应仓库 packages/plugin-atomic-chat/package.json名称为kilocode/plugin-atomic-chat。但插件默认不会向本地服务发起任何 HTTP 请求——这一点由源码中的shouldProbeAtomicChat判定逻辑保证// packages/plugin-atomic-chat/src/utils/should-probe-atomic-chat.ts export function shouldProbeAtomicChat(config: any): boolean { return ( hasAtomicChatProviderSection(config) || isAtomicChatAutoDetectEnabled(config) || isAtomicChatModelSelected(config) ) }仅当以下任一条件成立时Kilo Code 才会访问本地 Atomic Chat 服务在kilo.jsonc中配置了provider.atomic-chat块显式启用 provider设置了model: atomic-chat/...或在 per-agent 模型配置中使用了atomic-chat前缀 /providerID开启了可选自动检测atomicChat: { autoDetect: true }会依次探测1337和1338两个端口。条件 2 的判定甚至支持按 agent 维度配置模型。从源码可以看到模型引用既可以是atomic-chat/modelId这样的字符串也可以是{ providerID: atomic-chat, modelID: ... }这样的对象形式并且会遍历config.model下所有 agent 模式如code、general逐一检查// packages/plugin-atomic-chat/src/utils/should-probe-atomic-chat.ts function modelRefUsesAtomicChat(ref: unknown): boolean { if (typeof ref string) { return ref.startsWith(${ATOMIC_CHAT_PROVIDER_KEY}/) } ... return record.providerID ATOMIC_CHAT_PROVIDER_KEY }这一设计对受限网络环境restricted environments非常友好不配置就不产生任何 localhost 请求避免了对本地服务的意外探测与潜在冲突。对应测试 should-probe-atomic-chat.test.ts 明确断言空配置不触发 localhost HTTP同时验证三种 opt-in 路径均能正确返回true。在 VS Code 中配置打开Settings齿轮图标→Providers→Atomic Chat默认本地服务器无需 API Key——源码 auth-hook.ts 注册的认证方式即为{ type: api, label: Local server }表明直接走本机 API无鉴权开销。如果 Atomic Chat 使用了非默认的主机或端口在设置中调整base URL即可。在 CLI 中配置CLI 形态使用配置文件~/.config/kilo/kilo.jsonc或项目根目录的./kilo.jsonc。1. 配置 provider 块{ provider: { atomic-chat: { options: { baseURL: http://127.0.0.1:1337/v1, }, }, }, }baseURL的解析逻辑见 atomic-chat-api.ts 中的normalizeBaseURL它会去除末尾斜杠并将/v1后缀归一化最终拼出/v1/models端点因此无论你写http://127.0.0.1:1337还是http://127.0.0.1:1337/v1都能正确工作。2. 设置默认模型模型 id 以curl http://127.0.0.1:1337/v1/models的返回值为准{ model: atomic-chat/gemma-4-E4B-it-IQ4_XS, }3. 可选免 provider 块的自动检测如果不写 provider 块也可以直接开启自动检测{ atomicChat: { autoDetect: true }, }开启后插件会在配置加载阶段调用autoDetectAtomicChat见 atomic-chat-api.ts依次探测[1337, 1338]两个端口常量定义于 constants.ts返回第一个可达的服务器及其模型列表。值得关注的是自动检测成功后的副作用插件会主动向配置写入完整的 provider 块将检测到的 baseURL、模型清单一并填充// packages/plugin-atomic-chat/src/plugin/enhance-config.ts setAtomicSection(config, { npm: ai-sdk/openai-compatible, name: Atomic Chat (local), options: { baseURL: ${baseURL}/v1, }, models: {}, })从源码结构看它底层通过ai-sdk/openai-compatibleSDK 与 Atomic Chat 通信因此任何遵循 OpenAI 兼容协议的能力chat、embeddings都可以复用。4. 完全禁用该 provider如需彻底关闭使用disabled_providers列表或直接从plugin数组中移除kilocode/plugin-atomic-chat{ disabled_providers: [atomic-chat], }两种方式任选其一即可。自定义或未列出的模型当 Atomic Chat 已加载的模型没有出现在 Kilo Code 的模型选择器中时可以在provider.atomic-chat.models下手动注册{ model: atomic-chat/my-local-model, provider: { atomic-chat: { models: { my-local-model: { id: exact-id-from-v1-models, name: My Local Model, }, }, }, }, }其中id必须是GET /v1/models返回的精确 id区分大小写name用于在 UI 中展示。模型字段的完整说明参见 custom-models.md。自动发现时的模型处理细节当插件通过enhanceConfig自动发现模型时会做以下处理见 enhance-config.tsmodel key 清洗对于包含非[a-zA-Z0-9_-]字符的模型 id会用下划线替换非法字符生成配置键但保留原始id用于 API 请求类型归类通过categorizeModel区分 chat 与 embedding 模型——chat 模型写入modalities: { input: [text, image], output: [text] }embedding 模型写入modalities: { input: [text], output: [embedding] }名称格式化formatModelName会把gemma-4-E4B-it-IQ4_XS这类 id 拆分成可读名称并自动将gpt、gguf、it、vl、量化标记如Q4等常见缩写与参数量标记如4B转为大写见 format-model-name.ts组织归属extractModelOwner提取 id 中/前的部分作为organizationOwner如google/gemma-...会归属google已存在模型不覆盖用户在models中手动注册的条目优先自动发现仅补充缺失项异常告警若只检测到 embedding 模型而没有任何 chat 模型会提示请先在 Atomic Chat 中加载 chat 模型。模型加载状态校验与故障提示这是插件最实用的能力之一在每次发起对话前chat.params钩子chat-params-hook.ts会校验所选模型当前是否真的已加载通过getLoadedModels拉取 Atomic Chat 当前已加载模型列表结果由sharedModelStatusCache缓存带 TTL校验失败时以forceRefresh强制刷新重试校验带指数退避重试retryWithBackoff最多 3 次、间隔 500ms给模型加载留出时间窗口若模型未加载会按offline服务不可达、not_found模型未加载、network、timeout等类别归类错误类型定义见 types/index.ts通过 toast 通知用户并提供排查步骤打开 Atomic Chat → 加载目标模型 →curl http://127.0.0.1:1337/v1/models确认模型 id 存在 → 在 Kilo Code 中重试还会调用findSimilarModels推荐名称相近的已加载模型方便快速切换校验结果写入output.options.atomicChatValidation供 UI 展示。此外配置加载阶段config-hook.ts会在 5 秒超时内完成一次模型发现若发现 0 个模型会记录告警Atomic Chat may be offline or no model loaded。缓存统计CacheStats含age、modelCount、ttl也被用于在提示中告知用户缓存新鲜度。实践建议优先选择大上下文窗口的强模型Agent 工作流依赖长提示词long prompts小上下文模型容易在多次工具调用后截断只加载必要的模型Atomic Chat 中同时加载的模型越多内存占用越高也会拖慢GET /v1/models的响应。插件在加载了多个模型时也会给出性能提示embedding 走 openai-compatible 索引提供方如需用 Atomic Chat 做向量嵌入在索引indexing配置中选择openai-compatibleprovider并使用相同的 base URL 即可复用本地推理排查链路自检遇到模型不可用优先依次检查——Atomic Chat 是否运行、本地 API 是否开启、curl http://127.0.0.1:1337/v1/models是否列出目标模型、配置中的baseURL是否与 Atomic Chat 设置一致。相关文档LM Studio 本地模型接入Ollama 本地模型接入本地模型总览自定义模型字段详解【免费下载链接】kilocodeKilo is the all-in-one agentic engineering platform. Build, ship, and iterate faster with the most popular open source coding agent.项目地址: https://gitcode.com/GitHub_Trending/ki/kilocode创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考