本文面向第一次使用 Terminal、第一次配置 Kilo Code，或者需要把 Kilo Code 接入第三方 AI Gateway 的用户。

完成本文后，你将能够：

• 安装并确认 Kilo Code CLI 或 Kilo Code for VS Code；
• 安全输入 AI Gateway 的 Base URL 和 API Key；
• 查询自己的 API Key 可以看到的模型；
• 根据模型厂商和实际路由选择 OpenAI Chat、OpenAI Responses 或 Anthropic Messages；
• 用标准 curl 验证模型是否能够返回最终文字；
• 把通过测试的模型写入 Kilo 全局配置；
• 用 kilo run 或 Kilo 图形界面发送第一条消息；
• 添加第二种协议或更多模型；
• 根据错误信息判断是网络、认证、模型路由、Kilo 配置还是高级能力问题。

本文以 macOS、zsh 和以下 AI Gateway 为例：

<https://cn-shanghai-alicloud-aimesh.api.clickzetta.com/gateway/v1>

本文命令已按 Kilo Code CLI 7.4.22 校验。版本号不同不一定有问题；如果命令参数或界面字段不同，请先执行对应命令的 --help，并参考第 16 节的官方资料。

最后验证日期：2026-08-19 验证环境：macOS、zsh、Kilo Code CLI 7.4.22 验证范围：模型目录、基础文本 curl、Kilo 配置加载和 Kilo 基础文本消息

如果你的地址不同，只需替换 Base URL。不同 API Key 能看到的模型可能不同；模型 ID 必须从你自己的 /models 结果中复制。

先看结论：模型厂商和请求协议是两件事

Kilo 不会根据模型名称自动选择协议。真正决定请求格式的是 Kilo 自定义 provider 的 Provider API 和 npm runtime。

本文使用三个容易识别的本地 provider 名称：

kilo run

kilo run

kilo run

这些 provider 名称只是 Kilo 本机配置名称，不是 AI Gateway 规定的名称，也不是模型厂商名称。若 Kilo 中已经存在其他 provider 名称，不需要为了匹配本文示例而重命名；继续沿用原名称，并把本文命令中的 provider ID 替换为你的实际名称。

按模型厂商选择协议

下面的矩阵只用于确定第一次应该测试哪个协议，不代表该厂商的所有模型都能通过该协议调用。最终以自己的模型目录、标准 curl 和 Kilo 实际消息测试结果为准。

已知兼容性提示：在本文示例网关、Kilo Code 7.4.22 和

@ai-sdk/openai

openai/gpt-5.5

/responses

SSE-Keep-Alive

text part SSE-Keep-Alive not found

kilo run

当前版本的协议验证状态

以下结果用于说明本文示例网关与 Kilo Code CLI 7.4.22 的协议适配状态，不限制其他 API Key 能够看到的模型范围：

qwen/qwen3.6-flash

anthropic/claude-opus-5

openai/gpt-5.5

SSE-Keep-Alive

这里的“Kilo 基础文本消息成功”表示

kilo run

最重要的规则是：

模型厂商 ≠ 请求协议 模型出现在目录中 ≠ 该模型已经可以调用 标准 curl 成功 ≠ Kilo 已经配置完成

你只需要为准备使用的协议配置 provider。只用 Claude 时可以只配置 relay-anthropic；只用 OpenAI Chat 时可以只配置 relay-chat；不需要一开始就配置全部三个 provider。

0. 完整操作路线

第一次配置时，请按以下顺序操作：

1. 安装或确认 Kilo Code 2. 准备 Base URL、API Key 和 Terminal 3. 初始化或确认 Kilo 全局配置 4. 安全保存 API Key 5. 查询自己的模型目录 6. 选择一个模型和一个目标协议 7. 用对应协议的 curl 取得最终文字 8. 把通过测试的模型写入 Kilo 9. 检查配置和模型列表 10. 用 kilo run 发送真实消息 11. 需要时再添加第二种协议或更多模型

完成第 10 步后，你已经具备基础文本对话能力。工具调用、图片、文件、结构化输出、流式传输和其他高级能力的适用范围见第 12 节。

1. 准备信息

开始前准备三项内容。

1.1 Base URL

本示例使用：

<https://cn-shanghai-alicloud-aimesh.api.clickzetta.com/gateway/v1>

该地址已经包含 /v1，不要写成：

<https://cn-shanghai-alicloud-aimesh.api.clickzetta.com/gateway/v1/v1> <https://cn-shanghai-alicloud-aimesh.api.clickzetta.com/gateway/v1/chat/completions> <https://cn-shanghai-alicloud-aimesh.api.clickzetta.com/gateway/v1/responses> <https://cn-shanghai-alicloud-aimesh.api.clickzetta.com/gateway/v1/messages>

Kilo 的 AI SDK runtime 会根据 provider 自动追加具体端点。

1.2 API Key

请从 AI Gateway 后台创建或复制 API Key，并确认：

• API Key 没有过期；
• API Key 有模型调用权限；
• Base URL 和 API Key 属于同一个环境和租户；
• 复制时没有多余空格或换行；
• 账户余额、配额和并发限制满足调用要求。

不要把真实 API Key 发到聊天、工单、截图、Git 仓库或公开网页。

1.3 模型 ID

模型 ID 是 AI Gateway 的路由键，必须从自己的模型目录中完整复制，例如：

vendor/model-name

版本号、点号、连字符、斜杠和厂商前缀都可能是 ID 的一部分。不要根据网页显示名称手写模型 ID，也不要自行改写大小写。

本文示例使用以下占位符：

YOUR_MODEL_ID

