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

# 使用 kha CLI 管理托管智能体

> 在 AI 编程助手中通过自然语言创建和配置智能体、创建会话、提交和继续任务，并获取产物。

`kha` 是与控制台和 API 并列的托管智能体使用入口，具备与两者相同的资源管理和会话操作能力。安装后，你可以在 Kimi Code、Claude Code、Codex 等 AI 编程助手中用自然语言创建和配置智能体（Agent）与执行环境（Environment），创建会话（Session），提交和继续任务，查看执行状态并获取产物（Artifact）。

## 安装与认证

开始前，准备具有托管智能体访问权限的 API Key。

### 安装 kha CLI

在终端运行一键安装脚本：

<Tabs>
  <Tab title="macOS / Linux">
    ```bash theme={null}
    curl -fsSL https://ha-static.moonshot.cn/kha/install.sh | sh
    export PATH="$HOME/.local/bin:$PATH"
    ```

    脚本自动识别操作系统与架构并校验 SHA-256，默认安装到 `~/.local/bin`；设置 `KHA_INSTALL_DIR` 可更换目录，设置 `KHA_VERSION=0.X.Y` 可安装指定版本（默认最新稳定版）。
  </Tab>

  <Tab title="Windows (PowerShell)">
    ```powershell theme={null}
    $installer = Join-Path ([IO.Path]::GetTempPath()) 'kha-install.ps1'
    Invoke-WebRequest https://ha-static.moonshot.cn/kha/install.ps1 -UseBasicParsing -OutFile $installer
    & $installer
    $env:Path = "$(Join-Path $env:LOCALAPPDATA 'kha\bin');$env:Path"
    ```

    默认安装到 `%LOCALAPPDATA%\kha\bin`；用 `-InstallDir` 可更换目录，`-Version 0.X.Y` 可安装指定版本（默认最新稳定版）。
  </Tab>
</Tabs>

安装完成后验证：

```bash theme={null}
kha version
```

希望由 AI 编程助手代为安装时，将下面这句话发给它：

```text wrap theme={null}
请从 https://ha-static.moonshot.cn/kha/install.sh 下载并运行 kha CLI 安装脚本（Windows 使用同一目录下的 install.ps1）。
确认 kha version 可用后，执行 kha install-skill -g 把 kha 技能包安装到用户级技能目录，并报告 CLI 版本和技能包安装路径。
```

### 安装 kha 技能包

在 AI 编程助手中配合使用时，需要安装 kha 技能包，助手才能按内置的最佳实践调用 CLI。技能包随 CLI 分发、无需联网下载：

```bash theme={null}
kha install-skill      # 项目级：./.agents/skills/kha/
kha install-skill -g   # 用户级：~/.agents/skills/kha/
```

