Skip to main content
自托管环境（self-hosted environment）让沙箱工具在你管理的主机上运行，平台继续负责模型调用、智能体编排和会话管理。
自托管环境仅向企业认证用户开放，请完成企业认证后使用。
自托管环境不严格等于私有化部署。工具的输入和执行结果仍会经过平台模型推理接口。

​
适用场景

  • 需要让代码执行和文件处理留在自己的执行环境中，并把执行沙箱工具的主机纳入组织的合规、审计和运维体系；
  • 需要访问只有企业内网可达的服务（云托管沙箱 配合网络代理规则也可以实现）。

​
与云端模式的能力差异

以下差异是当前版本的预期行为。

​
工作原理

  1. 创建会话时绑定自托管环境，智能体循环（agent loop）仍在云端执行。
  2. 在 Worker 主机上运行官方 Worker 命令完成注册，Worker 随后主动领取该环境的任务，执行沙箱工具调用。
  3. 工具结果上报会话，智能体循环恢复执行。
MCP 与自定义工具不经过该 Worker，仍按各自原有方式运行。

​
接入前准备

  • 一个可用的智能体：创建会话时使用；如果还没有，先完成 快速开始。
  • 一台 Worker 主机：以下示例以 macOS 或 Linux 为例，主机需要能通过出站 HTTPS 访问平台。
  • 管理端 API Key（可选）：只有选择通过 API 创建环境时才需要准备 KIMI_API_KEY；使用控制台创建环境不需要。

​
运行第一个会话

1

创建自托管环境

在 Kimi 开放平台控制台 进入“托管智能体 > 环境”，点击“创建环境”，选择“Self-hosted”。也可以通过 API 在管理端创建：
自托管环境无需构建，创建后即可使用。创建后复制环境 ID，并在 Worker 主机上设置：
2

生成环境密钥

在环境详情的“Worker”页点击“生成环境密钥”。完整密钥只展示一次，请立即复制并妥善保存。环境密钥以 ewk- 开头，只用于接入对应环境。主机下线或密钥泄露时，在控制台吊销并重新生成。
3

安装 kha CLI 并启动 Worker

以下命令以 macOS 或 Linux 为例。在 Worker 主机上安装 kha CLI：
运行以下命令，按隐藏提示粘贴刚生成的环境密钥。密钥会保存在系统钥匙串中：
在希望执行任务的工作目录中启动 Worker：
--workdir "$PWD" 将当前目录作为 shell 工具的工作目录；--max-idle 0 让 Worker 在空闲时继续等待任务。请保持命令运行。
4

创建会话并验证

在控制台进入“托管智能体 > 会话”，选择已有智能体和刚创建的环境，创建会话并发送以下任务：
任务完成后，在 Worker 主机的工作目录中查看文件：
文件应包含 Worker 主机的系统信息。环境详情的“Worker”页可以查看活跃 Worker 和队列状态。

​
网络与凭据

  • Worker 主机需要能通过出站 HTTPS 访问 https://api.moonshot.cn，无需为任务队列开放入站端口。
  • 自托管沙箱工具使用 Worker 主机的网络出口。远程 MCP、平台侧工具和自定义工具的执行位置不会因此改变。
  • 你负责 Worker 主机加固、进程和文件系统隔离、依赖，以及外部服务凭据的管理。
  • 普通 KIMI_API_KEY 只用于管理端，不要写入 Worker 镜像、工作目录或工具子进程环境。

​
常见问题

kha worker poll 默认在空闲 60 秒后退出。需要持续等待任务时，在启动命令中添加 --max-idle 0。
在无法使用系统钥匙串的容器或 CI 中，可以跳过 kha worker login，直接通过密钥文件启动 Worker：
将 /path/to/work-key 替换为环境密钥文件的路径。也可以使用 --token-stdin 从标准输入读取密钥，不要把密钥直接写入命令参数。
先确认会话绑定了当前自托管环境，并且已经发送任务，而不只是创建会话。再检查 Worker 进程是否运行、环境 ID 是否与密钥匹配、密钥是否被吊销，以及主机能否通过出站 HTTPS 访问平台 API。

​
相关资源

启动会话

通过控制台或 API 创建会话并发送任务。

执行环境

查看云环境配置与环境 API 操作。