执行命令或保存配置前，必须把它替换为实际模型 ID。尖括号或大写占位符不能原样输入。

1.4 Terminal

本文所有命令都在 macOS Terminal 中执行。

打开方式：按 Command + Space，输入 Terminal，按回车。

你可能看到类似提示符：

user@Mac ~ %

不要复制提示符本身，只复制本文代码框中的命令。

2. 安装或确认 Kilo Code

2.1 检查基础工具

执行：

command -v curl command -v jq node --version npm --version

正常情况下，每条命令都会返回文件路径或版本号。

如果没有 jq，并且已经安装 Homebrew：

brew install jq jq --version

如果没有 Node.js 或 npm，请先从 Node.js 官方渠道安装当前 LTS 版本，再重新打开 Terminal。

2.2 检查 Kilo CLI

执行：

command -v kilo kilo --version type -a kilo

command -v 应返回 Kilo 路径，kilo --version 应返回版本号。

如果 type -a kilo 显示多个路径，后续排查时要确认 Terminal、VS Code 和脚本使用的是同一个版本。

2.3 没有安装时

执行：

npm install -g @kilocode/cli kilo --version

如果安装成功但仍提示 kilo: command not found，先检查：

npm prefix -g echo "$PATH"

把 npm prefix -g 对应的 bin 目录加入 PATH 后，重新打开 Terminal。

2.4 安装 Kilo Code for VS Code（可选）

如果使用 VS Code：

1. 打开 VS Code；
2. 打开 Extensions；
3. 搜索 Kilo Code；
4. 按 Kilo 官方安装页的说明安装推荐版本；
5. 安装后重新加载 VS Code。

本文优先使用 CLI 完成连通验证，因为 Terminal 能完整显示配置检查和错误信息。CLI 成功后，再按第 9.5 节使用 VS Code 界面。

2.5 确认当前 CLI 能力

执行：

kilo --help kilo config --help kilo models --help kilo run --help kilo debug paths

本文会使用以下命令：

kilo config check 检查配置 kilo models 查看模型 kilo run 发送一条消息 kilo debug paths 查看配置目录

3. 初始化 Kilo 配置

Kilo 的自定义 provider 配置保存在用户级全局配置中。全局配置可以安全解析 {file:...} 密钥引用，项目目录中的配置不适合保存凭据。

3.1 查看配置目录

执行：

kilo debug paths

macOS 默认配置目录通常是：

~/.config/kilo

Kilo 默认使用以下文件之一：

~/.config/kilo/kilo.json ~/.config/kilo/kilo.jsonc

检查当前文件，并在当前 Terminal 中记录后续要使用的配置路径：

mkdir -p "$HOME/.config/kilo" if [ -f "$HOME/.config/kilo/kilo.json" ] \ && [ -f "$HOME/.config/kilo/kilo.jsonc" ]; then echo '同时发现 kilo.json 和 kilo.jsonc，请先确认 Kilo 实际使用哪一份，不要继续配置。' unset KILO_CONFIG_FILE elif [ -f "$HOME/.config/kilo/kilo.jsonc" ]; then export KILO_CONFIG_FILE="$HOME/.config/kilo/kilo.jsonc" else export KILO_CONFIG_FILE="$HOME/.config/kilo/kilo.json" fi if [ -n "${KILO_CONFIG_FILE:-}" ]; then echo "本次使用的配置文件：$KILO_CONFIG_FILE" fi

如果两份文件都不存在，命令会把

KILO_CONFIG_FILE

~/.config/kilo/kilo.json

kilo.jsonc

同时存在

kilo.json

kilo.jsonc

kilo debug config

3.2 已有配置

如果你已经配置过其他 provider、模型、插件或权限，先备份刚才选定的文件：

if [ -z "${KILO_CONFIG_FILE:-}" ]; then echo '没有选定配置文件，请先完成第 3.1 节。' elif [ -f "$KILO_CONFIG_FILE" ]; then cp "$KILO_CONFIG_FILE" \ "$KILO_CONFIG_FILE.backup-$(date +%Y%m%d-%H%M%S)" echo "已备份 $KILO_CONFIG_FILE" else echo '尚无现有配置文件，将在下一步创建。' fi

已有配置时只新增或更新本文 provider，不要直接覆盖整个文件，也不要删除其他团队或项目设置。

3.3 第一次配置

如果配置文件尚不存在，创建空的 JSON 配置文件：

mkdir -p "$HOME/.config/kilo" if [ -z "${KILO_CONFIG_FILE:-}" ]; then echo '没有选定配置文件，请先完成第 3.1 节。' elif [ ! -e "$KILO_CONFIG_FILE" ]; then printf '%s\n' '{}' > "$KILO_CONFIG_FILE" chmod 600 "$KILO_CONFIG_FILE" echo "已创建 $KILO_CONFIG_FILE" else echo "配置文件已存在，不会覆盖：$KILO_CONFIG_FILE" fi

打开配置文件：

open -e "$KILO_CONFIG_FILE"

也可以使用 VS Code：

code "$KILO_CONFIG_FILE"

如果 code 命令不存在，使用 open -e 即可。

4. 在当前 Terminal 安全输入连接信息

4.1 临时加载 Base URL 和 API Key

在同一个 Terminal 中执行。文件已经存在时，命令会直接读取；文件不存在时，会在当前 Terminal 安全询问 API Key 并创建文件：