需要安装到其他目录时使用 `--dir`。安装完成后，按客户端要求刷新或新开一个会话，确认技能已加载。如需直接使用 CLI 管理资源，请查看 [查询 CLI 命令用法](#查询-cli-命令用法)。

### 升级 kha CLI

CLI 每天会自动检查一次新版本，发现落后时在 stderr 给出提示，不影响命令输出；设置 `KHA_NO_UPDATE_CHECK=1` 可关闭检查，CI 环境中自动跳过。手动升级运行：

```bash theme={null}
kha upgrade                  # 升级到最新稳定版
```

升级会下载并校验新二进制、原地替换，并自动刷新已安装的技能包副本。

### 配置认证

在 [Kimi 开放平台](https://platform.kimi.com/console/api-keys) 创建 API Key，然后在本地终端运行：

```bash theme={null}
kha login
```

运行命令后，终端出现无回显的输入提示，粘贴 API Key 后按回车即完成。脚本或无交互环境中改用 `kha login --api-key-stdin`，从标准输入读取。

API Key 只在本地终端中输入，不要写入命令参数，也不要粘贴到 AI 编程助手的对话中。

`login` 只保存凭据，`whoami` 才会访问 API 并验证身份：

```bash theme={null}
kha whoami
```

如果终端中已配置 `KIMI_API_KEY`，CLI 也可以直接使用。需要管理多个账号或环境时，可以用 profile 分别保存配置：

```bash theme={null}
kha login --profile work
kha whoami --profile work
```

## 用自然语言完成第一个任务

在 AI 编程助手中发送：

```text wrap theme={null}
请使用 kha CLI，为以下销售数据选择或创建合适的智能体和执行环境。
确认执行环境已就绪后创建会话，按月份和产品类别统计销售额，将报告保存为产物 sales-report.md。
任务完成后下载报告，并给出主要结论和会话 ID。

2026 年 1 月，产品 A 销售额 12000 元，产品 B 销售额 8000 元；
2026 年 2 月，产品 A 销售额 15000 元，产品 B 销售额 10000 元；
2026 年 3 月，产品 A 销售额 18000 元，产品 B 销售额 12000 元。
```

AI 编程助手会通过 kha CLI 完成以下操作：

1. 检查现有智能体和执行环境的配置，没有合适资源时再创建；
2. 等待执行环境状态变为 `ready`；
3. 创建会话，发送销售数据和统计要求；
4. 检查任务回答与产物，确认结果完整；
5. 下载 `sales-report.md`，返回主要结论、会话 ID 和本地文件路径。

## 常见管理场景

以下示例可直接作为对 AI 编程助手的指令，资源名称、ID 和文件路径应替换为实际值。

| 场景 | 自然语言指令示例 | 相关文档 |
| - | - | - |
| 调整智能体 | “读取当前配置，在保留其他配置的前提下更新系统提示词，并创建新会话验证。” | [创建与管理智能体](/docs/hosted-agents/agents) |
| 配置技能或插件（Plugin） | “上传这个技能包并绑定到指定智能体，保留已有技能与插件。” | [技能](/docs/hosted-agents/skills)、[插件](/docs/hosted-agents/plugins) |
| 多智能体协作 | “创建一个协调智能体和三个子智能体，让协调智能体将可并行的子任务分派给它们，并汇总结果。” | [多智能体编排](/docs/hosted-agents/multiagent-orchestration) |
| 使用外部服务 | “为需要访问 GitHub 的任务配置凭据库（Vault），并告诉我在哪里完成授权。” | [凭据库](/docs/hosted-agents/vaults)、[接入 MCP](/docs/hosted-agents/mcp) |
| 使用跨会话记忆 | “创建项目记忆库（Memory Store），并在新会话中以只读方式挂载。” | [记忆库](/docs/hosted-agents/memory) |
| 定时运行 | “创建一个每个工作日 09:00 运行的触发器（Trigger），并手动运行一次检查结果。” | [定时运行智能体](/docs/hosted-agents/triggers) |
| 文件与产物 | “上传这个文件并绑定到原会话，任务完成后下载生成的产物。” | [文件](/docs/hosted-agents/files) |
| 调试失败任务 | “读取这个会话的完整事件记录，重点分析 agent.thinking、agent.tool\_use 和 agent.tool\_result，定位失败原因。” | [事件流](/docs/hosted-agents/event-stream) |

凭据库和记忆库需要在创建会话时绑定。更新智能体后，应创建新会话验证，因为已有会话仍使用创建时绑定的智能体版本。触发器显示初始事件已被接受后，还要检查对应会话的回答和产物。

## 与控制台和 API 配合

通过 kha CLI 创建的智能体、会话和产物都可以在控制台和 API 中继续操作。你可以在 AI 编程助手中继续输入自然语言指令，在 [控制台](/docs/hosted-agents/console) 中继续会话，或通过 [API](/docs/api-reference) 继续发送消息、查看事件和取消当前轮次。

控制台适合可视化配置、OAuth 授权、运行观测和产物检查；API 适合将后续操作集成到自己的系统。首条任务消息可以直接通过 kha CLI 发送，无需打开控制台。

## 故障排查

| 问题 | 检查与处理 |
| - | - |
| AI 编程助手没有识别 kha 技能包 | 检查安装范围、`kha/SKILL.md` 路径和完整的 `references/` 目录，再按客户端要求刷新或新开一个会话 |
| 找不到 `kha` 命令 | 确认 CLI 已安装，安装目录已加入 `PATH`，并用 `kha version` 验证 |
| 认证失败或返回 401 / 403 | 使用相同 profile 和服务地址运行 `kha whoami`，检查 API Key 是否有效以及是否有托管智能体访问权限 |
| 创建会话时提示执行环境未就绪 | 等待执行环境状态变为 `ready` 后用原配置重试，不要重复创建执行环境 |
| 等待超时但没有得到结果 | 查询原会话的状态和最近执行记录；本地超时不会停止云端执行 |
| 追加输入没有立即执行 | 会话处于 `running` 时新输入会排队，检查是否还有待处理输入 |
| 更新智能体后行为没有变化 | 创建新会话验证；已有会话使用原先绑定的智能体版本 |

## 查询 CLI 命令用法

不使用 AI 编程助手时，也可以直接用 kha CLI 管理资源。运行以下命令查看与本机 CLI 版本一致的完整命令参考：

```bash theme={null}
kha docs
```

需要某个命令的参数和用法时，用 `kha docs <资源> <命令>` 逐级查看。

## 请求体输入方式

直接用 CLI 创建或更新资源时，有两种方式传入请求参数：

* **字段选项**：顶层标量字段用命令选项传入，例如 `kha sessions create --agent "$AGENT_ID" --environment "$ENVIRONMENT_ID" --title "周报"`。
* **完整请求体**：嵌套结构（如 `resources`、`tools`、`mcp_servers`、`metadata`）用 `--file` 整体传入，支持 **JSON 或 YAML**，`--file -` 表示从标准输入读取。

两种方式不能混用：使用 `--file` 时不能再带字段选项。请求体字段与 REST API 契约一致，因此文档中 cURL 示例的 JSON body 可以直接交给 `--file`；同样的内容也可以写成 YAML：

```bash theme={null}
kha sessions create --file - <<'YAML'
agent_id: agent_...
environment_id: env_...
title: 周报
resources:
  - type: file
    file_id: file_...
YAML
```

消息文本等单字段内容用 `--text-file`、`--payload-file`、`--content-file` 等选项按字面文本读入，不做结构化解析。

## 下一步

<CardGroup cols={2}>
  <Card title="管理运行中的会话" icon="message" href="/docs/hosted-agents/session-operations">
    查看会话状态、待处理输入和当前轮次的取消方式。
  </Card>

  <Card title="在控制台中继续操作" icon="display" href="/docs/hosted-agents/console">
    在网页上配置资源、观测运行并检查产物。
  </Card>
</CardGroup>