Kaiwu MCP（外部）

将 Kaiwu 作为外部 stdio MCP 服务器运行，以便编辑器和智能体能够启动/管理会话并执行 Kaiwu 操作。

MCP 包含两个交互方向，本文介绍其中之一：由外部程序驱动 Kaiwu。如果你希望为自己的 Agent 扩充更多工具，请参阅 MCP servers。

Kaiwu 可以运行自身的外部 MCP 服务，方便其他 MCP 宿主（如编辑器、Agent、自动化工作流）控制 Kaiwu：

列出并查看会话
启动、停止或归档会话
向会话发送消息
修改会话标题、权限模式或模型
启动执行任务（review / plan / delegate / voice agent）
执行任何已启用的 Kaiwu 操作（以操作规范为事实来源）

这与在 Kaiwu 内部管理的 MCP 服务（如 Playwright、GitHub 等）不同，后者请参阅 MCP servers。

外部 MCP 服务与桌面端 App、CLI、语音及会话 Agent 等各个界面共用同一个操作目录。每个操作可以：

在特定界面上可用，
通过 action_spec_search / action_spec_get 发现，
直接公开为专属的命名 MCP 工具。

这些属于独立的控制项。出于兼容性考虑，外部 MCP 和 CLI 界面默认保留直接命名的工具；而会话内 Agent 默认采用更精简、优先通过发现机制调用的直接工具集。

这种“直接公开 / 仅可发现”的暴露模型仅适用于 Kaiwu 原生操作支撑的工具。它不会把 Kaiwu 内部管理的 MCP 服务工具变成仅可发现；这些自定义工具仍由 Settings → MCP servers 进行控制。

授予的权限

kaiwu mcp serve 会使用 CLI 的已认证凭据，并以与 MCP 宿主进程相同的本地权限运行。配置宿主来生成该进程实质上是一次授权行为，而非单纯的连接设置。

该宿主可以执行已启用的 Kaiwu 操作，请求审批（对于无需审批的界面则立即执行），并访问当前账号权限内的所有会话。

请像对待 shell 配置文件一样对待 MCP 宿主的服务配置：任何能修改它的程序，都能以你的身份执行操作。

运行服务

外部 MCP 服务是一个 stdio 模式的 MCP 服务（设计上由 MCP 宿主负责启动）：

kaiwu mcp serve

kaiwu mcp start 可作为兼顾兼容性的别名使用。

如果正在接入新宿主，建议在配置中保留规范命令名 serve，以便后续协作者能一目了然地理解其意图。

针对支持推导“当前会话”的工具，你也可以选择设置默认的会话上下文：

kaiwu mcp serve --session <session-id>

配置 MCP 宿主

大多数 MCP 宿主允许通过指定 command 和 args 来配置服务。

配置示例如下：

{
  "mcpServers": {
    "kaiwu": {
      "command": "kaiwu",
      "args": ["mcp", "serve"]
    }
  }
}

注意事项：

请确保 kaiwu 位于 PATH 中，或者直接使用二进制文件的绝对路径——许多宿主运行时的 shell 环境与终端并不一致。运行 which kaiwu 即可获取可供粘贴的完整路径。
务必与实际使用的版本通道保持一致。 预览版或开发版的命令各不相同：kaiwu（稳定版）、hprev（预览版）、hdev（开发版）。给宿主配置了未实际使用的通道，往往会导致各种令人困惑的问题。
MCP 宿主必须运行在已完成 Kaiwu 认证的设备上，否则服务启动会报错 not_authenticated。
出于安全考虑，kaiwu mcp serve 不会读取用于指定服务器的环境变量（如 KAIWU_SERVER_URL）。如需连接非默认服务器，请在 args 中传入 CLI 服务器标志（见下文），或者在 CLI 主目录中切换当前的服务器配置文件。

指定特定服务器

如果 MCP 宿主支持，可以在配置的 args 中加入常规的 CLI 服务器选择标志：

{
  "mcpServers": {
    "kaiwu": {
      "command": "kaiwu",
      "args": ["--server", "company", "mcp", "serve"]
    }
  }
}

或者使用临时的 URL：

{
  "mcpServers": {
    "kaiwu": {
      "command": "kaiwu",
      "args": ["--server-url", "https://api.company.example", "--webapp-url", "https://app.company.example", "mcp", "serve"]
    }
  }
}

快速冒烟测试

若要验证服务接入是否正常，可以使用任意 MCP 宿主或 Inspector 连接以下配置：

command: kaiwu
args: ["mcp", "serve"]

接着优先测试会话控制类工具：

