服务 API

kimi web 启动的本地服务暴露两组程序化接口：REST API（/api/v1，另有 /api/v2/sessions）和 WebSocket 事件流（/api/v1/ws）。本页是这两组接口的协议参考；服务的启动方式与命令行选项见 kimi 命令，端到端的上手流程见本地服务与 API。

每个端点的完整请求 / 响应 schema 以服务自描述的规范文档为准：GET /openapi.json（OpenAPI）与 GET /asyncapi.json（AsyncAPI），两者都需要鉴权。

注意

本页描述的 REST 与 WebSocket API 为实验性特性：不保证接口稳定性，端点、字段与事件类型可能随版本随时更改。集成时请以当前版本服务的 /openapi.json 与 /asyncapi.json 为准。

基础约定

地址

默认地址 http://127.0.0.1:58627；端口被占用时自动 +1 重试（至多 100 次），可用 --port / --host 修改。同一 home 目录可并存多个实例，运行中的实例登记在 ~/.kimi-code/server/instances/。

鉴权

除以下例外，所有 /api/* 路径（含 /openapi.json 与 /asyncapi.json）都要求 bearer token：

OPTIONS 预检请求
GET /api/v1/healthz（探活）
静态 web 资源（非 /api/ 路径）

携带方式：REST 用 Authorization: Bearer <token> 请求头；WebSocket 升级请求可用同一请求头，或子协议 kimi-code.bearer.<token>。token 的生成与轮换见本地服务与 API：鉴权。

鉴权失败返回 HTTP 401，信封 code 为 40101。在非 loopback 绑定上，同一来源 60 秒内鉴权失败 10 次会被封禁 60 秒，期间一律返回 HTTP 429（code 为 42901）。

响应信封

所有 JSON 响应统一包在信封里：

json

{
  "code": 0,
  "msg": "success",
  "data": {},
  "request_id": "01JZX4A6E7M8V0R3Q0N2K2M5Q9"
}

code：业务结果，0 表示成功；错误码分段见下文。
data：成功时的业务数据。注意部分「错误」信封也携带非空 data——例如重复解决审批返回 40902 且 data.resolved 为 false——客户端应先判 code 再看 data。
request_id：本次请求的 ULID；客户端可用 X-Request-Id 请求头指定，非法值会被服务端重新生成。

HTTP 状态码几乎总是 200，业务结果以 code 为准。例外情况：

场景	HTTP 状态
鉴权失败 / 触发限流	401 / 429
创建供应商、导入供应商目录成功	201
删除供应商成功	204
二进制与流式端点	支持时返回 206（Range 分段）/ 304（ETag 未变），各端点能力不同，详见「二进制与流式端点」
`GET /api/v1/files/{file_id}` 下载错误	真实 404 / 500（响应体仍为信封）

其中 201 的响应体仍是标准信封（code 为 0），只是状态行遵循 REST 的资源创建习惯；204 按 HTTP 语义没有响应体，删除成功以状态码本身为准。

错误码

错误码按段位分组：

段位	含义	示例
`0`	成功
`400xx`	请求参数错误	`40001` 校验失败（`details` 逐字段说明）、`40003` 供应商由 OAuth 托管
`401xx`	鉴权与就绪状态	`40101` 未授权、`40110` 未配置供应商、`40113` 模型未解析
`404xx`	资源不存在	`40401` 会话、`40408` MCP 服务、`40409` 文件路径
`409xx`	状态冲突	`40901` 会话忙、`40902` 审批已解决、`40922` 分页条件与 `page_token` 不符
`410xx`	资源已过期	`41001` 审批超时、`41002` 提问超时、`41003` 临时文件过期
`413xx`	体积或边界超限	`41302` 读取文件超 10 MB、`41304` 路径越出会话目录
`429xx`	限流	`42901` 鉴权失败封禁、`42902` 文件监听数超限
`500xx`	服务端内部错误	`50001` 未捕获异常、`50003` 持久化失败
`6xxxx` / `7xxxx` / `8xxxx`	工具运行时 / LLM 供应商 / MCP 透传错误，`msg` 保留上游原文

分页

列表端点有两种分页风格：

游标式：before_id / after_id（互斥）加 page_size（1–100），响应为 { items, has_more }。用于会话列表、消息列表、转录等。
page_token：不透明令牌（内部绑定了查询条件指纹），用于 POST /api/v1/search 与 GET /api/v2/sessions。翻页途中改变任何查询条件会使令牌失效：v2 返回 40922，search 返回 40001。

REST 端点

按资源分组列出端点。路径里的 :{action} 是动作后缀约定——对单个资源 POST 到 路径:动作 执行非 CRUD 操作（如会话的 :fork、:archive）。

服务与元信息

方法与路径	说明
`GET /api/v1/healthz`	探活，免鉴权
`GET /api/v1/meta`	服务版本、能力集、`server_id`、实验开关等
`POST /api/v1/shutdown`	优雅退出（先回 200 再关闭）；仅 loopback 绑定时挂载

登录与用量

方法与路径	说明
`GET /api/v1/auth`	登录就绪状态快照
`POST /api/v1/oauth/login`	发起 OAuth device-code 登录流程
`GET /api/v1/oauth/login`	轮询登录流程状态
`DELETE /api/v1/oauth/login`	取消进行中的登录流程
`POST /api/v1/oauth/logout`	登出托管供应商
`GET /api/v1/oauth/usage`	查询套餐用量与限额
`GET /api/v1/oauth/userinfo`	查询账号资料

配置

方法与路径	说明
`GET /api/v1/config`	读取全局配置（密钥字段脱敏）
`POST /api/v1/config`	合并式更新配置，并广播 `event.config.changed`

模型与供应商

方法与路径	说明
`GET /api/v1/models`	列出已配置的模型别名
`POST /api/v1/models/{model_id}:set_default`	设置全局默认模型
`GET /api/v1/providers`	列出供应商
`POST /api/v1/providers`	创建供应商（201）
`GET /api/v1/providers/{provider_id}`	读取供应商（含已存密钥）
`PUT /api/v1/providers/{provider_id}`	整体替换供应商配置
`DELETE /api/v1/providers/{provider_id}`	删除供应商（204）
`POST /api/v1/providers/{provider_id}:refresh`	刷新该供应商的模型元数据
`POST /api/v1/providers:{action}`	集合级动作：`refresh` / `refresh_oauth` / `import_catalog` / `import_registry`
`GET /api/v1/catalog/providers`	浏览 models.dev 目录（服务端代理）
`GET /api/v1/catalog/providers/{catalog_id}`	读取目录中单个条目

会话

方法与路径	说明
`POST /api/v1/sessions`	创建会话（需 `workspace_id` 或 `metadata.cwd`）
`GET /api/v1/sessions`	列出会话，游标分页，支持 `busy` / `archived_only` 等过滤
`GET /api/v1/sessions/{session_id}`	读取单个会话
`GET /api/v1/sessions/{session_id}/profile`	读取会话档案
`POST /api/v1/sessions/{session_id}/profile`	更新标题、元数据、agent 配置
`POST /api/v1/sessions/{session_id}:{action}`	会话动作：`fork` / `compact` / `undo` / `abort` / `btw` / `archive` / `restore`
`GET /api/v1/sessions/{session_id}/children`	列出子会话
`POST /api/v1/sessions/{session_id}/children`	创建子会话（fork 并打标）
`GET /api/v1/sessions/{session_id}/status`	实时状态汇总
`GET /api/v1/sessions/{session_id}/goal`	当前目标快照（无则 `null`）
`GET /api/v1/sessions/{session_id}/warnings`	会话级告警
`POST /api/v1/sessions/{session_id}/export`	导出会话与诊断信息（zip 流，不走信封）
`GET /api/v1/sessions/{session_id}/snapshot`	客户端重建用全量快照（含 `as_of_seq` 与 `epoch`）

消息与转录

方法与路径	说明
`GET /api/v1/sessions/{session_id}/messages`	消息分页（`before_id` / `after_id` / `role`）
`GET /api/v1/sessions/{session_id}/messages/{message_id}`	读取单条消息
`GET /api/v1/sessions/{session_id}/transcript`	转录按轮次分页（需 `agent_id`），全局状态不分页随响应返回
`GET /api/v1/sessions/{session_id}/transcript/ops`	转录批次补漏（`since_seq`），`complete: false` 时需全量刷新
`GET /api/v1/sessions/{session_id}/transcript/user-messages`	各轮次的用户输入，不分页
`GET /api/v1/sessions/{session_id}/transcript/plan`	ExitPlanMode 计划内容、路径与审阅结果

提示词

方法与路径	说明
`GET /api/v1/sessions/{session_id}/prompts`	进行中与排队中的提示词
`POST /api/v1/sessions/{session_id}/prompts`	提交提示词（内容块数组，可带模型 / 权限模式等覆盖）
`POST /api/v1/sessions/{session_id}/prompts:steer`	把排队的提示词插入当前轮次
`POST /api/v1/sessions/{session_id}/prompts/{prompt_id}:abort`	中止进行中的提示词
`POST /api/v1/sessions/{session_id}/prompts/{prompt_id}:steer`	插入单个排队提示词

审批与提问

方法与路径	说明
`GET /api/v1/sessions/{session_id}/approvals`	列出审批请求（可按 `status=pending` 过滤）
`POST /api/v1/sessions/{session_id}/approvals/{approval_id}`	答复审批
`GET /api/v1/sessions/{session_id}/questions`	列出提问
`POST /api/v1/sessions/{session_id}/questions/{question_id}`	回答提问
`POST /api/v1/sessions/{session_id}/questions/{question_id}:dismiss`	忽略提问

后台任务

方法与路径	说明
`GET /api/v1/sessions/{session_id}/tasks`	列出后台任务
`GET /api/v1/sessions/{session_id}/tasks/{task_id}`	读取任务（可选输出预览）
`POST /api/v1/sessions/{session_id}/tasks/{task_id}:cancel`	取消任务

技能、工具与 MCP

方法与路径	说明
`GET /api/v1/sessions/{session_id}/skills`	会话级技能目录
`GET /api/v1/workspaces/{workspace_id}/skills`	无会话的工作区技能目录
`POST /api/v1/sessions/{session_id}/skills/{skill_name}:activate`	激活技能（开启一个轮次）
`GET /api/v1/tools`	列出当前生效 agent 的工具
`GET /api/v1/mcp/servers`	列出 MCP 服务
`POST /api/v1/mcp/servers/{mcp_server_id}:restart`	重启 MCP 服务

终端

PTY 终端接口，仅 loopback 绑定时挂载。

方法与路径	说明
`GET /api/v1/sessions/{session_id}/terminals`	列出终端
`POST /api/v1/sessions/{session_id}/terminals`	创建终端
`GET /api/v1/sessions/{session_id}/terminals/{terminal_id}`	读取终端（含回滚缓冲）
`POST /api/v1/sessions/{session_id}/terminals/{terminal_id}:close`	关闭终端

工作区

方法与路径	说明
`GET /api/v1/workspaces`	列出已注册工作区
`POST /api/v1/workspaces`	注册工作区（按根路径幂等）
`PATCH /api/v1/workspaces/{workspace_id}`	重命名
`DELETE /api/v1/workspaces/{workspace_id}`	注销（保留磁盘内容）
`GET /api/v1/workspaces/{workspace_id}/trust`	读取信任状态
`POST /api/v1/workspaces/{workspace_id}/trust`	授予信任
`POST /api/v1/workspaces/{workspace_id}/untrust`	撤销信任

文件系统

会话内文件操作为 POST /api/v1/sessions/{session_id}/fs:{action}，动作包括 list / read / list_many / stat / stat_many / mkdir / search / grep / git_status / diff / open / open-in / reveal，请求体为 JSON。另有：

方法与路径	说明
`POST /api/v1/workspace/fs:search`	无会话的工作区搜索（body 携带工作区引用）
`GET /api/v1/sessions/{session_id}/fs/{path}:download`	下载会话文件（二进制，见下文）
`GET /api/v1/fs:browse`	列出本机目录（文件夹选择器用）
`GET /api/v1/fs:home`	用户主目录与最近工作区
`GET /api/v1/fs:content`	读取本机任意文件原始字节（仅受 token 保护，谨慎暴露端口）
`POST /api/v1/fs:mkdir`	按绝对路径创建目录

文件上传

方法与路径	说明
`POST /api/v1/files`	multipart 上传（字段 `file`，可选 `name`、`expires_in_sec`），返回文件元信息
`GET /api/v1/files/{file_id}`	下载（二进制，错误用真实 HTTP 状态码）
`DELETE /api/v1/files/{file_id}`	删除

全局搜索与其他

方法与路径	说明
`POST /api/v1/search`	跨会话全文搜索，`mode` 为 `terms`（默认）或 `literal`（精确子串），`page_token` 分页
`GET /api/v1/connections`	列出当前在线的 WebSocket 连接
`GET /api/v2/sessions`	新一代会话列表，见下节
`/api/v1/debug/*`	反射式调试 RPC，仅 `--debug-endpoints` 且 loopback 时挂载，不属于稳定协议

`GET /api/v2/sessions`

面向列表页的新一代会话查询，筛选、排序、字段组都在查询参数里：

参数	说明
`workspace.id`	按工作区过滤，可重复
`activity.status`	按活动状态过滤：`running` / `approval` / `question` / `failed` / `idle`，可重复
`meta.updated_after`	只看该时间（epoch 毫秒）之后更新过的会话
`meta.archived`	`true` / `false`（默认）/ `all`
`sort`	`meta.updated_at_desc`（默认）/ `meta.updated_at_asc` / `meta.created_at_desc`
`include`	逗号分隔的附加字段组；目前支持 `git`（分支与 PR 信息，按目录去重并缓存 60 秒）
`page_size`	1–100，默认 50
`page_token`	上一页返回的翻页令牌

响应每项固定包含 workspace、meta、activity 三组，include=git 时附加 git 组。翻页令牌绑定首页查询条件，中途改条件返回 40922。

WebSocket 协议

建立连接

唯一端点是 ws://<host>:<port>/api/v1/ws，升级请求即完成鉴权（方式见上文「鉴权」）。连接建立后服务端立即发送 server_hello：

json

{
  "type": "server_hello",
  "timestamp": "2026-01-01T00:00:00.000Z",
  "payload": {
    "ws_connection_id": "conn_01JZX4...",
    "protocol_version": 2,
    "max_event_buffer_size": 1000,
    "capabilities": { "event_batching": false, "compression": false }
  }
}

注意服务端不发送心跳，也不会主动断开空闲连接——保活与重连由客户端自己负责。

控制帧

客户端发送 JSON 帧 { "type", "id"?, "payload" }；每个请求帧都会收到应答 { "type": "ack", "id", "code", "msg", "payload" }，code 为 0 表示成功。

帧	payload	说明
`subscribe`	`{ session_ids, cursors?, agent_filter? }`	订阅会话事件；带 `cursors`（每会话 `{seq, epoch}`）时回放错过的持久事件
`unsubscribe`	`{ session_ids }`	取消会话订阅
`subscribe_v2`	`{ session_id, transcript, transcript_since? }`	订阅转录流（唯一的转录订阅通道），`transcript` 按 agent 指定粒度
`unsubscribe_v2`	`{ session_id, agent_ids? }`	退订转录流；省略 `agent_ids` 表示整个会话
`watch_fs_add` / `watch_fs_remove`	`{ session_id, paths, recursive? }`	订阅 / 取消文件变更通知（`event.fs.changed`）
`client_hello`	`{ client_id }`	握手帧，其余字段为遗留兼容

事件

事件帧形状为 { "type", "seq", "epoch"?, "volatile"?, "offset"?, "session_id"?, "timestamp", "payload" }，type 即事件类型。按投递范围分两类：

全局事件：发送到每个已建立连接，无需订阅——session.meta.updated、event.session.created、event.session.work_changed、event.session.status_changed、event.workspace.*、event.config.*。
会话事件：只发给订阅了该会话的连接，受 agent_filter 过滤。主要事件族：

事件族	主要事件
轮次	`turn.started`、`turn.ended`、`turn.step.started` / `completed` / `interrupted` / `retrying`
流式文本	`assistant.delta`、`thinking.delta`（带 `offset` 用于对齐）
工具调用	`tool.call.started`、`tool.call.delta`、`tool.progress`、`tool.result`
交互	`event.approval.requested` / `resolved`、`event.question.requested` / `answered` / `dismissed`
子 Agent	`subagent.spawned` / `started` / `suspended` / `completed` / `failed`
后台	`task.started` / `terminated`、`shell.started` / `output` / `completed`
其他	`compaction.`、`skill.activated`、`goal.updated`、`prompt.`、`error`、`warning`

事件另分持久与易失两种：持久事件带严格递增的 seq，落盘并可回放；易失事件（各 *.delta、tool.progress、shell.* 等）标 volatile: true，不回放。消费易失文本流时用 offset（该轮次内的累计字符偏移）与本地已累积文本比对：小于本地长度说明是重复帧，大于说明有缺漏、需走快照恢复。

断线恢复

重连后在 subscribe 的 cursors 里带上每个会话最后应用事件的 {seq, epoch}，服务端会回放缺口；落后超过缓冲（1000 条）或游标失效时改为收到 resync_required。此时调用 GET /api/v1/sessions/{session_id}/snapshot 拿全量快照（含 as_of_seq 与 epoch），再以新游标重新订阅。

转录协议

subscribe_v2 的 transcript 按 agent 指定粒度：off / turn / block / delta（键 "*" 表示默认粒度），粒度越高推送越细。粒度非 off 的 agent 走两帧推送：transcript.reset（基线快照，历史经 REST 分页回读）和 transcript.ops（增量批次，带每个 agent 连续递增的 seq）；该 agent 的旧式事件在同一连接上被抑制，改由转录帧承载。断线时用 transcript_since 续传；服务端批次日志无法覆盖缺口时（REST 补漏返回 complete: false）需全量刷新。REST 侧对应 GET .../transcript（按轮次分页）与 GET .../transcript/ops?since_seq=（批次补漏）。

二进制与流式端点

以下端点返回二进制流而非 JSON 载荷，各端点的 HTTP 能力并不相同：

方法与路径	说明	Range 分段（206）	ETag / 304
`GET /api/v1/files/{file_id}`	下载已上传文件	支持	不支持（会发送 `etag` 头，但不处理 `If-None-Match`）
`GET /api/v1/sessions/{session_id}/fs/{path}:download`	下载会话工作区文件	支持	支持
`GET /api/v1/fs:content`	读取本机任意文件（仅受 token 保护，谨慎暴露端口）	支持	支持
`POST /api/v1/sessions/{session_id}/export`	导出会话与诊断信息（zip 流）	不支持	不支持

错误语义也不相同：GET /api/v1/files/{file_id} 对查找和存储失败返回真实 404 / 500 状态码（参数校验失败仍走 HTTP 200 信封），其余三个端点的所有失败都走标准响应信封——客户端在这三个端点上仍需检查信封中的 code。

下一步

本地服务与 API — 启动、鉴权与端到端调用流程
kimi 命令 — kimi web 的全部命令行选项

服务 API ​

基础约定 ​

地址 ​

鉴权 ​

响应信封 ​

错误码 ​

分页 ​

REST 端点 ​

服务与元信息 ​

登录与用量 ​

配置 ​

模型与供应商 ​

会话 ​

消息与转录 ​

提示词 ​

审批与提问 ​

后台任务 ​

技能、工具与 MCP ​

终端 ​

工作区 ​

文件系统 ​

文件上传 ​

全局搜索与其他 ​

GET /api/v2/sessions ​

WebSocket 协议 ​

建立连接 ​

控制帧 ​

事件 ​

断线恢复 ​

转录协议 ​

二进制与流式端点 ​

下一步 ​