export RELAY_BASE_URL='https://cn-shanghai-alicloud-aimesh.api.clickzetta.com/gateway/v1' if [ ! -s "$HOME/.config/kilo/clickzetta-api-key" ]; then mkdir -p "$HOME/.config/kilo" read -s "RELAY_API_KEY?请粘贴 AI Gateway API Key，然后按回车：" echo (umask 077; printf '%s' "$RELAY_API_KEY" > "$HOME/.config/kilo/clickzetta-api-key") unset RELAY_API_KEY chmod 600 "$HOME/.config/kilo/clickzetta-api-key" fi export CLICKZETTA_API_KEY="$(< "$HOME/.config/kilo/clickzetta-api-key")"

检查变量是否存在，但不要输出令牌内容：

if [ -n "$CLICKZETTA_API_KEY" ]; then echo 'API Key 已载入当前 Terminal' else echo 'API Key 未载入，请重新执行第 4.2 节' fi

关闭 Terminal 后，export 的变量会消失；密钥文件不会消失。完成第 7 节前，请继续使用当前窗口。

4.2 手动重新创建密钥文件

如果需要更换或重新创建 API Key，执行：

mkdir -p "$HOME/.config/kilo" read -s "RELAY_API_KEY?请粘贴 AI Gateway API Key，然后按回车：" echo (umask 077; printf '%s' "$RELAY_API_KEY" > "$HOME/.config/kilo/clickzetta-api-key") unset RELAY_API_KEY chmod 600 "$HOME/.config/kilo/clickzetta-api-key"

粘贴 API Key 时屏幕不显示字符是正常现象。

确认文件存在和权限正确，但不要显示文件内容：

test -s "$HOME/.config/kilo/clickzetta-api-key" \ && echo 'API Key 文件已创建' \ || echo 'API Key 文件为空或不存在' ls -l "$HOME/.config/kilo/clickzetta-api-key"

权限应仅允许当前用户读取和写入，通常显示为：

-rw-------

4.3 Kilo 配置中的密钥引用

Kilo 全局配置使用以下引用读取密钥文件：

{file:~/.config/kilo/clickzetta-api-key}

不要把真实 API Key 替换进 JSON。{file:...} 只应放在 Kilo 的可信全局配置中，不要把它放进提交到 Git 的项目配置。

5. 检查网络并查询模型目录

5.1 先检查 OpenAI 风格连接

执行：

curl -sS -o /tmp/kilo-gateway-models-openai.json \ --max-time 30 \ -w 'HTTP %{http_code}\n' \ "$RELAY_BASE_URL/models" \ -H "Authorization: Bearer $CLICKZETTA_API_KEY" \ -H 'Content-Type: application/json'

返回含义：

如果已经收到 HTTP 200、401、403、404、429 或 5xx，说明域名通常能够访问，不应首先判断为“必须开 VPN”。只有域名解析失败、连接超时或网络策略拦截时，才需要检查代理或 VPN。

5.2 查看 OpenAI 视图

HTTP 200 后执行：

jq -r ' if (.data | type) == "array" then .data[].id else .error.message // .message // "没有读取到模型目录" end ' /tmp/kilo-gateway-models-openai.json

这个列表用于选择 OpenAI Chat 或 OpenAI Responses 的候选模型。列表只表示当前 API Key 可以看到这些模型，接下来仍要分别测试具体端点。

5.3 查看 Anthropic 视图

只有准备使用 Anthropic Messages 或 Claude 时才需要执行：

curl -sS -o /tmp/kilo-gateway-models-anthropic.json \ --max-time 30 \ -w 'HTTP %{http_code}\n' \ "$RELAY_BASE_URL/models" \ -H "x-api-key: $CLICKZETTA_API_KEY" \ -H 'anthropic-version: 2023-06-01' \ -H 'Content-Type: application/json' jq -r ' if (.data | type) == "array" then .data[].id else .error.message // .message // "没有读取到 Anthropic 模型目录" end ' /tmp/kilo-gateway-models-anthropic.json

如果 OpenAI 视图和 Anthropic 视图不同，这是正常现象。请求头和协议上下文不同，AI Gateway 可以返回不同的模型目录。

5.4 模型 ID 必须原样复制

不要：

• 根据网上的展示名称手写模型 ID；
• 删除模型 ID 中的厂商前缀；
• 把点号改成连字符；
• 因为同系列某个版本可用，就推断其他版本也可用；
• 把模型 ID 中的 / 当成需要删除的字符。

如果目标模型不在自己的目录中，先确认 API Key 权限，不要继续强行配置。

6. 用对应协议验证目标模型

只需测试自己准备使用的协议。每个测试都必须同时满足：HTTP 200，并且响应中有最终文字。

6.1 OpenAI Chat Completions

从第 5.2 节的结果中复制一个完整模型 ID：

read "CHAT_MODEL_ID?请粘贴准备使用 Chat 协议的完整模型 ID："

执行：

curl -sS -o /tmp/kilo-test-chat.json \ --max-time 60 \ -w 'HTTP %{http_code}\n' \ "$RELAY_BASE_URL/chat/completions" \ -H "Authorization: Bearer $CLICKZETTA_API_KEY" \ -H 'Content-Type: application/json' \ -d "$(jq -cn \ --arg model "$CHAT_MODEL_ID" \ '{ model: $model, max_tokens: 512, messages: [{role: "user", content: "请只回复：Chat连接成功"}], stream: false }')" jq -r ' .choices[0].message.content // .error.message // .message // "HTTP 已返回，但没有找到最终文字" ' /tmp/kilo-test-chat.json

成功时应看到：

HTTP 200 Chat连接成功

如果成功，可以使用第 7.2 节的 relay-chat 配置。

6.2 OpenAI Responses

从第 5.2 节的结果中复制一个完整模型 ID：

read "RESPONSES_MODEL_ID?请粘贴准备使用 Responses 协议的完整模型 ID："

执行：