session_list
session_message_send
change_title
send_file_to_user
session_title_set
session_permission_mode_set

若上述工具工作正常，再测试通用调用路径：

action_spec_search
action_spec_get
action_execute

这样即可快速完成端到端校验，确认服务、账号认证、操作目录以及审批路由均已正常连通。

工具调用示例

具体的 JSON 结构取决于所使用的 MCP 宿主，但工具调用通常都会传入一个符合该工具输入模式（input schema）的 args 对象。

如果对工具包含哪些字段存疑，可以先使用发现类工具查询：

action_spec_get（用于查看 inputSchema、inputHints 及示例）
action_options_resolve（用于解析某个字段的有效选项）

列出会话

不传参数直接调用 session_list：

{}

发送消息（并等待空闲）

调用 session_message_send：

{
  "sessionId": "sess_123",
  "message": "ping",
  "wait": true,
  "timeoutSeconds": 60
}

可选覆盖项（需后端支持）：

permissionModeOverride
modelOverride（在适用情况下，可使用 null 清除覆盖配置）

等待会话变为空闲（不发送消息）

调用 session_wait_idle：

{
  "sessionId": "sess_123",
  "timeoutSeconds": 60
}

重命名会话

重命名当前或默认的会话上下文：

调用 change_title：

{
  "title": "Fix flaky tests"
}

通过 ID 或前缀重命名特定会话：

调用 session_title_set：

{
  "sessionId": "sess_123",
  "title": "Fix flaky tests"
}

把文件发给用户

把当前会话工作区里的一个文件发给用户。用户会在会话里看到一张文件卡片，可以直接预览或下载（端到端加密，走开物现有的文件通道）：

调用 send_file_to_user：

{
  "path": "reports/summary.pdf",
  "message": "本周报告，请查收"
}

path 是相对会话工作目录的路径；工作目录以外的路径、目录、不存在的文件、Windows 保留设备名都会被拒绝，并返回原因（access_denied / file_not_found / is_directory 等）。
单个文件上限 100MB（可用环境变量 HAPPIER_WEB_DOWNLOAD_MAX_BYTES 调整）。
该工具免审批；Claude、Codex、Gemini、OpenCode、Kilo 会话都可用。
旧版客户端不认识文件卡片时，会显示为普通工具调用，不会报错。

修改会话的权限模式

调用 session_permission_mode_set：

{
  "sessionId": "sess_123",
  "permissionMode": "read_only"
}

启动执行任务（plan/review/delegate/voice agent）

调用 execution_run_start 可以在会话中启动一个受 Kaiwu 托管的结构化任务。该调用需要提供 intent 以及后端目标。

示例：

{
  "sessionId": "sess_123",
  "intent": "plan",
  "backendTarget": { "kind": "builtInAgent", "agentId": "claude" },
  "instructions": "Plan a safe refactor and list risks."
}

后端目标决定由哪个提供商/后端来承载执行任务，它并非容量配额槽位。如果通过支持该结构的操作选择了多个后端目标，Kaiwu 会为每个选定的提供商/后端分别启动一个受管任务。

包含的工具

外部 MCP 界面包含以下两类工具的组合：

Kaiwu 操作工具（基于操作规范目录自动生成）
少量预置便捷工具（用于处理常用的控制平面操作）

常用会话控制工具示例：

session_list
session_status_get
session_message_send
session_stop
session_archive / session_unarchive
change_title（重命名当前/默认会话）
send_file_to_user（把工作区里的文件以文件卡片发给用户）
session_title_set
session_permission_mode_set
session_model_set
session_wait_idle

操作发现工具：

action_spec_search
action_spec_get
action_options_resolve

通用执行工具：

action_execute（通过 actionId 传入结构化 input 来执行任意已启用的操作）

执行任务工具：

execution_run_start

具体可用的工具集合取决于当前账号的启用状态、各界面的启用配置，以及操作在该界面中是被配置为直接工具还是仅可发现。详情请参阅“审批、启用与公开方式”。

会话上下文与工具变体

部分工具针对特定会话生效，而另一部分则作用于当前或默认会话。

默认会话（`--session`）与显式指定 `sessionId`

许多会话控制工具都支持显式传入 sessionId 参数。
如果工具支持自动推导会话，而你并未传入 sessionId，Kaiwu 会采用以下逻辑：
1. 优先使用在 kaiwu mcp serve 启动时传入的 --session ⟦K20⟧ 值（如果有）；
2. 否则使用全局“未选择会话”上下文（此时部分工具会报错 session_not_selected）。

为了保证自动化流程的行为确定性，建议显式传入 sessionId。

会话 ID 与前缀

