前置条件
克隆 executor 仓库
克隆仓库，其中包含你后续要部署的控制器与客户端：环境变量
- PPIO_API_KEY —— 在 PPIO 控制台获取 API key。
- KIMI_API_KEY —— 在 Kimi 开放平台的 API keys 页面创建。
- KIMI_ENVIRONMENT_ID —— 创建环境一节里
--create-environment打印的 ID。 - KIMI_ENVIRONMENT_KEY —— 在 Kimi 控制台该环境的 Worker 标签页生成的环境密钥，见申请环境 Key。
- KIMI_AGENT_ID —— 创建 Agent一节里
--create-agent打印的 ID。
创建自托管环境
创建环境
环境只需创建一次，而不是每个会话都创建：.env 的 KIMI_ENVIRONMENT_ID。
申请环境 Key
在 Kimi 控制台进入项目，依次打开 托管智能体 › 环境，选择刚刚创建的环境，点击 生成环境密钥。把生成的密钥（ewk-...）填入 .env 的 KIMI_ENVIRONMENT_KEY。
创建 Agent
创建控制器将要服务的 Agent：.env 的 KIMI_AGENT_ID。
部署控制器
.controller.json。重新运行 webhook:deploy 会重新连接到同一控制器，并用新的环境变量重启它。不使用时，用该 ID 暂停或关闭控制器沙箱：
发送输入
通过客户端向 Agent 发送消息，客户端与运行在 worker 沙箱中的 Agent 通信：{"session_id":"sesn_..."}。Agent 的输出会随着生成实时流出，会话回到 idle 后命令退出。
如果配置正确，Agent 描述的会是沙箱内的环境，而非你的本机 —— 例如下面的 Debian GNU/Linux 12 (Bookworm)、内核 Linux 6.1.158、x86_64，工作目录 /workspace —— 这确认了会话通过 PPIO 托管的 worker 执行，你无需创建或注册任何自己的沙箱。
--session-id 传回即可在同一 worker、同一工作区继续：
Sandbox 的文件系统与沙箱绑定，会随沙箱一起销毁。如果你希望代码与数据在沙箱之外留存、并可被其他 Agent 读取，请用 Git 管理代码，或挂载 Volume 将数据保存在沙箱之外并在多个沙箱间共享。
排查
日志与状态
- 控制器日志：控制器沙箱内的
/app/controller.log，JSON 行格式，事件包括enqueued、ack_failed、worker_created、worker_resumed、executor_started、worker_paused、claim_resolved、work_reread_failed、reconcile_failed、poll_failed等。进程崩溃的堆栈写入/app/controller.stdio.log。 - worker 日志：每个 worker 内的
/tmp/kha-worker.log。租约与工具调用失败都在这里，而不是在任何 HTTP 状态码中。 - 工作队列：
GET /v1/environments/$KIMI_ENVIRONMENT_ID/work列出每个工作项的状态与worker_id；/work/stats返回队列深度与 worker 数量。 - 元数据：worker 沙箱带有
agents-session-id=<session>，控制器沙箱带有agents-webhook-controller=ppio。