curl -sS -o /tmp/kilo-test-responses.json \ --max-time 60 \ -w 'HTTP %{http_code}\n' \ "$RELAY_BASE_URL/responses" \ -H "Authorization: Bearer $CLICKZETTA_API_KEY" \ -H 'Content-Type: application/json' \ -d "$(jq -cn \ --arg model "$RESPONSES_MODEL_ID" \ '{ model: $model, input: "请只回复：Responses连接成功", max_output_tokens: 512, stream: false }')" jq -r ' ([.output[]?.content[]? | select(.type == "output_text" or .type == "text") | .text] | join("\n")) as $text | if ($text | length) > 0 then $text else .output_text // .error.message // .message // "HTTP 已返回，但没有找到最终文字" end ' /tmp/kilo-test-responses.json

成功时应看到：

HTTP 200 Responses连接成功

curl 成功只说明网关的非流式 Responses 请求可用。继续执行第 9 节的 Kilo 实际消息测试；只有

kilo run

text part SSE-Keep-Alive not found

6.3 Anthropic Messages

从第 5.3 节的结果中复制一个完整模型 ID：

read "ANTHROPIC_MODEL_ID?请粘贴准备使用 Anthropic 协议的完整模型 ID："

执行：

curl -sS -o /tmp/kilo-test-anthropic.json \ --max-time 60 \ -w 'HTTP %{http_code}\n' \ "$RELAY_BASE_URL/messages" \ -H "x-api-key: $CLICKZETTA_API_KEY" \ -H 'anthropic-version: 2023-06-01' \ -H 'Content-Type: application/json' \ -d "$(jq -cn \ --arg model "$ANTHROPIC_MODEL_ID" \ '{ model: $model, max_tokens: 1024, messages: [{role: "user", content: "请只回复：Anthropic连接成功"}], stream: false }')" jq -r ' ([.content[]? | select(.type == "text") | .text] | join("\n")) as $text | if ($text | length) > 0 then $text else .error.message // .message // "HTTP 已返回，但没有找到最终文字" end ' /tmp/kilo-test-anthropic.json

成功时应看到：

HTTP 200 Anthropic连接成功

如果成功，可以使用第 7.4 节的 relay-anthropic 配置。

6.4 HTTP 200 但没有最终文字

部分推理模型可能先生成 thinking 或 reasoning 内容。输出预算太小时，请求可能返回 HTTP 200，但没有最终文本。

可以把对应请求中的：

max_tokens: 512 max_output_tokens: 512

提高到 1024 或 4096 后再测试。最终值不能超过模型和 AI Gateway 的真实上限。

如果提高后仍没有最终文字，请查看完整 JSON，确认响应结构是否与当前协议一致。

7. 把通过测试的模型写入 Kilo

本节提供三个独立方案。请选择标准 curl 和准备执行的 Kilo 协议相匹配的一个方案完成首次配置，不要一次性复制三个方案。Responses 还必须满足第 6.2 节的额外兼容性要求。

{}

{}

provider

7.1 先备份配置

如果还没有备份，请执行：

if [ -z "${KILO_CONFIG_FILE:-}" ]; then echo '没有选定配置文件，请先完成第 3.1 节。' elif [ -f "$KILO_CONFIG_FILE" ]; then cp "$KILO_CONFIG_FILE" \ "$KILO_CONFIG_FILE.backup-$(date +%Y%m%d-%H%M%S)" echo '已创建 Kilo 配置备份' else echo '配置文件不存在，请先完成第 3.3 节。' fi

7.2 方案 A：配置 OpenAI Chat

只有第 6.1 节成功时才使用此方案。

配置文件当前只有

{}

relay-chat

provider

{ "$schema": "https://app.kilo.ai/config.json", "model": "relay-chat/YOUR_MODEL_ID", "provider": { "relay-chat": { "name": "AI Gateway - OpenAI Chat", "npm": "@ai-sdk/openai-compatible", "options": { "apiKey": "{file:~/.config/kilo/clickzetta-api-key}", "baseURL": "https://cn-shanghai-alicloud-aimesh.api.clickzetta.com/gateway/v1" }, "models": { "YOUR_MODEL_ID": { "name": "AI Gateway Model" } } } } }

把两处 YOUR_MODEL_ID 替换为第 6.1 节已经通过测试的完整模型 ID。

7.3 方案 B：配置 OpenAI Responses

只有第 6.2 节的 curl 成功时，才可以临时写入这个 provider 进行 Kilo 验证；只有第 9.2 节的 Kilo 实际消息测试也成功时，才可以保留并正式使用此方案。

由于首次

kilo run

SSE-Keep-Alive

{ "$schema": "https://app.kilo.ai/config.json", "model": "relay-responses/YOUR_MODEL_ID", "provider": { "relay-responses": { "name": "AI Gateway - OpenAI Responses", "npm": "@ai-sdk/openai", "options": { "apiKey": "{file:~/.config/kilo/clickzetta-api-key}", "baseURL": "https://cn-shanghai-alicloud-aimesh.api.clickzetta.com/gateway/v1" }, "models": { "YOUR_MODEL_ID": { "name": "AI Gateway Model" } } } } }

把两处 YOUR_MODEL_ID 替换为第 6.2 节已经通过测试的完整模型 ID。

7.4 方案 C：配置 Anthropic Messages

只有第 6.3 节成功时才使用此方案。

{ "$schema": "https://app.kilo.ai/config.json", "model": "relay-anthropic/YOUR_MODEL_ID", "provider": { "relay-anthropic": { "name": "AI Gateway - Anthropic Messages", "npm": "@ai-sdk/anthropic", "options": { "apiKey": "{file:~/.config/kilo/clickzetta-api-key}", "baseURL": "https://cn-shanghai-alicloud-aimesh.api.clickzetta.com/gateway/v1" }, "models": { "YOUR_MODEL_ID": { "name": "AI Gateway Model" } } } } }

