Kilo Code 接入 Atomic Chat 本地模型：OpenAI 兼容 API 配置与源码级原理解析-平芜编程栈

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/kilocode

Kilo 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字段将直接用于后续的模型引用。

安全默认：默认不访问 localhost

@kilocode/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.ts）：

model 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 设置一致。