> ## 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，在自己的基础设施中运行托管智能体的沙箱工具。

自托管环境（self-hosted environment）让沙箱工具在你管理的主机上运行，平台继续负责模型调用、智能体编排和会话管理。

<Warning>
  自托管环境仅向企业认证用户开放，请完成企业认证后使用。
</Warning>

<Note>
  自托管环境不严格等于私有化部署。工具的输入和执行结果仍会经过平台模型推理接口。
</Note>

## 适用场景

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

## 与云端模式的能力差异

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

| 能力 | 云端模式 | 自托管模式 |
| - | - | - |
| `read_file`、`write_file`、`edit_file`、`shell`、`todo_read`、`todo_write` | 在云沙箱中执行，计入沙箱运行时长 | 在 Worker 主机上执行，以主机的系统权限读写文件系统，平台不收取费用 |
| `web_search`、`web_open_url` | 由平台执行，按调用次数计费 | 相同：仍由平台执行，按调用次数正常计费，价格见 [托管智能体定价](/docs/pricing/hosted-agents) |
| `ipython`、`search_image_by_text`、`search_image_by_image`、`save_artifact` | 在云沙箱中执行 | 暂不支持 |
| 会话 [文件](/docs/hosted-agents/files) | 上传到云沙箱，工具产物进入会话文件列表 | 上传的文件不同步到 Worker 主机；主机上的工具产物不进入会话文件列表 |
| [技能](/docs/hosted-agents/skills) 和 [记忆](/docs/hosted-agents/memory) | 挂载到云沙箱 | 不挂载到 Worker 主机 |

## 工作原理

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

MCP 与自定义工具不经过该 Worker，仍按各自原有方式运行。

## 接入前准备

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

## 运行第一个会话

<Steps>
  <Step title="创建自托管环境">
    在 [Kimi 开放平台控制台](https://platform.kimi.com/console) 进入“托管智能体 > 环境”，点击“创建环境”，选择“Self-hosted”。

    也可以通过 API 在管理端创建：

    <CodeGroup>
      ```bash cURL theme={null}
      curl -sS -X POST "https://api.moonshot.cn/v1/environments" \
        -H "Authorization: Bearer $KIMI_API_KEY" \
        -H "kimi-api-version: 2026-09-01-beta" \
        -H "Content-Type: application/json" \
        -d '{
          "name": "内网执行环境",
          "config": {
            "type": "self_hosted"
          }
        }'
      ```

      ```bash CLI theme={null}
      kha environments create --name "内网执行环境" --self-hosted
      ```
    </CodeGroup>

    自托管环境无需构建，创建后即可使用。创建后复制环境 ID，并在 Worker 主机上设置：

    ```bash theme={null}
    export ENVIRONMENT_ID="env_your_environment_id"
    ```
  </Step>

  <Step title="生成环境密钥">
    在环境详情的“Worker”页点击“生成环境密钥”。完整密钥只展示一次，请立即复制并妥善保存。

    环境密钥以 `ewk-` 开头，只用于接入对应环境。主机下线或密钥泄露时，在控制台吊销并重新生成。
  </Step>

  <Step title="安装 kha CLI 并启动 Worker">
    以下命令以 macOS 或 Linux 为例。在 Worker 主机上安装 kha CLI：

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

    运行以下命令，按隐藏提示粘贴刚生成的环境密钥。密钥会保存在系统钥匙串中：

    ```bash theme={null}
    kha worker login "$ENVIRONMENT_ID"
    ```

    在希望执行任务的工作目录中启动 Worker：

    ```bash theme={null}
    kha worker poll "$ENVIRONMENT_ID" --workdir "$PWD" --max-idle 0
    ```

    `--workdir "$PWD"` 将当前目录作为 shell 工具的工作目录；`--max-idle 0` 让 Worker 在空闲时继续等待任务。请保持命令运行。
  </Step>

  <Step title="创建会话并验证">
    在控制台进入“托管智能体 > 会话”，选择已有智能体和刚创建的环境，创建会话并发送以下任务：

    ```text theme={null}
    使用 shell 在当前工作目录创建 hello.txt，写入 uname -a 的输出。
    ```

    任务完成后，在 Worker 主机的工作目录中查看文件：

    ```bash theme={null}
    cat hello.txt
    ```

    文件应包含 Worker 主机的系统信息。环境详情的“Worker”页可以查看活跃 Worker 和队列状态。
  </Step>
</Steps>

## 网络与凭据

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

## 常见问题

<AccordionGroup>
  <Accordion title="Worker 空闲 60 秒后退出">
    `kha worker poll` 默认在空闲 60 秒后退出。需要持续等待任务时，在启动命令中添加 `--max-idle 0`。
  </Accordion>

  <Accordion title="没有系统钥匙串时，如何启动 Worker？">
    在无法使用系统钥匙串的容器或 CI 中，可以跳过 `kha worker login`，直接通过密钥文件启动 Worker：

    ```bash theme={null}
    kha worker poll "$ENVIRONMENT_ID" \
      --token-file /path/to/work-key \
      --workdir "$PWD" \
      --max-idle 0
    ```

    将 `/path/to/work-key` 替换为环境密钥文件的路径。也可以使用 `--token-stdin` 从标准输入读取密钥，不要把密钥直接写入命令参数。
  </Accordion>

  <Accordion title="发送任务后，Worker 没有反应">
    先确认会话绑定了当前自托管环境，并且已经发送任务，而不只是创建会话。再检查 Worker 进程是否运行、环境 ID 是否与密钥匹配、密钥是否被吊销，以及主机能否通过出站 HTTPS 访问平台 API。
  </Accordion>
</AccordionGroup>

## 相关资源

<CardGroup cols={2}>
  <Card title="启动会话" icon="message" href="/docs/hosted-agents/sessions">
    通过控制台或 API 创建会话并发送任务。
  </Card>

  <Card title="执行环境" icon="layer-group" href="/docs/hosted-agents/environments">
    查看云环境配置与环境 API 操作。
  </Card>
</CardGroup>