把两处 YOUR_MODEL_ID 替换为第 6.3 节已经通过测试的完整模型 ID。

Claude 应优先使用此 provider。将 Claude 模型 ID 写进 relay-chat 并不会自动切换到 Anthropic Messages。

7.5 同时配置多个协议

如果多个协议已经分别通过标准 curl 和 Kilo 实际消息测试，可以把多个 provider 合并在同一个顶层 provider 对象中。每个 provider 必须保持独立：

relay-chat → @ai-sdk/openai-compatible → /chat/completions relay-responses → @ai-sdk/openai → /responses relay-anthropic → @ai-sdk/anthropic → /messages

已有配置时遵循：

1. 保留现有 $schema、其他 provider、插件、主题和项目设置；
2. 新 provider 添加到顶层 provider 对象内部；
3. 每个 provider 必须是对象，不能写成单个字符串；
4. 不要把三种协议的模型合并到同一个 provider；
5. 顶层 model 必须引用一个真实存在的 provider_id/model_id；
6. 保存后执行第 8 节的 JSON 和 Kilo 配置检查。

错误写法（仅用于识别错误，不要执行）：

{ "provider": { "relay-anthropic": "@ai-sdk/anthropic" } }

这会导致类似 expected object, received string 的配置校验错误。

7.6 正常结果

写入配置后，不要只看文件是否保存成功。必须继续执行第 8 节的配置与模型列表检查，以及第 9 节的实际消息测试。

本文没有给所有模型统一写入 tool_call、reasoning、attachment、modalities 或固定 token 上限。这些字段必须有对应模型或 AI Gateway 的明确说明；随意复制统一数值可能导致截断、参数错误或错误的功能展示。

8. 检查 Kilo 配置和模型列表

8.1 检查 JSON 和配置警告

执行：

if [[ "$KILO_CONFIG_FILE" == *.json ]]; then jq empty "$KILO_CONFIG_FILE" else echo '当前使用 JSONC，跳过 jq，由 Kilo 检查配置。' fi kilo config check

正常情况下，kilo config check 应返回：

No config warnings.

如果 jq 报语法错误，先检查逗号、引号、花括号和 provider 层级。JSONC 可能包含注释，不能直接用 jq 检查，因此以

kilo config check

8.2 查看刚配置的 provider

根据实际配置，只执行对应的一条或多条命令：

kilo models relay-chat kilo models relay-responses kilo models relay-anthropic

你应该看到类似结构：

relay-chat/<从目录复制的模型 ID> relay-responses/<从目录复制的模型 ID> relay-anthropic/<从目录复制的模型 ID>

尖括号中的文字只是说明，不要原样输入。kilo models 能看到模型，只说明本地 provider 和模型目录已加载，不代表远端调用一定成功。

8.3 查看有效配置（可选）

需要确认 Kilo 最终读取了哪个配置文件时，可以执行：

kilo debug config

输出可能包含 API Key 解析结果或其他敏感字段。只在本机查看，分享前必须删除或遮盖 API Key、Authorization、token、组织 ID 和账户信息。

9. 用 Kilo 发送第一条消息

9.1 测试默认模型

如果配置文件顶层的 model 已设置为通过测试的完整模型引用，执行：

kilo run '请只回复：Kilo连接成功'

正常最终文字：

Kilo连接成功

成功标准是命令最终返回模型文字，而不是仅仅看到配置检查通过或模型出现在列表中。

9.2 测试指定模型

如果要绕过默认模型，使用完整的 Kilo 模型引用：

kilo run \ --model 'relay-chat/YOUR_MODEL_ID' \ '请只回复：指定模型连接成功'

如果配置的是 Responses 或 Anthropic，把 --model 改为：

relay-responses/<模型 ID> relay-anthropic/<模型 ID>

模型 ID 中如果包含 /，完整引用包含多个 / 是正常的。不要只写模型 ID 而省略 provider ID。

9.3 用 JSON 事件排查完成原因

如果输出不完整或长时间重试，可以查看原始事件：

kilo run \ --model 'PROVIDER_ID/YOUR_MODEL_ID' \ --format json \ '请只回复：OK'

把 PROVIDER_ID 替换为 relay-chat、relay-responses 或 relay-anthropic，把模型占位符替换为真实模型 ID。

成功时应包含最终文本和正常结束事件。如果只有 thinking/reasoning 内容，请回到第 6.4 节检查输出预算。

9.4 在交互界面中使用

进入需要处理的项目目录：

cd /path/to/your/project kilo

在 Kilo TUI 中使用 /models 选择已经配置的完整模型引用。首次进行文件修改或命令执行时，请阅读权限提示，只批准你理解的操作。

9.5 使用 Kilo Code for VS Code

如果已经在 CLI 中完成验证，可以在 VS Code 中配置：

1. 打开 Kilo Code 面板；
2. 点击 Settings；
3. 进入 Providers；
4. 滚动到 provider 列表底部；
5. 点击 Custom provider。

字段对应关系：

填写后点击 Submit，然后在模型选择器中选择模型。界面自动获取不到模型时，按照第 5 节手动复制模型 ID，再确认 Provider API 与标准 curl 使用的协议一致。

VS Code 扩展的菜单名称和字段位置可能随版本变化。CLI 的

kilo config check

kilo run

10. 添加第二种协议或更多模型

10.1 添加第二种协议

例如已经配置 relay-chat，现在还要使用 Claude：

1. 执行第 5.3 节查询 Anthropic 目录；
2. 执行第 6.3 节测试目标模型；
3. 执行第 7.4 节添加 relay-anthropic；
4. 执行第 8 节检查配置和模型列表；
5. 使用 --model relay-anthropic/<模型 ID> 发送测试消息。

添加第二个 provider 不需要重新安装 Kilo，也不需要删除第一个 provider。

10.2 向已有 provider 添加模型

先用第 6 节的对应协议测试新模型。成功后，在目标 provider 的 models 对象中新增一项：

{ "models": { "vendor/existing-model": { "name": "Existing Model" }, "vendor/new-model": { "name": "New Model" } } }

新增后执行：

if [[ "$KILO_CONFIG_FILE" == *.json ]]; then jq empty "$KILO_CONFIG_FILE" fi kilo config check kilo models PROVIDER_ID kilo run --model 'PROVIDER_ID/vendor/new-model' '请只回复：新模型连接成功'

把 PROVIDER_ID 和模型 ID 替换为实际值。

如果要让新模型成为默认模型，把配置文件顶层的 model 改为新的完整模型引用；也可以只在命令中使用 --model，不改变默认值。

10.3 同一个模型添加到多个协议

如果同一个模型分别通过 Chat 和 Anthropic Messages 测试，可以在两个 provider 中各添加一次：

relay-chat/<同一个模型 ID> relay-anthropic/<同一个模型 ID>

这是两个不同的 Kilo 模型引用。它们使用不同请求格式，错误、响应字段和工具调用表现也可能不同。

11. 请求协议和配置边界

11.1 三种协议不能混用

只修改 URL 或模型名称，不能把一种协议变成另一种协议。端点、认证头、请求体、流式事件和工具调用结构必须一起匹配。

11.2 模型 ID 前缀不会切换协议

假设模型 ID 以 anthropic/ 开头：

relay-chat/anthropic/<模型名称>

仍然会使用 OpenAI Chat，因为本地 provider 是 relay-chat。

只有：

relay-anthropic/anthropic/<模型名称>

才会按本文配置使用 Anthropic Messages。

同理，openai/、deepseek/、qwen/ 或其他前缀都只是 AI Gateway 模型 ID 的一部分。

11.3 Kilo 不会自动协议回退

一次 Kilo 调用只使用完整模型引用中指定的 provider。Chat 失败不会自动改用 Responses，Responses 失败也不会自动改用 Anthropic。

需要备用协议时，必须分别创建 provider、分别测试，并在使用时明确切换 provider ID 和模型 ID。

11.4 同一个模型可能支持多个协议

如果同一个模型分别通过 Chat 和 Anthropic Messages 测试，可以在两个 provider 中各添加一次。这不表示两个引用完全等价；它们可能有不同的参数、响应事件、工具调用和计费表现。

11.5 目录、curl 和 Kilo 分别说明什么

11.6 不要猜上下文窗口和输出上限

Kilo 自定义模型可以配置 limit.context、limit.output、tool_call、reasoning、attachment 和 modalities，但这些不是所有模型通用的固定值。

本文最小 provider 配置只写入模型名称。只有在 AI Gateway 或模型文档明确提供数值，并且经过实际验证后，才应增加其他字段。

12. 配置完成后可以使用哪些能力

完成第 9 节只表示基础文本链路已经成功：你可以向 Kilo 发送文字，并收到模型的最终文字回复。它不自动证明 Kilo 的 Agent 工具、文件修改或命令执行能力已经可用。

以下能力是否可用，还取决于模型、请求协议、AI Gateway 和 Kilo provider 的共同实现：

• 流式输出和中途取消；
• 工具调用以及多轮工具结果回传；
• 文件编辑、命令执行和其他 agent 工具；
• JSON Schema 或结构化输出；
• 图片、PDF、音频和其他多模态输入；
• Prompt Cache 或其他缓存能力；
• Extended Thinking、reasoning effort 或其他推理参数；
• 超长上下文和自动压缩；
• 并发、限流、超时和重试；
• 自动故障转移和 fallback 模型。

如果你只需要普通文本对话，第 9 节成功后即可开始使用。如果需要上述能力，请对准备使用的模型和协议分别进行专项测试。

不要仅因为模型在原生厂商 API 中支持某项能力，就直接在 Kilo 配置中声明该能力。协议转换可能改变字段、事件或限制。

12.1 可选：执行只读 Agent 冒烟测试

如果准备让 Kilo 读取项目文件，可以先在临时目录中验证只读工具能力。把

PROVIDER_ID/YOUR_MODEL_ID

KILO_SMOKE_DIR="$(mktemp -d)" printf '%s\n' 'KILO_AGENT_SMOKE_20260819' \ > "$KILO_SMOKE_DIR/kilo-agent-smoke.txt" kilo run \ --dir "$KILO_SMOKE_DIR" \ --model 'PROVIDER_ID/YOUR_MODEL_ID' \ --format json \ '请读取 kilo-agent-smoke.txt，只回复文件中的完整内容，不要修改任何文件。'

成功时，最终文字应包含：

KILO_AGENT_SMOKE_20260819

同时检查 JSON 事件中是否存在文件读取工具调用。如果模型没有调用工具，而是猜测或直接复述提示词，不能把本次结果视为工具能力验证成功。

测试完成后，可以先删除本文创建的测试文件，再删除已经变空的临时目录：

if [ -f "$KILO_SMOKE_DIR/kilo-agent-smoke.txt" ]; then rm -- "$KILO_SMOKE_DIR/kilo-agent-smoke.txt" rmdir -- "$KILO_SMOKE_DIR" unset KILO_SMOKE_DIR else echo '没有找到本文创建的测试文件，未执行删除。' fi

