> ## Documentation Index
> Fetch the complete documentation index at: https://evolink.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Kilo Code CLI

> 在命令行中配置 Kilo Code CLI，通过 EvoLink 使用 Claude 模型

## 概述

Kilo Code CLI 是 Kilo Code 的终端版本。它与 VS Code 扩展使用同一套 Agent Runtime 和 `kilo.jsonc` 配置，但所有安装、模型切换、任务执行和排错都在命令行中完成。

本教程会完成以下操作：

* 安装并启动 `kilo` 命令。
* 通过 OpenAI Compatible 协议连接 EvoLink。
* 配置 Claude 模型的工具调用、上下文窗口和输出预算。
* 在终端中验证文件读取与 Agent 工具是否正常。

<Card title="希望在 VS Code 中操作？" icon="code" href="/docs/cn/integration-guide/kilo-code-vscode">
  请改用独立的 Kilo Code VS Code 教程。
</Card>

## 使用前准备

### 1. 安装 Kilo Code CLI

<Tabs>
  <Tab title="npm（全平台）">
    需要先安装 Node.js 和 npm。

    ```bash theme={null}
    npm install -g @kilocode/cli
    ```
  </Tab>

  <Tab title="安装脚本（macOS / Linux）">
    也可在 Windows 的 Git Bash 中运行。

    ```bash theme={null}
    curl -fsSL https://kilo.ai/cli/install | bash
    ```
  </Tab>

  <Tab title="Homebrew（macOS / Linux）">
    ```bash theme={null}
    brew install Kilo-Org/tap/kilo
    ```
  </Tab>
</Tabs>

安装完成后确认命令可用：

```bash theme={null}
kilo --version
kilo --help
```

<Note>
  本教程已使用 Kilo CLI `7.4.15` 验证。已经安装旧版本时，可以运行 `kilo upgrade` 更新；若界面或命令与本文明显不同，请先用 `kilo --version` 确认版本。
</Note>

### 2. 获取 EvoLink API Key

