Kimi Hosted Agents 兼容指南

OpenMA 在自部署 Node 上提供实验性的 Kimi Hosted Agents（KHA）兼容子集，需要手动开启。它复用 OpenMA 的认证、Agent、会话执行和输出存储，不是另一套运行时，也不是 Moonshot 服务的完整实现。

产品差异见 Kimi Hosted Agents 与 OpenMA 对比（English）。调用 Moonshot 自己的服务请使用其官方快速开始，不要使用下文的 OpenMA 地址。

连接自部署 Node

按 Node 自部署指南配置持久化、服务端密钥、隔离沙箱及所需凭据。使用包含适配层的源码构建，不要假定旧镜像已包含它。
在自己的 OpenMA Console 中创建 OpenMA API key，配置带有效模型凭据的 Model Card，再创建 Agent 和适合该运行时的环境。适配层不实现 Agent 创建，也不会导入 Moonshot 的资源和凭据。
将开关设置到服务进程环境并重启该 Node 服务。对于已完成常规配置的源码目录：

OMA_KIMI_KHA_COMPAT=1 pnpm --filter @open-managed-agents/main-node start

使用 Docker 时，将变量传入服务容器的 environment 配置；只在终端设置不会改变运行中的容器。原生 /v1/* 接口合同不变。

安装官方 KHA CLI。仓库中的 CLI 验证使用 kha 0.4.2。在另一个终端运行：

kha version
export KHA_BASE_URL="http://localhost:8787/kha"
export KIMI_API_KEY="oma_REPLACE_WITH_YOUR_OPENMA_API_KEY"

kha whoami
kha agents list
kha environments list

按需将 localhost 替换为自己的 Node 地址。Base URL 以 /kha 结尾，不是 /kha/v1，CLI 会追加 /v1。显式 --base-url 覆盖环境变量；显式 --profile 忽略环境变量中的地址和 key，因此这里不要传它。whoami 通过列举 Agent 检查访问权限，不返回 OpenMA 用户身份。不要将 OpenMA key 发给 Moonshot，也不要把 Moonshot key 当作 OpenMA 凭据。

使用已有 Agent 和环境 ID，并安装 jq：

export AGENT_ID="agent_REPLACE_WITH_EXISTING_ID"
export ENVIRONMENT_ID="env_REPLACE_WITH_EXISTING_ID"

session_id=$(kha sessions create \
  --agent "$AGENT_ID" --environment "$ENVIRONMENT_ID" -o json | jq -r '.id')
kha sessions send "$session_id" "概括任务并报告结果。" --wait
kha sessions events "$session_id"
kha artifacts list --session "$session_id"

真实执行需要可用模型和执行环境。产物列表可能为空，发送消息不保证生成文件。取得产物 ID 后可用 kha artifacts download "$ARTIFACT_ID" --out result.txt 下载；适配层提供当前会话输出，不提供不可变产物版本。

兼容性矩阵

范围	已实现子集	边界
Agent	列举、读取原生 Agent	不支持创建、更新、完整定义导入或写操作
环境	创建、列举、读取	使用 OpenMA 运行时配置；就绪状态不是 Moonshot 镜像构建遥测
会话	创建、列举、读取；每次追加一条文本消息	不具备完整多模态、资源覆盖或自定义工具结果输入能力
中断	运行中的会话接受 `user.interrupt`，返回 HTTP 202	接受不代表取消完成；没有 control epoch 隔离或持久暂停/恢复
历史与 SSE	会话、线程历史及可恢复游标	增量轮询原生日志；初次回放有界，不等同上游全部流式语义
线程	主线程及已观测到的子线程	原生日志投影，不是独立持久化的 Kimi 线程图
产物	列举、读取、下载当前原生输出	没有不可变版本快照；版本查询返回 400
未实现操作	明确返回错误	pending 输入检查及无消息 `/continue` 返回 501；无 worker 协议、计费、OAuth 或初始化脚本等价支持

SSE 接受 delta 请求，但只输出完整事件。空闲连接每秒轮询一次原生日志，初次回放最多扫描 10,000 行；不承诺 token delta 或快照隔离分页。游标与资源和过滤条件绑定，客户端应按事件 ID 去重，改变过滤条件时丢弃旧游标。

中断运行中的会话并等待取消完成后，可以发送新的普通输入。/continue 不会合成消息。即使 CLI 接受了命令或参数，这些边界仍然适用。

迁移清单

选择接口。 /kha/v1/* 仅用于上述子集；Agent 配置及未覆盖操作使用 OpenMA 原生 API。
重新配置资源。 在 OpenMA 配置模型凭据、Agent、环境、skills 和 MCP 连接。替换资源 ID，并检查路径和认证；只换 Base URL 不等于完成迁移。
显式映射原生工具。 Kimi 的 agent_toolset（名称 default_toolset_20260901）不同于 OpenMA 的 agent_toolset_20260401。原生 Agent 需检查 shell → bash、read_file → read、web_open_url → web_fetch。自定义 JSON schema 可能可复用，但执行和结果协议仍需检查。参见 Kimi 工具与 OpenMA 工具。
在原生配置中设置委派。 使用 multiagent.subagents.predefined_agents，不要使用已弃用的 callable_agents。对比文章提供完整配置示例。适配层的线程接口不会导入 Kimi 多智能体配置。
检查事件和输出。 切换流量前，按矩阵验证应用所需事件、中断和产物下载。Moonshot 原生 API 使用 include_deltas=true 开启实时 delta；本适配层仍只输出完整事件。

已验证到什么程度？

仓库记录了官方 CLI 0.4.2 对本地 fixture 的验证、路由与映射测试，以及使用真实认证和 SQLite 组合的权限隔离、持久化、产物与中断前置条件测试。Fixture 使用内存应用接口，不调用模型或运行真实 provider。这些结果不能证明与 Moonshot 线上服务完全等价，也不能证明通过适配层完成了真实 provider 执行。

可在仓库根目录启动无需凭据的协议演示：

pnpm --filter @open-managed-agents/main-node exec tsx scripts/kimi-kha-smoke-server.ts

该 fixture 使用端口 8799 和测试 key dummy，与上面的真实服务配置不同。完整命令、观测到的错误及实现限制见适配层验证记录。