本文不会自动使用

--auto

12.2 能力结论怎么写

判断能力是否可用时，请使用与实际测试相匹配的结论：

kilo run

13. 常见问题排查

13.1 API Key 粘贴时没有字符

正常。read -s 会隐藏输入内容。粘贴后按回车即可。

13.2 kilo: command not found

原因通常是 Kilo 未安装，或者 npm 全局 bin 不在 PATH。

执行：

npm install -g @kilocode/cli npm prefix -g echo "$PATH" kilo --version

13.3 expected object, received string

这通常表示把 provider 写成了字符串。例如：

{ "provider": { "relay-anthropic": "@ai-sdk/anthropic" } }

provider 必须是对象，并且至少包含正确的 npm、options 和 models。请恢复备份后，使用第 7 节的完整对象结构重新合并。

13.4 模型不在 kilo models 中

按顺序检查：

1. 当前编辑的是 Kilo 实际使用的全局配置文件；
2. provider ID 与 kilo models PROVIDER_ID 一致；
3. 模型 ID 写在目标 provider 的 models 对象内部；
4. 顶层 model 或命令中的 --model 使用完整引用；
5. jq empty 和 kilo config check 均通过；
6. 没有同时维护冲突的 kilo.json 与 kilo.jsonc。

13.5 HTTP 401 或 403

常见原因：

• API Key 错误、失效或没有权限；
• OpenAI 请求错误地使用了 x-api-key；
• Anthropic 请求遗漏 x-api-key 或 anthropic-version；
• Base URL 和 API Key 不属于同一个环境；
• VS Code 界面没有填入 API Key，而 CLI 使用的是本地文件。

先回到第 5 节重新检查认证头和目录请求。

13.6 No upstream candidates

表示当前“模型 ID + 协议 + API Key/租户”组合没有可用上游。常见原因：

• 模型 ID 写错；
• provider 使用了错误协议；
• API Key 没有对应模型权限；
• AI Gateway 没有为该协议配置模型路由；
• 上游暂时下线。

处理顺序：重新查询对应目录，原样复制模型 ID，再用第 6 节的同协议 curl 测试。不要先把它判断成 Kilo 安装问题。

13.7 HTTP 404、502 或 503

HTTP 404 通常表示 Base URL、/v1 或具体端点写错；HTTP 502/503 通常表示请求已经到达 AI Gateway，但上游模型调用失败。

保存以下脱敏信息：

• 发生时间和时区；
• 完整模型 ID；
• 请求协议和路径；
• HTTP 状态码；
• 删除 API Key 后的错误 JSON。

不要通过修改 Kilo provider 名称来解决上游 5xx。

13.8 HTTP 200 但没有最终文字

提高输出预算，并检查当前协议的正确文本字段：

Chat → choices[].message.content Responses → output[].content[].text 或 output_text Anthropic → content[] 中 type=text

如果 JSON 中只有 thinking 或 reasoning 内容，说明输出预算可能被推理过程占满。回到第 6.4 节逐步提高预算。

13.9 Claude 访问失败

首先确认完整引用使用了 Anthropic provider：

relay-anthropic/完整模型 ID

下面的写法会走 Chat Completions，不会因为模型 ID 中有 anthropic 就自动切换：

relay-chat/anthropic/your-model-id

继续检查：

1. Anthropic 目录是否能看到模型；
2. /messages 标准请求是否成功；
3. Kilo runtime 是否为 @ai-sdk/anthropic；
4. Base URL 是否只到 /v1；
5. 模型 ID 是否完整保留厂商前缀。

13.10 OpenAI 模型访问失败

不要把 Chat Completions 和 Responses 当成同一个协议：

• /chat/completions 成功时，使用 relay-chat；
• /responses 成功后，仍要执行 relay-responses 的

  kilo run

  kilo run
  测试；
• 两个端点和对应的 Kilo 测试都成功时，可以分别保留两个 provider；
• 只有一个协议通过 Kilo 实际消息测试时，只使用对应 provider。

当前示例网关在 Kilo Code CLI 7.4.22 中可能出现 Responses 流式事件兼容问题。遇到

SSE-Keep-Alive

/responses

13.11 DeepSeek 或 Qwen 在一个协议成功、另一个失败

这是兼容路由差异，不一定是模型 ID 前缀错误。保留成功协议对应的 provider，删除或停用失败协议的配置。

Kilo 不会在 Chat、Responses 和 Anthropic 之间自动回退。

13.12 CLI 成功，但 VS Code 失败

依次检查：

• VS Code 中的 Kilo Code 是否为当前推荐版本；
• VS Code 是否加载了同一用户的全局 Kilo 配置；
• 界面中的 Base URL 是否重复追加端点；
• Provider API 是否与 CLI provider 一致；
• VS Code 是否需要重新加载窗口；
• CLI 使用的是密钥文件，而界面中是否漏填 API Key；
• VS Code Output 面板中的 Kilo Code 日志是否有明确错误。

13.13 Responses 返回 text part SSE-Keep-Alive not found

如果

/responses

kilo run

text part SSE-Keep-Alive not found

说明 API Key、Base URL 和非流式 Responses 路由通常已经接通，但网关返回的流式事件与当前 Kilo

@ai-sdk/openai

按以下顺序处理：

1. 不要把 relay-responses 设置为默认模型；
2. 改用已经通过第 9 节验证的 relay-chat；
3. 保留脱敏后的错误文字、Kilo 版本、发生时间、模型 ID 和协议路径；
4. 网关或 Kilo 升级后，重新执行第 6.2 节和第 9.2 节；
5. 只有

   kilo run

   kilo run
   返回最终文字并正常结束后，才把 Responses 标记为 Kilo 可用。

