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

# Kilo Code

Kilo Code 是运行在 VS Code、Cursor 等编辑器中的编码 Agent，可连接不同模型提供方，执行代码修改、调试和终端任务。通过 Step Plan Provider，可在编辑器内使用 Step 模型。

## 接入条件

* 已安装 VS Code 或 Cursor。运行下方 Python 验证示例时，还需安装 Python 3。
* [Step Plan 订阅](https://platform.stepfun.com/step-plan)有效、额度可用，且具备所用模型的调用权限。
* 已在 [StepFun 开放平台密钥管理](https://platform.stepfun.com/interface-key)页面创建 API Key。

## 安装 Kilo Code

在编辑器扩展市场中搜索并安装 Kilo Code，扩展标识为 `kilocode.kilo-code`。以下步骤使用包含 `Providers` 和 `Models` 设置页的版本。

## 配置 Step Plan

### 连接内置 Provider

1. 打开 Kilo Code 设置，进入 `Providers`，选择 `StepFun Step Plan (China)`。
2. 填写 API Key，点击 `Submit` 保存。API Key 字段不添加 `Bearer ` 前缀或首尾空格。
3. 在 `Settings > Models > Default Model` 中，选择该 Provider 下的 Step 5 Preview，模型 ID 为 `step-5-preview`。
4. 保存后新建任务。使用内置 Provider 时，保留其模型预设参数。

### 使用自定义 Provider

如果当前版本没有 Step Plan 预设，或预设列表中没有目标模型，可通过 `Providers > Custom provider` 手动配置：

| 配置项 | 填写值 |
| - | - |
| `Provider ID` | `step-plan`。 |
| `Display name` | `Step Plan`。 |
| `Provider API` | `OpenAI Compatible`。 |
| `Base URL` | `https://api.stepfun.com/step_plan/v1`。 |
| `API key` | Step API Key，不包含 `Bearer ` 前缀。 |
| `Models` | 选择或添加 `step-5-preview`。 |

点击 `Submit` 后，在模型选择器中选择该自定义 Provider 下的模型。此配置使用 Chat Completions 协议，完整请求路径为 `/step_plan/v1/chat/completions`。

手动添加的模型还需提供上下文和输出容量信息。若当前配置文件中的自定义模型缺少这些字段，将以下内容合并到 `kilo.json` 或 `kilo.jsonc`，保留该 Provider 已有的连接与认证设置：

```json theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
{
  "provider": {
    "step-plan": {
      "models": {
        "step-5-preview": {
          "name": "Step 5 Preview",
          "limit": {
            "context": 1000000,
            "output": 65536
          }
        }
      }
    }
  }
}
```

上述容量配置适用于 [Step 5 Preview](/docs/zh/guides/models/step-5-preview)。切换到其他模型时，按对应模型规格调整。推理模型需要为推理与正文保留预算，过小的输出限制可能导致正文为空或提前结束。

## 接入 StepSearch MCP

[StepSearch](/docs/zh/guides/developer/integrations/search-mcp) 通过 Step Plan 端点提供 `web_search` 和 `web_fetch`，用于联网搜索与网页内容获取。

### 提供认证环境变量

完全退出编辑器后，在项目目录的终端中设置密钥并重新启动编辑器。将 `YOUR_STEP_API_KEY` 替换为实际密钥；Cursor 用户将 `code .` 替换为 `cursor .`。

<Tabs>
  <Tab title="macOS / Linux / WSL">
    ```bash theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
    export STEP_API_KEY="YOUR_STEP_API_KEY"
    code .
    ```
  </Tab>

  <Tab title="Windows PowerShell">
    ```powershell theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
    $env:STEP_API_KEY = "YOUR_STEP_API_KEY"
    code .
    ```
  </Tab>
</Tabs>

若编辑器命令不可用，先配置对应命令行入口。环境变量只对当前终端及其启动的进程生效；以后使用该 MCP 时，也需确保编辑器进程能够读取 `STEP_API_KEY`。

### 添加 MCP 服务

1. 在 Kilo Code 设置中打开 `MCP Servers`。
2. 编辑当前项目的 `kilo.json`。如果项目已有 `kilo.jsonc` 或 `.kilo/` 下的同名配置文件，请合并到现有文件中，保留其他设置：

```json theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
{
  "mcp": {
    "step-search": {
      "type": "remote",
      "url": "https://api.stepfun.com/step_plan/v1/mcp/web_search/mcp",
      "headers": {
        "Authorization": "Bearer {env:STEP_API_KEY}"
      },
      "oauth": false,
      "enabled": true
    }
  }
}
```

3. 保存后刷新或重新连接服务，检查 `step-search` 是否已连接，以及工具列表中是否包含 `web_search` 和 `web_fetch`。
4. 新建任务，调用其中一个工具完成搜索或网页抓取，按提示确认授权，并核对实际返回结果。

新版配置使用顶层 `mcp`、`type: "remote"` 和 `{env:STEP_API_KEY}` 环境变量引用。远程服务优先使用 Streamable HTTP，必要时回退到 SSE。该示例通过请求头认证，不使用 OAuth。

<Warning>
  请保留示例中的环境变量引用，不要将真实密钥写入项目配置后提交到代码仓库。任何获得该密钥的人都可能以您的权限发起请求并消耗额度。
</Warning>

## 验证接入

### 验证对话

新建任务并输入 `请只回复 OK。`，预期返回 `OK`。

### 验证工具调用

1. 在独立测试目录中创建 `README.md`，内容为 `Kilo Code Step Plan test`，然后在编辑器中打开该目录。
2. 新建任务，发送以下指令：

```text theme={"theme":{"light":"light-plus","dark":"dark-plus"}}
读取 README.md，创建 hello.py，使其打印 "Hello, world!"。
使用本机可用的 Python 解释器运行 hello.py，并报告执行命令和实际输出。
不要修改 README.md 或其他已有文件。
```

3. 按提示批准必要的文件与命令操作，核对读取、编辑和执行记录。确认 `hello.py` 实际生成，输出为 `Hello, world!`，且 `README.md` 未被修改。

### 验证配置保存

重启编辑器后，检查 Provider 与模型选择是否保留，并重新发起一次简短对话。

## 常见问题

<AccordionGroup>
  <Accordion title="Q: 找不到 Step Plan Provider 或 Step 5 Preview 怎么办？">
    更新 Kilo Code 扩展并检查 Provider 列表。也可通过 `Providers > Custom provider` 选择 `OpenAI Compatible`，填写 Step Plan Base URL，并手动添加 `step-5-preview`。保存后，选择该自定义 Provider 下的模型。
  </Accordion>

  <Accordion title="Q: 提示 Connection error 或返回 401 怎么办？">
    查看完整错误信息，检查网络连接、Base URL、API Key 与模型权限。自定义 Provider 使用 `https://api.stepfun.com/step_plan/v1`；API Key 应完整、有效，且属于对应站点账号。根据服务端返回信息，分别排查认证、模型和请求参数。
  </Accordion>

  <Accordion title="Q: 回复为空或被截断怎么办？">
    检查停止原因和输出预算。推理可能先消耗输出预算，过小的限制会影响正文生成。使用内置模型时先恢复其预设；使用自定义模型时检查容量与请求设置，再按实际错误调整。
  </Accordion>

  <Accordion title="Q: 旧版 Include max output tokens 设置如何处理？">
    `Include max output tokens` 和 `Max Output Tokens = -1` 属于旧版界面配置，不作为新版内置 Provider 的必填项。新版自定义模型使用 `limit.context`、`limit.output` 描述容量，请填写模型支持的有效值，不要直接将 `-1` 复制到 `limit.output`。
  </Accordion>

  <Accordion title="Q: 旧版 .kilocode/mcp.json 配置如何处理？">
    当前流程使用 `kilo.json` 或 `kilo.jsonc` 中的 `mcp` 配置。旧版 `.kilocode/mcp.json` 中的 `mcpServers`、`streamable-http`、`disabled` 等字段不能直接混入新版示例；请按当前配置格式迁移，或使用与旧版扩展匹配的配置。
  </Accordion>

  <Accordion title="Q: MCP 中没有 step-search 或对应工具怎么办？">
    检查配置是否位于当前项目实际加载的文件中，`type` 是否为 `remote`、`enabled` 是否为 `true`。确认编辑器进程可以读取 `STEP_API_KEY`，请求头使用 `Bearer {env:STEP_API_KEY}`。保存后重新连接，并查看服务日志。
  </Accordion>

  <Accordion title="Q: 模型只回复文字，没有执行操作怎么办？">
    确认已打开目标项目，当前模式允许修改文件，并检查是否有等待批准的工具调用。按提示授权后继续；不需要为完成验证而开启全部自动批准选项。
  </Accordion>
</AccordionGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.