1. 登录 [EvoLink 控制台](https://evolink.ai/dashboard)。
2. 进入 API Keys 页面并创建 Key。
3. 复制生成的裸 Key，并妥善保存。

API Key 通常以 `sk-` 开头。下面使用环境变量保存 Key，避免把密钥写进配置文件或提交到 Git。

<Tabs>
  <Tab title="macOS / Linux">
    ```bash theme={null}
    export EVOLINK_API_KEY="你的EvoLink_API_Key"
    ```
  </Tab>

  <Tab title="Windows PowerShell">
    ```powershell theme={null}
    $env:EVOLINK_API_KEY="你的EvoLink_API_Key"
    ```
  </Tab>
</Tabs>

<Warning>
  环境变量中只填写裸 Key，不要添加 `Bearer ` 前缀。Kilo 的 OpenAI Compatible Provider 会自动生成 `Authorization: Bearer ...` 请求头。

  上面的命令只对**当前终端会话**生效。后续的配置检查和实际调用必须在同一个终端中完成；关闭终端后，需要重新设置环境变量，或按你的操作系统方式安全地持久化它。
</Warning>

## 第一步：创建 Kilo 配置文件

Kilo 通过 `kilo.jsonc` 配置文件定义 Provider 与模型。本教程使用受信任的**全局配置文件**：

* macOS / Linux：`~/.config/kilo/kilo.jsonc`
* Windows：`C:\Users\<用户名>\.config\kilo\kilo.jsonc`

<Note>
  `~` 代表你的**用户主目录**（macOS 上是 `/Users/你的用户名`，Linux 上是 `/home/你的用户名`）。`.config` 以点开头，是**隐藏文件夹**，在访达（Finder）/文件资源管理器里默认看不到——所以用下面的命令行方式创建最省事，整段复制粘贴即可。
</Note>

<Warning>
  Kilo Code 只在**受信配置**中解析 `{env:EVOLINK_API_KEY}` 这类环境变量引用——即全局配置（`~/.config/kilo/`）、通过 `KILO_CONFIG` 指定的配置或组织托管配置；项目根目录的 `kilo.jsonc` 或 `.kilo/kilo.jsonc` 中的 `{env:}` 引用**不会被解析**（防止仓库内配置窃取凭证）。因为本教程需要读取环境变量中的密钥，下面的 Provider 必须写入上述**全局配置**；项目级配置只适合放默认模型等不含密钥引用的覆盖项。
</Warning>

按下面三步操作：

<Steps>
  <Step title="打开终端">
    * **macOS**：按 `Command + 空格` 打开聚焦搜索，输入 `Terminal`（终端）回车。
    * **Windows**：在开始菜单搜索 `PowerShell`，点击打开。
    * **Linux**：按 `Ctrl + Alt + T`，或在应用菜单中搜索「终端」。
  </Step>

  <Step title="一条命令写入全局配置">
    把下面**整段命令**复制后粘贴到终端，回车执行。它会自动创建 `~/.config/kilo` 目录，并把完整配置一次性写入 `kilo.jsonc`——**不需要打开任何编辑器**：

    <Tabs>
      <Tab title="macOS / Linux">
        ```bash theme={null}
        mkdir -p ~/.config/kilo && cat > ~/.config/kilo/kilo.jsonc <<'EOF'
        {
          "$schema": "https://app.kilo.ai/config.json",
          "model": "evolink/claude-sonnet-5",
          "provider": {
            "evolink": {
              "npm": "@ai-sdk/openai-compatible",
              "options": {
                "apiKey": "{env:EVOLINK_API_KEY}",
                "baseURL": "https://direct.evolink.ai/v1"
              },
              "models": {
                "claude-fable-5": {
                  "name": "Claude Fable 5",
                  "tool_call": true,
                  "reasoning": true,
                  "limit": {
                    "context": 1000000,
                    "output": 32000
                  }
                },
                "claude-sonnet-5": {
                  "name": "Claude Sonnet 5",
                  "tool_call": true,
                  "reasoning": true,
                  "limit": {
                    "context": 1000000,
                    "output": 32000
                  }
                },
                "claude-haiku-4-5-20251001": {
                  "name": "Claude Haiku 4.5",
                  "tool_call": true,
                  "reasoning": true,
                  "limit": {
                    "context": 200000,
                    "output": 32000
                  }
                },
                "claude-opus-4-8": {
                  "name": "Claude Opus 4.8",
                  "tool_call": true,
                  "reasoning": true,
                  "limit": {
                    "context": 1000000,
                    "output": 32000
                  }
                }
              }
            }
          }
        }
        EOF
        ```

        说明：`<<'EOF'` 到结尾 `EOF` 之间的内容会被**原样写入**文件（`'EOF'` 带引号可确保 `$schema` 等字符不被 shell 展开）。文件已存在时会被**整体覆盖**；如果你之前配置过其他 Provider，请改用编辑器手动合并，不要直接执行这条命令。
      </Tab>

      <Tab title="Windows PowerShell">
        ```powershell theme={null}
        New-Item -ItemType Directory -Force -Path "$HOME\.config\kilo" | Out-Null
        @'
        {
          "$schema": "https://app.kilo.ai/config.json",
          "model": "evolink/claude-sonnet-5",
          "provider": {
            "evolink": {
              "npm": "@ai-sdk/openai-compatible",
              "options": {
                "apiKey": "{env:EVOLINK_API_KEY}",
                "baseURL": "https://direct.evolink.ai/v1"
              },
              "models": {
                "claude-fable-5": {
                  "name": "Claude Fable 5",
                  "tool_call": true,
                  "reasoning": true,
                  "limit": {
                    "context": 1000000,
                    "output": 32000
                  }
                },
                "claude-sonnet-5": {
                  "name": "Claude Sonnet 5",
                  "tool_call": true,
                  "reasoning": true,
                  "limit": {
                    "context": 1000000,
                    "output": 32000
                  }
                },
                "claude-haiku-4-5-20251001": {
                  "name": "Claude Haiku 4.5",
                  "tool_call": true,
                  "reasoning": true,
                  "limit": {
                    "context": 200000,
                    "output": 32000
                  }
                },
                "claude-opus-4-8": {
                  "name": "Claude Opus 4.8",
                  "tool_call": true,
                  "reasoning": true,
                  "limit": {
                    "context": 1000000,
                    "output": 32000
                  }
                }
              }
            }
          }
        }
        '@ | Set-Content -Path "$HOME\.config\kilo\kilo.jsonc" -Encoding utf8
        ```

        说明：`@'` 与 `'@` 之间的内容会被**原样写入**（单引号 here-string 不做变量展开）；结尾的 `'@` 必须**顶格单独成行**。文件已存在时会被**整体覆盖**；如果你之前配置过其他 Provider，请改用编辑器手动合并。
      </Tab>
    </Tabs>
  </Step>

  <Step title="确认写入成功">
    执行下面的命令查看文件开头几行：

    <Tabs>
      <Tab title="macOS / Linux">
        ```bash theme={null}
        head -5 ~/.config/kilo/kilo.jsonc
        ```
      </Tab>

      <Tab title="Windows PowerShell">
        ```powershell theme={null}
        Get-Content "$HOME\.config\kilo\kilo.jsonc" -Head 5
        ```
      </Tab>
    </Tabs>

    能看到以 `"$schema": "https://app.kilo.ai/config.json"` 开头的内容，就说明写入成功。
  </Step>
</Steps>

<Note>
  更习惯图形界面的话，也可以用任意文本编辑器（VS Code、记事本等）打开上述路径，把命令中 `EOF`（或 `@'`/`'@`）之间的配置内容粘贴进去保存，效果相同。
</Note>

### 关键字段

| 字段                | 作用                               |
| ----------------- | -------------------------------- |
| `npm`             | 指定 OpenAI Chat Completions 兼容协议  |
| `options.apiKey`  | 从 `EVOLINK_API_KEY` 环境变量读取密钥     |
| `options.baseURL` | EvoLink OpenAI 兼容接口根地址，只填到 `/v1` |
| `model`           | 默认模型，格式必须为 `providerID/modelID`  |
| `tool_call`       | 声明模型具备工具调用能力                     |
| `limit.context`   | 用于会话压缩和上下文管理                     |
| `limit.output`    | 单次输出预算；Kilo 默认最高使用 32K           |

<Warning>
  `baseURL` 必须填写 `https://direct.evolink.ai/v1`，不要追加 `/chat/completions`。模型配置必须放在 `provider.evolink.models` 下，不能把 `limit` 写到顶层。
</Warning>

`tool_call: true` 不会自动授予读取文件、修改文件或执行命令的权限。实际使用时，Kilo 仍可能根据权限设置要求你批准某次工具调用。

## 第二步：检查配置和模型

先检查 JSONC 结构：

```bash theme={null}
kilo config check
```

然后查看 Kilo 实际解析到的 EvoLink 模型：

```bash theme={null}
kilo models evolink --verbose
```

成功时应看到 `evolink/claude-sonnet-5` 等模型，以及对应的上下文和输出限制。

<Note>
  `kilo config check` 只检查配置结构，`kilo models evolink --verbose` 只确认 Kilo 已加载模型配置。它们不会发起实际聊天请求，因此不能验证网络连接、API Key 或 EvoLink 鉴权；下一步的文件读取任务才是端到端测试。
</Note>

如果刚修改过配置但当前 Kilo 会话没有更新，可以退出后重新运行 `kilo`，或在交互界面执行：

```text theme={null}
/reload
```

## 第三步：启动终端 Agent

进入需要操作的项目目录，先创建一个结果确定的测试文件，然后启动 Kilo：

```bash theme={null}
cd /你的/项目目录
printf '%s\n' 'EvoLink Kilo test' > kilo-evolink-test.txt
kilo
```

Windows PowerShell 使用：

```powershell theme={null}
Set-Location "C:\你的\项目目录"
Set-Content -Path "kilo-evolink-test.txt" -Value "EvoLink Kilo test"
kilo
```

在交互界面输入 `/models`，确认当前模型为 `evolink/claude-sonnet-5`。如果 `model` 已经写入配置，它会成为默认选择。

发送一个只读验证任务：

```text theme={null}
请读取当前项目根目录的 kilo-evolink-test.txt，并原样返回文件内容；不要修改任何文件。
```

配置成功时应同时满足：

* Kilo 调用了文件读取工具，而不是只返回普通聊天文本。
* 返回内容为 `EvoLink Kilo test`。
* 没有出现 `401`、`404`、`model_not_found` 或工具调用不支持错误。

首次读取文件时可能出现权限确认。批准本次只读工具调用后继续即可。

## 第四步：常用 CLI 工作流

### 交互式工作

```bash theme={null}
kilo
```

常用斜杠命令：

| 命令         | 用途                         |
| ---------- | -------------------------- |
| `/models`  | 切换模型                       |
| `/agents`  | 切换 Code、Plan、Debug 等 Agent |
| `/status`  | 查看当前会话状态                   |
| `/review`  | 审查当前代码改动                   |
| `/compact` | 压缩长会话                      |
| `/reload`  | 重新加载配置、Skills 和 Agents     |
| `/exit`    | 退出 Kilo                    |

### 单次执行任务

不进入完整 TUI，也可以直接执行任务：

```bash theme={null}
kilo run -m evolink/claude-sonnet-5 "检查当前项目的测试失败原因，不要修改文件"
```

### 临时指定不同模型

```bash theme={null}
kilo -m evolink/claude-fable-5
kilo run -m evolink/claude-haiku-4-5-20251001 "总结当前目录结构"
```

建议分工：

| Agent / 场景   | 推荐模型                                |
| ------------ | ----------------------------------- |
| Plan、复杂规划    | `evolink/claude-fable-5`            |
| Code、日常实现    | `evolink/claude-sonnet-5`           |
| Explore、轻量检索 | `evolink/claude-haiku-4-5-20251001` |
| 高难度编码        | `evolink/claude-opus-4-8`           |

## 排错

### `kilo: command not found`

确认全局 npm 可执行目录已加入 `PATH`，然后重新打开终端。也可以重新执行安装命令，并用 `npm prefix -g` 查看全局安装位置。

### `kilo config check` 报错

常见原因：

* JSONC 大括号或逗号位置错误。
* `provider`、`models` 或 `options` 层级写错。
* `model` 没有使用 `evolink/模型ID` 格式。

### `401 unauthorized`

检查当前终端是否真的设置了环境变量：

<Tabs>
  <Tab title="macOS / Linux">
    ```bash theme={null}
    test -n "$EVOLINK_API_KEY" && echo "EVOLINK_API_KEY is set"
    ```
  </Tab>

  <Tab title="Windows PowerShell">
    ```powershell theme={null}
    if ($env:EVOLINK_API_KEY) { "EVOLINK_API_KEY is set" }
    ```
  </Tab>
</Tabs>

不要把完整 Key 输出到终端截图或日志中。确认 Key 是裸值，不带 `Bearer ` 前缀。

### `404 not found`

先把 `baseURL` 恢复为本教程已验证的地址：

```text theme={null}
https://direct.evolink.ai/v1
```

再检查模型 ID 和 Provider 配置。Kilo 支持某些供应商使用完整端点 URL，因此不要把所有 `404` 都归因于路径重复；EvoLink 按本教程使用 `/v1` 即可。

### `model_not_found`

模型 ID 必须与 EvoLink 返回的 ID 完全一致。可以重新运行：

```bash theme={null}
kilo models evolink --verbose
```

不要自行添加 `anthropic/` 前缀或删除模型日期后缀。

### 可以聊天，但不会读取或修改文件

确认模型配置包含：

```jsonc theme={null}
{
  "tool_call": true
}
```

然后使用本页的只读任务重新验证。弱模型也可能无法稳定完成复杂工具调用，此时切换到 `claude-sonnet-5` 或 `claude-fable-5`。

### 长会话突然上下文超限

检查 `provider.evolink.models.<模型ID>.limit.context` 是否存在且不为 `0`。自定义模型缺少上下文窗口时，Kilo 无法正常触发会话压缩。

## 参考资料

* [Kilo Code CLI 官方文档](https://kilo.ai/docs/code-with-ai/platforms/cli)
* [Kilo Code OpenAI Compatible 配置](https://kilo.ai/docs/ai-providers/openai-compatible)
* [Kilo Code Custom Models](https://kilo.ai/docs/code-with-ai/agents/custom-models)
* [EvoLink Claude Messages API](/docs/cn/api-manual/language-series/claude/claude-messages-api)