13.14 kilo config check 失败

先执行：

if [[ "$KILO_CONFIG_FILE" == *.json ]]; then jq empty "$KILO_CONFIG_FILE" fi kilo config check

常见原因：

• JSON 缺少逗号、引号或花括号；
• provider 被写成字符串；
• models 写到了 provider 外层；
• npm runtime 名称错误；
• {file:...} 文件不存在或路径错误；
• 同时存在冲突的 kilo.json 和 kilo.jsonc。

13.15 恢复配置备份

查看备份：

find "$HOME/.config/kilo" -maxdepth 1 -type f \ \( -name 'kilo.json.backup-*' -o -name 'kilo.jsonc.backup-*' \) -print \ | sort -r \ | sed -n '1,5p'

复制准确的备份文件路径，然后执行：

read "KILO_BACKUP_FILE?请粘贴要恢复的完整备份文件路径：" if [ -f "$KILO_BACKUP_FILE" ] \ && [[ "$KILO_BACKUP_FILE" == "$HOME/.config/kilo/"*.backup-* ]]; then cp "$KILO_BACKUP_FILE" "$KILO_CONFIG_FILE" echo "已恢复到 $KILO_CONFIG_FILE" else echo '备份文件不存在或路径不符合预期，未执行恢复。' fi unset KILO_BACKUP_FILE if [[ "$KILO_CONFIG_FILE" == *.json ]]; then jq empty "$KILO_CONFIG_FILE" fi kilo config check

恢复目标始终使用第 3.1 节选定的

$KILO_CONFIG_FILE

kilo config check

14. API Key 和本机安全

Kilo 全局配置文件通常是以下一份：

~/.config/kilo/kilo.json ~/.config/kilo/kilo.jsonc

实际操作对象以第 3.1 节选定的

$KILO_CONFIG_FILE

本文的 provider 配置使用文件引用，API Key 保存在：

~/.config/kilo/clickzetta-api-key

请同时限制配置文件、密钥文件和历史备份的权限：

chmod 600 "$HOME/.config/kilo/clickzetta-api-key" chmod 600 "$KILO_CONFIG_FILE" 2>/dev/null || true find "$HOME/.config/kilo" -maxdepth 1 -type f \ \( -name 'kilo.json.backup-*' -o -name 'kilo.jsonc.backup-*' \) \ -exec chmod 600 {} \;

不要：

• 上传 kilo.json 或密钥文件；
• 对完整配置截图；
• 执行 echo "$CLICKZETTA_API_KEY"；
• 把完整请求头粘贴到公开工单；
• 把 API Key 写入项目仓库；
• 在项目级配置中保存真实令牌；
• 与他人共用长期有效的高权限 API Key。

配置完成后，可以清除当前 Terminal 中的临时变量：

unset CLICKZETTA_API_KEY unset RELAY_BASE_URL unset CHAT_MODEL_ID unset RESPONSES_MODEL_ID unset ANTHROPIC_MODEL_ID unset KILO_CONFIG_FILE

如果 API Key 已经出现在公开截图、聊天或命令输出中，请立即在 AI Gateway 后台撤销并重新创建。

Kilo 的工具能力可以读取文件、修改代码和运行命令。启用自动执行或放宽权限前，请确认项目目录、沙箱和权限设置，不要把模型连接成功等同于可以开放所有本机权限。

15. 完成检查清单

完成配置后逐项确认：

[ ] curl、jq、node、npm 可以执行 [ ] kilo --version 返回版本 [ ] kilo debug paths 能找到 Kilo 配置目录 [ ] KILO_CONFIG_FILE 指向本次实际编辑的配置文件 [ ] 没有同时维护冲突的 kilo.json 和 kilo.jsonc [ ] 已备份现有 Kilo 配置 [ ] Base URL 正确，/v1 没有重复 [ ] API Key 已安全保存，没有公开 [ ] 已查询目标协议对应的模型目录 [ ] 模型 ID 从自己的目录原样复制 [ ] 目标协议 curl 返回 HTTP 200 [ ] curl 响应中存在最终文字 [ ] Kilo provider 的 npm runtime 与 curl 协议一致 [ ] provider 是对象，不是字符串 [ ] 配置文件中没有 YOUR_ 或实际占位符 [ ] 使用 JSON 时 jq empty 检查通过；使用 JSONC 时已跳过 jq [ ] kilo config check 返回 No config warnings [ ] kilo models 能看到完整 provider/model 引用 [ ] kilo run 返回最终文字并正常结束 [ ] 需要第二种协议时已单独测试并单独配置 [ ] 工具、推理、流式和多模态能力按需单独验证 [ ] 如果自行配置 limit.context 或 limit.output，数值来自真实模型规格 [ ] 配置文件、密钥文件和备份文件权限已经限制

完成到

kilo run

如果 /models 成功但 curl 失败，从协议和上游路由开始排查；如果 curl 成功但 Kilo 失败，从 provider runtime、完整模型引用、配置路径和版本开始排查。

16. 相关资料

• Kilo Code Custom Models
• Kilo Code CLI
• Kilo Code CLI Command Reference
• Kilo Code Installation

Kilo 和 AI Gateway 都可能升级。遇到命令参数或界面字段差异时，先执行：

kilo --version kilo config --help kilo models --help kilo run --help

以当前安装版本显示的参数为准；协议选择、模型 ID 原样复制、标准 curl 验证和 Kilo 实际消息验证这条主流程保持不变。