Code Mode 输出
声明的输出契约¶
OpenClaw 工具可以为 AgentToolResult.details 中放置的结构化值声明 outputSchema。这对代码模式和工具搜索很有用;它不是提供商原生的工具响应模式,也不会改变直接工具暴露方式。
对于使用 defineToolPlugin 创建的工具,请在 parameters 旁边声明该模式:
import { Type } from "typebox";
import { defineToolPlugin } from "openclaw/plugin-sdk/tool-plugin";
const Shipment = Type.Object(
{
id: Type.String(),
paid: Type.Boolean(),
tons: Type.Number(),
},
{ additionalProperties: false },
);
export default defineToolPlugin({
id: "shipping",
name: "Shipping",
description: "Shipment tools.",
tools: (tool) => [
tool({
name: "shipping_list",
description: "List shipments.",
parameters: Type.Object({}),
outputSchema: Type.Array(Shipment),
execute: async () => loadShipments(),
}),
],
});
对于 api.registerTool(...) 或工厂工具,请将相同的 outputSchema 属性放在返回的 AnyAgentTool 对象上。
当前内置契约包括 agents_list、agents_wait、apply_patch、automations、conversations_list、conversations_send、conversations_turn、edit、openclaw、process、read、screen、sessions_history、sessions_list、sessions_search、sessions_send、session_status、suggest_task、terminal、web_fetch 和 web_search。automations 声明调度器状态、分页作业摘要、完整作业、运行历史和操作结果。当活动运行仍拥有其会话时,成功的移除可能包含 sessionCleanup: "pending"。该作业已被移除;会话清理在该运行结束时进行。process 声明会话列表、轮询和日志输出、输入确认及失败。在组合结果前,请通过 API.read("tools/automations.d.ts") 或 API.read("tools/process.d.ts") 阅读其声明。这些声明根据输入 action 选择输出:automations({ action: "list" }) 返回作业页面,而 action: "status" 返回调度器状态。进程列表仍包含其真实的失败结果;在读取 result.sessions 之前先检查 result.status === "failed"。声明式与普通自动化创建仍然是 add 可能产生的不同结果。
精确透传可以复用其所属协议的模式,而不是复制仅模型的契约。例如,会话工具公开 conversations.list、conversations.send 和 conversations.turn 所使用的相同 Gateway 结果模式;web_fetch 拥有工具本地模式,其提示公开稳定的元数据、文本、缓存状态和嵌套的溢出元数据;web_search 将其精确的规范化结果/答案/错误/原始联合声明为完整的快速索引提示。文件系统契约返回结构化的读取文本、图像、截断和可选未找到结果;显式编辑变更状态及差异/补丁数据;以及应用补丁的路径摘要。缺失的规范每日笔记(memory/YYYY-MM-DD.md)即使省略 optional,也会返回可选的 not_found 结果;其他缺失路径在未显式提供 optional: true 时会抛出异常。当快速索引声明了这些字段时,一个单元可以组合发现和投递,而无需单独的检查轮次:
const listed = await conversations_list({ query: "build bot" });
const target = listed.conversations.find((item) => item.label === "Build bot");
if (!target) throw new Error("conversation not found");
return await conversations_send({
conversationRef: target.conversationRef,
message: "Build finished.",
});
嵌套调用仍使用正常的工具策略、钩子和审批。如果完整契约是精确的,但超出有界快速索引的大小,它仍然可以通过可调用句柄的 describe() 获得,箭头保持 -> ?。
完整的原生工具声明也可按需通过 API.list("tools") 和 API.read("tools/<callableName>.d.ts") 获得,使用与发现相同的最终可调用名称。这些声明是根据有效输入和可信输出模式生成的,而非来自缩短的快速索引。原生列表条目包含路径;API.read 生成文件后,bytes 可用。文件不会急于注入到每个来宾 VM 中。未知输出和不支持的模式叶节点保持 unknown;客户端模式不会被提升为可信声明。对于 TypeScript 无法表达的约束,运行时验证仍然是事实来源。原生声明仅当有效模式接受运行时规范化所使用的空对象时,才允许省略输入参数;真正必需的输入仍然必需。
已知的输出声明描述完整的规范化工具值。程序数据准入会拒绝过大的回复,而不是替换为成功的截断标记。声明具有独立的大小、深度和遍历界限;当这些界限需要未知类型时,请对原始模式使用 describe()。读取声明不会执行工具或对单元进行类型检查;它们指导代理的 JavaScript 组合。
契约规则很严格:
- 描述精确的 JSON 兼容
details值,而非渲染的content块或提供方信封。 - 包含每个不抛出的成功或错误变体。当工具没有稳定的结构化结果时,省略
outputSchema。 - 使用
{ additionalProperties: false }闭合对象层,以获得完整的快速索引提示。开放、过大或其他不完整的模式仍可通过句柄describe()获得,但不能启用单轮字段使用。 - OpenClaw 在运行工具之前编译模式,然后在正常工具钩子之后、目录调用返回之前验证最终
details。无效模式无法运行工具;不匹配失败时不打印该值。 - 紧凑提示是确定性和有界的。当紧凑提示不足时,句柄
describe()暴露完整的可信模式。 - 已安装的插件代码已经是受信任的本地代码。远程 MCP 和客户端元数据仍然不受信任,不能选择使用这些快速索引提示。
插件编写细节请参阅 工具插件。
MCP 目录条目保留在生成的 MCP 命名空间下。面向任务的 catalog.search(...) 也会返回 MCP 句柄,这些句柄调用相同的命名空间路径并标识其声明文件。MCP 条目不会出现在裸全局变量、catalog.all() 和受信任的快速索引中。TypeScript 风格的声明文件可通过只读的 API 虚拟文件面获取,因此智能体无需将 MCP 模式添加到提示中即可检查 MCP 签名:
const files = await API.list("mcp");
const githubApi = await API.read("mcp/github.d.ts");
const issue = await MCP.github.createIssue({
owner: "openclaw",
repo: "openclaw",
title: "Investigate gateway logs",
});
const snapshot = await MCP.chromeDevtools.takeSnapshot({ output: "markdown" });
const resource = await MCP.docs.resources.read({ uri: "memo://one" });
const prompt = await MCP.docs.prompts.get({
name: "brief",
arguments: { topic: "release" },
});
(await API.read("mcp/<server>.d.ts")).content 包含从 MCP 工具元数据推断出的紧凑声明:
interface McpToolResult {
content: unknown[];
structuredContent?: unknown;
isError?: boolean;
}
interface McpResourcesListResult {
resources: unknown[];
nextCursor?: string;
}
interface McpResourcesReadResult {
contents: unknown[];
}
interface McpPromptsListResult {
prompts: unknown[];
nextCursor?: string;
}
interface McpPromptsGetResult {
messages: unknown[];
description?: string;
}
declare namespace MCP.github {
/** Return this TypeScript-style API header. */
function $api(toolName?: string, options?: { schema?: boolean }): Promise<McpApiHeader>;
/**
* Create a GitHub issue.
* @param owner Repository owner
* @param repo Repository name
* @param title Issue title
*/
function createIssue(input: {
owner: string;
repo: string;
title: string;
body?: string;
}): Promise<McpToolResult>;
}
字典输入保留其值类型。可空枚举和标记为 nullable: true 的字段包含 null,除非显式枚举排除了它。带默认值的顶层字段可以从调用中省略。这些声明近似于 JSON Schema;对于 TypeScript 无法表达的约束,请使用 MCP.<server>.$api("<tool>", { schema: true }) 检查原始模式。
MCP 工具调用返回其原始的 JSON 安全内容块,包括块注解和块级 _meta,以及(若提供)顶层 structuredContent 和 isError。顶层 MCP _meta 和私有应用元数据永远不会进入客体。带有 isError: true 的 MCP 应用故障仍会作为结果解析,因此客体代码可以检查并从中恢复。资源和提示操作则返回其原生 MCP 形状:resources.list() 返回 resources,resources.read() 返回 contents,prompts.list() 返回 prompts,prompts.get() 返回 messages 和可选的 description。
声明文件是虚拟的,不会写入工作区或状态目录。对于每次代码模式 exec 调用,OpenClaw 会构建运行作用域内的工具目录,保留可见的 MCP 条目,生成 mcp/index.d.ts 以及每个可见服务器对应的 mcp/<server>.d.ts,并将这个小型只读表注入所选执行器的工作进程中。客体代码只能看到 API 对象:API.list(prefix?) 返回带有文件元数据的 { files },API.read(path) 返回 { path, description, content, bytes }。content 字段保存声明文本。未知路径和 ./.. 路径段会被拒绝。
这样可以避免大型 MCP 模式进入模型提示:智能体从 exec 工具描述中得知虚拟 API 的存在,只读取所需的声明文件,然后使用一个对象参数调用 MCP.<server>.<tool>()。MCP.<server>.$api() 仍可作为程序内单工具模式响应的内联回退方案。
客体运行时永远不会直接看到宿主对象。输入和输出以 JSON 兼容的值通过桥接层传输,并带有显式的大小上限。
传递给 results.save 或 store 的工具参数和值必须能序列化为 JSON(store(key, undefined) 除外,它会删除该键)。BigInt 值、循环引用和抛错的序列化钩子会使相关调用失败,而不是静默替换其数据。请捕获错误并显式转换该值;已保存的结果保持不变。
依赖输入的输出¶
输出取决于某个字符串输入属性的工具,可以使用标准 TypeBox 或 JSON Schema API 对其现有 outputSchema 进行注解。从相同的变体中派生并集和映射:
import { Type } from "typebox";
const variants = Object.entries({
list: Type.Object({ items: Type.Array(Type.String()) }, { additionalProperties: false }),
status: Type.Object({ ready: Type.Boolean() }, { additionalProperties: false }),
});
const outputSchema = Type.Union(
variants.map(([, schema]) => schema),
{
"x-openclaw-input-discriminator": {
version: 1,
inputProperty: "action",
mapping: Object.fromEntries(variants.map(([value], index) => [value, index])),
},
},
);
将此模式赋给工具现有的 outputSchema 属性。每个分支必须包含该输入值的所有不抛错结果,包括失败情况。完整的并集和选择器来自这些相同的分支。该注解不会改变输入验证,也不会授权任何操作。
生成的声明会为字面量输入选择相应的结果。输入值的并集返回其结果的并集。缺失、宽泛或未映射的值保留完整的输出并集。该属性可以使用任意名称;action 是 automations 和 process 使用的约定。
目录执行在分发前会编译完整模式。当钩子更改选择器时,结果必须满足实际准备好的输入分支和原始调用方声明的分支。兼容的重写和默认/别名准备仍然有效;不兼容的结果无法到达面向原始操作的类型化代码。根 JSON Schema 约束保持不变。包含 $ref、$dynamicRef 或 $recursiveRef,或超出有界结构检查范围的模式,保留其原始的整体校验和声明。这保留了递归引用语义。生成的注释会标识这种保守的回退。操作声明也共享原始的 32,768 字符输出配额;超大的特化会回退到有界的整体声明。这些回退不会影响特定于操作的 automations 和 process 契约。
序列化模式包含普通 anyOf 分支和注解
x-openclaw-input-discriminator,其中包含 { version: 1, inputProperty, mapping }。
映射将字符串值与分支索引关联。请保持
联合和映射在一起;不要独立更新其中一个。SDK 静态元数据
和目录描述保留该注解。不支持它的宿主
保留普通联合。支持的宿主会在执行工具之前拒绝格式错误的注解和
不受支持的版本。不受支持的声明形状
保持为 unknown;注解不会绕过模式检查或类型限制。
输出 API¶
text(value)将人类可读的输出追加到output数组。json(value)在 JSON 兼容序列化之后追加一个结构化输出项。- 来宾代码最终返回的值会成为
completed结果中的value。
在发出异步值之前,或返回包含它们的数组或普通对象之前,
先等待这些值。未等待的 Promise 会显示为带有 await 和
Promise.all 指导的诊断字符串。例如,使用
return await Promise.all(handles.map((tool) => tool.describe())); 来返回工具描述。
输出序列化不会替你等待嵌套的 Promise。
已处理的 Error 值会在 text(...)、json(...) 以及返回的数组或
普通对象中保留其 name、message 和 JSON 兼容的可枚举自定义字段。
不会调用错误特定的 toJSON 方法。这包括来自
Promise.allSettled(...) 的拒绝原因。处理错误不会使单元格失败;
未捕获的错误仍会产生失败结果。
返回的值和 json(...) 输出会保留字面 JSON 键,例如
__proto__。数值类型的 TypedArray 会在索引 JSON 对象中保留其数值元素;
如果你想要 JSON 数组,请使用 Array.from(...)。最终返回的值
不会调用自定义 toJSON 方法。请显式转换特殊值,
例如返回 date.toISOString() 作为日期字符串。
最终值转换在单元格内运行。由属性 getter 创建的输出和工具调用 在单元格完成之前遵循普通的结算和挂起规则。
嵌套工具数据和模型可见输出具有独立的限制。成功的 桥接回复会以完整的规范化 JSON 值到达来宾,或者其 Promise 会以可捕获的程序数据资源错误拒绝。传输层 永远不会替换为成功的截断标记。这也适用于目录 发现和完整的适用技能说明:要么完整保留,要么明确拒绝。
每个单元格都有一个聚合的待回复收件箱,容量为
min(memoryLimitBytes, maxSnapshotBytes) 编码 UTF-8 字节:默认 10 MiB,
在现有配置限制下最高可达 256 MiB。成功值和
有界的工具错误在结算时、保留之前会消耗此配额。
该配额涵盖内联执行和每次等待;在宿主和工作进程释放已交付的回复后可重复使用,
而不是累计分页配额。
在饱和时,一个固定的、有界的失败诊断仍可在不保留工具数据的情况下使用;
这些控制回复受待处理调用槽位限制。
取消和过期会关闭准入并释放未交付的回复。
这是额外的逻辑宿主数据配额,不是总 RSS 限制,也不是 保证大型数据可以挂起。执行器内存限制和 QuickJS 整个 VM 快照限制仍然适用;工作进程交接和 JSON 转换可能临时保留额外副本。 在准入错误后,缩小或分页请求。
输出顺序与来宾调用匹配。累计来宾输出以及最终值
或失败诊断在所有等待中仍共享一个 maxOutputBytes 序列化 UTF-8 预算。
超大错误会保留其主要原因,并以
[error truncated] 结尾;截断不会将失败变为成功。对于
超过此预算的成功发出或返回输出,OpenClaw 会返回一个有界值,
其中包含 truncated: true、UTF-8 安全的 prefix、omittedBytes,以及使用更窄参数重新运行的指导。
将该标记视为成功的部分结果:
缩小搜索范围、分页、选择更少的文件,或返回更小的投影。
不可序列化的值会被转换为普通字符串或错误;
不支持二进制值。图像和文件通过普通
OpenClaw 工具传输,而不是通过代码模式桥接。
当后续单元格需要完整数据时,请返回 await results.save(value),
而不是发出该值。有界引用预览与完整保存的 JSON 是分开的;
results.load(id) 让后续代码无需重新获取即可选择更小的投影。
有关限制,请参阅
跨单元格重用数据。
引用在当前回复结束时过期;切勿重用之前轮次中的 id。
对于同一会话中跨轮次和重启所需的小型 JSON 值,请使用 await store(key, value) 和 await load(key);
请参阅
会话存储。
交互式 exec/wait 也会在其最终显示投影会截断超大最终对象或数组时
自动保留它。保存的结果使用 value: { truncated: true, reference, guidance },
并带有 results.save 返回的相同描述符。当发出输出争夺空间时,
其标识仍保持完整;预览文本和采样形状可能会缩小。
如果连标识都无法容纳,新的保存会被释放,并且完成结果会说明保留不可用。
容量或数据配额失败同样保留原始成功截断语义,
而不会驱逐较早的引用。小型值、普通字符串、发出输出、失败、无头执行和重启安全单元格
保留其普通输出行为。
标记前缀和省略字节数描述规范化后的原始紧凑 JSON, 包括数组括号、分隔符和 JSON 转义。普通输出增量交付。 未更改的累计摘要不会重复;新输出或更改的最终值/错误预留 可以生成同一原始输出的替换摘要。
面向模型的 exec 和 wait 结果也符合生效模型的每个结果上下文和持久化限制。OpenClaw 保留完整的结果封装,包括状态、续传、诊断、遥测和 JSON 格式化,在从保留的原始来源投影输出之前,使用相同的紧凑表示进行预算适配和投递。网络派生结果保留不可信内容封装及其更小的内容限制。这些限制不会减少嵌套工具的字节配额。无头执行和无模型上下文的低层控制保留其仅字节配额(对于网络派生控制输出,保留现有安全封装限制)。
这保护新结果;它不是归档 JSON 保证。后续的聚合缩减、缓存 TTL 修剪以及重放到更小模型仍可能缩短或替换历史工具文本。已发送的结果在普通续传期间保持不变。常规工具保留其自身的文本和图像格式:声明的输出模式描述 details,而不是模型可见文本。文件读取生产者在相同模型限制内为其精确的分页页脚预留空间,超大的技能指令会被拒绝,而不是静默地部分提供。
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw