无极开物Docs
扩展 Kaiwu

Kaiwu 工具与操作

跨提供商使用统一的工具界面，支持内置 Kaiwu 操作、自定义 MCP 工具以及按需操作发现。

Kaiwu 提供统一的 Kaiwu tools 界面。

该界面涵盖：

  • Kaiwu 内置操作：如代码审查、制定计划、委托任务、切换会话模式、指定目标会话以及响应请求等
  • 自定义工具：来自你所配置的 MCP 服务器

你无需将其视为两套独立的系统。Kaiwu 会选用当前提供商所支持的最佳传输通道来交付这些工具。

Kaiwu 还对三个关联概念做了清晰划分：

  • 操作可用性（Action availability）：某个操作在特定界面上是否被允许使用。
  • 操作发现（Action discovery）：智能体或客户端能否通过 action_spec_search / action_spec_get 找到该操作，并通过 action_execute 执行它。
  • 直接工具暴露（Direct tool exposure）：该操作是否注册为独立的具名工具（例如 session_title_set）。

一项操作即便未作为直接工具暴露，也依然可以保持可用并支持动态发现。这种模式称为仅支持发现（discoverable-only）。

什么是“Kaiwu tools”

Kaiwu tools 是指智能体可以通过 Kaiwu 本身调用的各种操作和外部工具。

示例包括：

  • 启动审查运行
  • 启动用于计划或委托的子智能体
  • 将会话切换为提供商支持的模式（如 plan）
  • 响应 AskUserQuestion 或 Exit Plan Mode 请求
  • 调用自定义 MCP 工具，如 Playwright、GitHub 或 Context7

从用户视角来看，这是一个统一的产品界面：

  • 在设置 → MCP 服务器中配置工具
  • 预览会话将获取的内容
  • 在常规会话记录中查看生成的工具活动

原生 MCP 对比 Shell 桥接

不同的提供商接入工具的方式各有不同。

Kaiwu 支持两种交付模式：

原生 MCP

对于可直接消费 MCP 的提供商，Kaiwu 会将工具作为原生 MCP 工具注入。

目前支持原生 MCP 的提供商包括：

  • Claude
  • Codex
  • OpenCode
  • Gemini
  • Kiro
  • 提供原生 MCP 支持的自定义 ACP 提供商

Shell 桥接

对于能够执行 Shell 命令但无法直接使用原生 MCP 的提供商，Kaiwu 会通过 kaiwu tools CLI 桥接来暴露同一套工具界面。

目前采用 Shell 桥接的提供商包括：

  • Auggie
  • Qwen
  • Kimi
  • Kilo
  • Pi
  • Copilot

从用户端来看，两者的最终效果完全一致：

  • 提供商依然可以使用 Kaiwu 托管的工具
  • 会话记录依然正常展示 Kaiwu 工具活动
  • MCP 服务器配置依然在同一处完成

内置操作对比自定义 MCP 工具

Kaiwu tools 有意将以下两类工具融合在一起：

  • 基于 Kaiwu ActionSpec 的内置操作
  • 来自已配置 MCP 服务器的自定义 MCP 工具

内置操作

若要向智能体开放结构化的 Kaiwu 工作流，内置操作是最安全的方式。

示例包括：

  • review.start
  • subagents.plan.start
  • subagents.delegate.start
  • session.mode.set
  • session.permission.respond
  • session.user_action.answer
  • session.target.primary.set
  • session.target.tracked.set

这些操作都具备规范的定义：

  • ID
  • 输入提示
  • 示例
  • 选项来源

这意味着 Kaiwu 可以在以下场景中复用同一套权威数据源：

  • 应用启动器与表单
  • 语音工具
  • MCP 交付
  • CLI 桥接交付

对于会话智能体，大多数由第一方操作支持的工具默认设置为“仅支持发现”。会话只会获取一小组用于操作发现和泛型执行的直接引导工具，而更庞大的操作目录则保留在该引导路径中供按需取用。这样既能让提供商原生工具清单保持精简聚焦，又不会切断对 Kaiwu 工作流的访问。

自定义 MCP 工具

自定义 MCP 工具的配置方式与以往一致：

  • 在设置 → MCP 服务器中添加
  • 按设备和工作区划定作用域
  • 预览会话可见的工具

配置完成后，它们会与内置操作并入同一个 Kaiwu tools 界面。

“直接暴露 / 仅支持发现”的设置仅适用于由内置操作支持的工具。已配置的自定义 MCP 工具仍保留其常规的原生 MCP 交付行为，并在设置 → MCP 服务器中统一管理，除非后续另行引入独立的自定义工具发现路径。

交互界面与审批

各项内置操作均可按交互界面（即操作生效的场合）分别配置，例如：

  • 会话智能体
  • CLI（kaiwu session ... 与 kaiwu tools ...）
  • 外部 MCP 服务器（kaiwu mcp serve）
  • 语音工具

这些界面均由同一个操作目录驱动。因此，你可以在不为每个客户端单独构建操作体系的前提下，对某个界面的操作进行文档说明、开启审批或直接禁用。

对于敏感操作，你还可以将对应界面配置为需要审批（approval-gated）。

在应用中，该配置位于设置 → 操作。

操作被设置为需要审批后，调用方将无法直接执行。Kaiwu 会转而创建一条审批请求，并显示在收件箱中等待人工审查与执行。

支持工具调用的操作界面还拥有工具暴露选项：

  • 使用默认值：遵循 Kaiwu 针对该操作和界面的默认策略。
  • 仅支持发现：允许通过发现流程和 action_execute 调用，但不在该界面上注册具名的直接工具。
  • 直接工具：当该操作在此界面上启用时，将其注册为独立的具名工具。

暴露设置与审批模式相互独立。直接工具同样可以要求审批；同样地，仅支持发现的操作在通过 action_execute 执行时，也能触发审批流程。

用户指南：收件箱与审批

发现优先机制

Kaiwu 不再需要将庞大而固定的操作目录塞进每条提示词中。

智能体可以按需动态发现操作。

内置的发现流程如下：

  1. 搜索操作规格：当智能体明确目标但不知晓确切的操作 ID 时使用
  2. 获取操作规格：当需要查询确切的字段、示例与提示时使用
  3. 解析操作选项：当需要获取后端或会话模式等有效的动态参数值时使用
  4. 执行：使用校验通过的输入参数执行操作

这种机制减轻了提示词负载，同时确保可用工具界面始终与当前实际运行时保持一致。

这也是会话内智能体的默认运行姿态。由 Kaiwu 托管的审查、计划、委托以及运行启动操作均保持可被发现，但除非默认规则或你的设置将其指定为直接工具，否则它们不会出现在会话智能体的直接工具列表中。外部 MCP 客户端与 CLI 工作流在配置了对应工具的情况下，默认仍保留具名直接工具，以确保现有自动化流程正常运转。

具备可发现性并不代表获得选择 Kaiwu 托管委托的授权。对于常规的任务委托请求，若当前智能体自带原生子智能体或并行智能体功能，应优先使用该能力。仅在以下情况才去发现并启动 Kaiwu 托管运行：用户明确要求发起 Kaiwu 运行、Kaiwu 委托运行或 Kaiwu 子智能体；用户要求使用原生功能无法满足的其他智能体后端、模型提供商、模型、账户或服务；或者用户启用了强制要求 Kaiwu 的自定义规则。

这些选择所创建的对象截然不同：

  • 提供商原生子智能体：完全保留在当前智能体自身的委托系统内部，是处理常规并行任务的通用选择。
  • Kaiwu 托管执行运行：包含 Kaiwu 的审查、计划和委托子智能体。其启动、生命周期、会话记录访问及控制权限全部由 Kaiwu 接管。
  • 独立 Kaiwu 会话：通过 session.spawn_new 创建的顶级会话。这不属于常规委托，也不能取代子智能体运行。

启动与观测 Kaiwu 托管运行

对于会话内智能体调用的操作，sessionId 为选填项。将其省略即可将运行直接托管在当前发起调用的会话中。仅在明确需要指定另一处已授权会话时，才需传入具体的 sessionId；显式跨会话托管机制依然受支持。

在启动运行之前，请先检查其当前的操作规格，随后通过操作选项解析流程获取可选字段。规格说明与选项解析器是判定当前智能体目标、模型、配置、账户、关联服务以及所接受输入格式的唯一权威来源。这样可以避免依赖可能与当前安装版本不再匹配的操作配方或选项源名称。

等待仅用于观测状态。若限时等待发生超时，运行本身可能仍在活动中；超时既不会中止该运行，也不会将其判定为失败。仅当返回的提供商凭据明确将失败归类为可重试错误（例如特定类型的瞬态速率限制）时，方可重试。切勿将所有后端故障都视作偶发错误，也不要悄默声地切换到其他后端。

热路径操作

针对高频操作，Kaiwu 依然保留了轻量级的动态热路径。

该热路径并非硬编码的文档列表。它是依据规范的 ActionSpec 元数据及当前的暴露策略动态派生而来的。因此，当某项操作的语音/工具元数据或直接/发现设置发生变更时，热路径也会随之同步更新。

在实际使用中，这意味着审查、计划、委托、请求响应和会话定位等高频操作始终触手可及，而无需额外维护一套并行的注册表。

计划运行对比计划模式

这是两个在用户层面上完全不同的概念。

计划子智能体

当你需要 Kaiwu 启动独立的规划运行或计划型子智能体时，请使用启动计划运行（Start plan run）。

这会在智能体界面中创建并行任务。

会话模式

当你希望当前会话本身切换到提供商支持的特定模式（如 plan）时，请使用设置会话模式（Set session mode）。

这只会更改当前会话的模式，不会启动新的子智能体。

若提供商不支持会话模式，Kaiwu 便不会提供该控制项。

响应用户操作

Kaiwu 采用统一的通用响应路径来处理用户操作类请求。

覆盖的场景包括：

  • AskUserQuestion
  • ExitPlanMode
  • 提供商/运行时暴露的其他结构化用户操作请求

响应操作支持以下行为：

  • 批准
  • 拒绝
  • 请求修改
  • 返回结构化的问答对

这保证了请求处理逻辑在图形界面、语音以及智能体驱动的工作流中保持高度一致。

这些工具在产品中的呈现位置

应用内

在应用中，Kaiwu tools 会在以下位置展示：

  • 设置 → MCP 服务器
  • 会话中的 MCP 标签
  • 会话记录中的工具时间线
  • 子智能体相关操作对应的智能体界面
  • 启用语音时的语音交互界面

CLI

在命令行中，Kaiwu 提供：

kaiwu tools list

以及：

kaiwu tools call --session-id <session-id> --source Kaiwu --tool <tool-name> --args-json '<json>'

若要查看当前可用的内置及自定义工具界面，请使用 list。

若要直接调用某个内置 Kaiwu 工具或已配置的自定义 MCP 工具，请使用 call。

常见工作流

让智能体精准查找操作而非盲目猜测

请使用发现流程：

  1. 搜索操作目录
  2. 检查匹配的操作规格
  3. 如有需要，解析动态选项
  4. 执行该操作

在当前会话中启用规划能力

将会话切换至支持的模式（如 plan）。

仅当你需要并行规划任务而非改变当前会话模式时，才应使用计划子智能体。

跨不同提供商复用同一套工具配置

只需在 Kaiwu 中配置一次工具即可。

若提供商支持原生 MCP，Kaiwu 会直接采用；若不支持，Kaiwu 会在受支持的情况下自动切换为 Shell 桥接模式。

通过语音可靠执行结构化任务

语音界面可以使用 Kaiwu 其余模块通用的内置操作，包括：

  • 发现操作
  • 启动子智能体
  • 切换会话模式
  • 响应权限请求
  • 回答用户操作

这样能确保语音能力与常规应用界面及 CLI 保持一致，无需另行设计专属于语音的独立命令集。

相关页面

© 乾元执中（南京）科技有限公司 · WUJI-Labs

Kaiwu MCP（外部）

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

提示词、技能、模板与注册表

在 Kaiwu 中管理可复用的提示词内容，将其附加至智能体与配置文件，并安装或导出到您设备上的提供商原生位置。

On this page

什么是“Kaiwu tools”原生 MCP 对比 Shell 桥接原生 MCPShell 桥接内置操作对比自定义 MCP 工具内置操作自定义 MCP 工具交互界面与审批发现优先机制启动与观测 Kaiwu 托管运行热路径操作计划运行对比计划模式计划子智能体会话模式响应用户操作这些工具在产品中的呈现位置应用内CLI常见工作流让智能体精准查找操作而非盲目猜测在当前会话中启用规划能力跨不同提供商复用同一套工具配置通过语音可靠执行结构化任务相关页面