当工具接收 sessionId 时，通常支持以下两种形式：

完整的会话 ID，或者
无歧义的前缀。

如果前缀匹配到了多个会话，工具调用将会失败，并返回候选会话列表。对于保存在 MCP 宿主配置中的持久设置，建议始终使用完整 ID。

修改标题：`change_title` 对比 `session_title_set`

重命名会话有两种常见方式：

change_title：便捷工具，仅接收 { "title": "..." }，用于重命名当前或默认的会话上下文。
session_title_set：基于 session.title.set 操作的原生工具，支持传入 sessionId 来重命名指定会话。

这两种方式都走同一个操作目录，并受制于同一套分界面策略（启用状态与审批配置）。

通用操作执行

外部 MCP 服务还提供了一个通用工具：

action_execute

适用于以下场景：

你已知悉确切的 actionId
想要调用的操作没有专属的命名工具
需要以编程方式管理审批凭据

调用格式：

{
  "actionId": "session.title.set",
  "input": {
    "sessionId": "sess_123",
    "title": "Fix flaky tests"
  }
}

注意事项：

actionId 为点分格式的标准 ID（例如：session.title.set）。
工具名称通常采用 snake_case 形式（例如：session_title_set），二者映射至同一个底层操作。

高级审批操作同样通过该路径调用，例如：

approval.request.create
approval.request.decide

这些审批操作虽已收录在操作目录中，但并未以独立的命名 MCP 工具形式公开。有使用需求时，请调用 action_execute。

审批、启用与公开方式

Kaiwu 将操作组织在一个统合目录中，可按不同的“界面”单独启用或禁用，涉及的界面包括：

会话 Agent（会话内工具）
语音
CLI
外部 MCP

在 App 内，可在如下位置进行配置：

Settings → Actions

针对每个“操作 + 界面”组合，你可以：

启用或禁用该操作
设定是否需要审批（门禁式审批执行）
为支持工具调用的界面选择是否直接公开为工具

如果某个工具设置了审批门禁，MCP 工具调用将返回 approval_request_created 载荷（其中包含 artifactId）。这一规则对通用的 action_execute 调用和内置别名（如 session_title_set）同样适用，因为它们遵循相同的操作与界面策略。你可以在 App 的收件箱中进行批准或拒绝，并查看最终执行结果：

以编程方式处理审批决定

如果希望 MCP 宿主直接管理审批，可以传入 approval.request.decide 调用 action_execute。

示例：

{
  "actionId": "approval.request.decide",
  "input": {
    "artifactId": "2765bc88-69ea-4316-9085-290ce5b3a3b6",
    "decision": "approve"
  }
}

该调用执行的审批对象与 App 收件箱中审核的对象完全相同。无论请求来源于 CLI、外部 MCP 宿主、会话 Agent 还是 Kaiwu 的其他界面，都遵循这套通用的审批模型。

直接工具公开

对于适用的原生操作工具，可在 Settings → Actions 中按界面设置工具的公开方式：

Use default：沿用 Kaiwu 对该操作及界面的默认配置。
Discoverable only：保留通过 action_execute 调用的能力，但从该界面移除专属命名的直接工具。
Direct tool：在操作已启用的前提下，直接将专属命名的工具公开出来。

如果你希望精简直接暴露的工具列表，同时又想保留通过发现机制和通用执行来调用操作的能力，这一配置非常有用。

故障排查

`not_authenticated`

请先完成 CLI 认证：

kaiwu auth login

如果要连接自托管服务器，请确保 MCP 宿主以正确的服务器配置文件（或服务器 URL 标志）启动 Kaiwu。详见 CLI → Server profiles。

`No daemon running` / 创建会话失败

在本地设备上启动并管理提供商进程（如创建会话、发送消息、附加连接等），通常需要该设备上正在运行 Kaiwu 守护进程。

如果工具调用失败并提示类似 No daemon running 的错误，请运行：

kaiwu daemon start

若想获得更顺畅的常驻运行体验（推荐），可将其安装为用户服务：

kaiwu daemon install

工具未显示

工具的可见性受操作规范目录及当前账号设置控制。请检查以下项目：

Settings → Actions（各界面的启用状态、审批设置以及“直接/仅可发现”公开方式）
Settings → MCP servers（如果你预期看到的是自定义 MCP 服务工具，而非 Kaiwu 原生操作工具）

如果某个操作在 MCP 界面上被设置为“仅可发现”，它将不会作为命名的直接工具出现。此时可以使用 action_spec_search、action_spec_get 和 action_execute 进行调用，或者将该操作的 MCP 公开设置修改为 Direct tool。

On this page