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

# Kimi Code 集成指南

> AceDataCloud Coding Plan 集成指南 - Ace Data Cloud

Kimi Code CLI 是一个运行在终端里的 AI 编程 Agent，可以阅读和修改代码、执行命令、运行测试、搜索文件，并根据执行结果继续规划下一步。把它接入 Ace Data Cloud 后，可以直接使用 `kimi-k3`，一把 API Token 也可继续调用平台上的其他服务。

本文从安装开始，带你完成配置、校验和第一次真实运行。Kimi Code CLI `0.33.0` 与 `kimi-k3` 的 2026 年 8 月 6 日结果是历史证据；发布选择器前必须以当前安装版本和最终 TOML 字节重新验证。

## 1. 安装 Kimi Code

### macOS / Linux（推荐）

运行官方安装脚本，无需预装 Node.js：

```bash theme={null}
curl -fsSL https://code.kimi.com/kimi-code/install.sh | bash
```

安装结束后，打开一个新的终端窗口，再检查版本：

```bash theme={null}
kimi --version
```

如果仍提示 `command not found`，先重开终端；仍无效时，根据安装器最后打印的提示，把 `~/.kimi-code/bin` 加入 `PATH`。

### Windows PowerShell

先安装 [Git for Windows](https://gitforwindows.org/)。Kimi Code 会使用其中的 Git Bash 作为 Shell 环境。然后在 PowerShell 中运行：

```powershell theme={null}
irm https://code.kimi.com/kimi-code/install.ps1 | iex
```

关闭并重新打开 PowerShell，再检查：

```powershell theme={null}
kimi --version
```

如果 Git Bash 安装在自定义目录，需要把 `KIMI_SHELL_PATH` 设置为 `bash.exe` 的绝对路径。

### npm 备用安装方式

如果你更习惯 npm，请先安装 Node.js 22.19.0 或更高版本：

```bash theme={null}
node --version
npm install -g @moonshot-ai/kimi-code
kimi --version
```

> 旧的 `kimi-cli` 项目正在迁移到 Kimi Code CLI。新安装请使用本页的 `@moonshot-ai/kimi-code` 或官方安装脚本。

## 2. 获取 Ace Data Cloud API Token

打开 [Ace Data Cloud 控制台](https://platform.acedata.cloud/console/applications) 获取 API Token。一个 Token 即可访问平台上的多种模型和服务。

请妥善保管 Token：不要把它提交到 Git，不要粘贴到 Issue、日志或截图中，也不要写进团队共享的示例文件。

## 3. 配置 Kimi K3

Kimi Code 的用户配置文件是：

* macOS / Linux：`~/.kimi-code/config.toml`
* Windows：用户主目录下的 `.kimi-code/config.toml`

首次运行后该文件会自动创建，也可以手动创建目录和文件。把下面配置完整写入 `config.toml`，再将 `{token}` 和 `MODEL_ID` 替换为选择器给出的值：

```toml theme={null}
default_model = "acedata/MODEL_ID"
default_permission_mode = "manual"
telemetry = false

[providers.acedata]
type = "openai"
base_url = "https://api.acedata.cloud/v1"
api_key = "{token}"

[models."acedata/MODEL_ID"]
provider = "acedata"
model = "MODEL_ID"
max_context_size = 1048576
capabilities = ["thinking", "always_thinking", "image_in", "tool_use"]
support_efforts = ["max"]
default_effort = "max"
display_name = "MODEL_ID"

[thinking]
enabled = true
effort = "max"
keep = "all"
```

这里有三个容易写错的地方：

1. `type` 必须是 `openai`，因为 Ace Data Cloud 为 Kimi Code 提供 OpenAI Chat Completions 兼容接口。
2. `base_url` 必须以 `/v1` 结尾；Kimi Code 会继续拼接 `/chat/completions`。
3. `model` 必须是 `kimi-k3`，而 `default_model` 指向上面定义的本地别名 `acedata/kimi-k3`。

### 更安全地保护配置文件

macOS / Linux 用户可以限制只有当前账户能够读取配置：

```bash theme={null}
chmod 600 ~/.kimi-code/config.toml
```

不要在本文配置完成后再执行 `/login` 并选择其他平台，否则登录流程可能改变默认模型。需要检查当前配置时，使用后面的 `kimi doctor` 和 `kimi provider list`。

## 4. 检查配置

先让 Kimi Code 校验 TOML 格式和字段：

```bash theme={null}
kimi doctor
```

正常结果包含：

```text theme={null}
OK config.toml
All checked config files are valid.
```

再确认 provider 和默认模型：

```bash theme={null}
kimi provider list
```

应看到类似结果：

```text theme={null}
acedata  type=openai  models=1  source=inline

Default model: acedata/kimi-k3
```

如果 `kimi doctor` 报错，请优先检查 TOML 引号、表名和 `{token}` 是否已经替换。

## 5. 在项目中启动

进入一个代码仓库并启动交互界面：

```bash theme={null}
cd /path/to/your-project
kimi
```

第一次可以输入这个英文测试任务：

```text theme={null}
Take a look at this project and explain its main directories. Do not modify any files.
```

Kimi Code 会读取目录和文件，然后给出项目结构说明。默认的 `manual` 权限模式会在写文件或执行敏感命令前询问你；认真查看操作内容后再批准。

接下来可以尝试一个真实开发任务：

```text theme={null}
Find the test command used by this project, run the smallest relevant test suite, and explain any failures. Do not change code yet.
```

确认分析正确后，再明确要求它修改代码并运行测试。

## 6. 常用运行方式

### 非交互执行一条任务

`-p` 适合脚本或只运行一次的任务：

```bash theme={null}
kimi -p "Summarize the current repository status"
```

本页实测命令为：

```bash theme={null}
kimi -p "Reply with exactly: KIMI_CODE_K3_OK"
```

Kimi Code CLI `0.33.0` 通过 Ace Data Cloud `kimi-k3` 返回了：

```text theme={null}
KIMI_CODE_K3_OK
```

### 继续最近一次会话

```bash theme={null}
kimi --continue
```

也可以用简写：

```bash theme={null}
kimi -c
```

### 先规划、暂不修改

```bash theme={null}
kimi --plan
```

Plan 模式适合大型改动：先让 Agent 阅读代码并给出方案，确认后再执行。

### 自动批准操作

```bash theme={null}
kimi --yolo
```

`--yolo` 会自动批准普通文件修改和 Shell 操作。只应在受信任的仓库、容器或隔离环境中使用；日常开发建议保留默认的 `manual`。

## 7. 交互界面常用命令

| 命令          | 作用           |
| ----------- | ------------ |
| `/help`     | 查看完整命令和快捷键   |
| `/model`    | 查看或切换当前模型    |
| `/new`      | 开始新会话        |
| `/sessions` | 浏览并恢复历史会话    |
| `/compact`  | 压缩较长的上下文     |
| `/exit`     | 退出 Kimi Code |

常用快捷键：

* `Esc`：中断当前输出或关闭弹窗
* `Shift-Tab`：切换 Plan 模式
* `Ctrl-C`：中断输出；空闲时连续按两次退出
* `Ctrl-O`：折叠或展开工具输出

## 8. 常见问题

### `kimi: command not found`

重新打开终端后再试。脚本安装默认把程序放在 `~/.kimi-code/bin`；确认该目录已加入 `PATH`。npm 安装则需要确认 npm 全局 bin 目录在 `PATH` 中。

### Windows 找不到 Git Bash

安装 Git for Windows。如果安装目录不是默认位置，在 PowerShell 中设置：

```powershell theme={null}
$env:KIMI_SHELL_PATH = "C:\Path\To\Git\bin\bash.exe"
```

确认可用后，可在 Windows 的用户环境变量中持久化该值。

### 返回 401 或 `invalid_token`

检查 `api_key` 是否仍是 `{token}` 占位符、是否有多余空格、是否复制完整。重新从 [控制台](https://platform.acedata.cloud/console/applications) 获取 Token 后再试。

### 返回 `model not found` 或模型列表里没有 Kimi K3

确认下面三处完全一致：

```toml theme={null}
default_model = "acedata/MODEL_ID"
model = "MODEL_ID"
```

然后运行：

```bash theme={null}
kimi doctor
kimi provider list
```

### 请求发到了错误地址

确认 provider 使用：

```toml theme={null}
type = "openai"
base_url = "https://api.acedata.cloud/v1"
```

不要写成 Kimi Code OAuth 托管地址，也不要漏掉 `/v1`。

### 配置修改后没有生效

退出当前 Kimi Code 进程，再重新运行 `kimi`。配置在会话启动时读取；已经运行的会话不会自动重载所有 provider 设置。

## 9. 升级与卸载

检查并升级：

```bash theme={null}
kimi upgrade
```

npm 安装的用户也可以运行：

```bash theme={null}
npm install -g @moonshot-ai/kimi-code@latest
```

卸载 npm 版本：

```bash theme={null}
npm uninstall -g @moonshot-ai/kimi-code
```

## 官方参考

* [Kimi Code 产品页](https://www.kimi.com/code)
* [Kimi Code CLI GitHub 仓库](https://github.com/MoonshotAI/kimi-code)
* [官方开始使用](https://moonshotai.github.io/kimi-code/zh/guides/getting-started)
* [官方平台与模型配置](https://moonshotai.github.io/kimi-code/zh/configuration/providers)
* [官方配置文件参考](https://moonshotai.github.io/kimi-code/zh/configuration/config-files)
* [官方命令参考](https://moonshotai.github.io/kimi-code/zh/reference/kimi-command)