跳转至

Code Mode 访客 API

来宾运行时 API

以下 TypeScript 声明用于记录来宾 API。可执行单元格使用不带类型注解的纯 JavaScript。每个 exec 都会启动一个全新的 JavaScript 上下文:变量和函数绝不会延续到另一个单元格。wait 会恢复同一个单元格。

declare const catalog: ToolCatalog;
declare const MCP: Record<string, unknown>;
declare const namespaces: Record<string, unknown>;
declare const API: {
  list(prefix?: string): Promise<{
    files: Array<{ path: string; description?: string; bytes?: number }>;
  }>;
  read(path: string): Promise<{
    path: string;
    description?: string;
    content: string;
    bytes: number;
  }>;
};

declare function setTimeout(
  callback: (...args: unknown[]) => void,
  delay?: number,
  ...args: unknown[]
): number;
declare function clearTimeout(id: number): void;
declare function text(value: unknown): void;
declare function json(value: unknown): void;
declare function yield_control(reason?: string): Promise<void>;
declare function store(key: string, value: unknown): Promise<void>;
declare function load(key: string): Promise<unknown>;

API.read(path) 返回文件记录,而不是字符串。声明文本是 (await API.read(path)).content;例如,(await API.read("mcp/lab.d.ts")).content.match(/function\s+\w+/g)。

TextEncoder 和 TextDecoder 可用于本地文本和字节转换。在任一执行器下,编码器和解码器实例都能跨越 wait 保留。这些 API 提供本地字节转换,不提供文件系统、模块或网络访问。返回值仍使用仅 JSON 的桥接;应输出解码后的文本或字节值数组,而不是二进制附件。

console.log、console.info、console.warn、console.error 和 console.debug 通过同一有序输出通道输出诊断文本,该通道与 text 和 json 相同,而不是通过宿主日志。它们返回 undefined;console.error 不会抛出异常。非日志方法会在其消息前加上级别前缀,例如 [warn]。参数之间以空格分隔;printf 风格的标记(如 %s)保持字面量。未提供其他 Console API 方法。

Console 检查被有意限制,而不是 Node/浏览器控制台的模拟。字符串不加引号;对象和数组使用紧凑的 JSON 形式检查其可枚举自身属性,并包含 Error 的自身消息。它不会调用 getter 或自定义 toJSON 方法。循环引用、访问器、未 await 的 Promise 以及检查失败会获得诊断占位符。每次调用最多访问 100 个值、每个对象 50 个属性,以及四层对象层级。字符串值和键最多保留 512 个 UTF-16 码元;消息最多保留 4096 个码元,外加截断后缀,且不会拆分代理对。

在所有恢复过程中,console 条目还有一个保守的额外限制:16,384 个序列化 JSON UTF-16 码元(少于 49,152 个 UTF-8 字节)。一旦达到上限,单个 [console output truncated] 条目会替换下一条消息,后续的 console 调用将被忽略。现有的累计 maxOutputBytes 和模型结果上限仍然适用于 console 输出,并与 text、json 以及最终值或错误一起计算。当诊断检查不足时,请使用更窄输入显式调用 text/json。

来宾计时器通过宿主桥接,因此在任一执行器下都能跨越 wait 保留,并仍受 Code Mode 执行和延续限制约束。clearTimeout 还会取消在更早挂起之前创建的计时器;这适用于交互式 Code Mode 和无头自动化脚本。

每个有效的非 MCP 工具也会安装为异步全局函数。模型可见的 exec 描述包含最终可调用名称的有界确定性子集、紧凑输入提示以及受信任的声明输出提示。描述保持延迟,以便对抗性目录文本无法引导模型。当该索引遗漏某个工具时,调用 catalog.search(...);其结果是可调用函数。

每个快速索引行中的箭头描述可调用函数的值。-> Array<{ id: string }> 是声明的输出提示;-> ? 表示输出未知。对于未知输出,请原样返回值,或返回 await results.save(value) 以获取有界预览。在后续 exec 中过滤或映射之前,先观察原始值或预览;不要在同一程序中将猜测的字段输入依赖逻辑。当声明输出的读取馈送到最终的 -> ? 调用时,也适用此规则:返回或保存该最终原始值,不要将其包装在猜测的答案形状中。

results.load(id) 为当前回复中的后续单元格返回一个分离的 JSON 副本,results.delete(id) 释放容量。引用在该回复结束时过期;切勿复用之前轮次中的 id。对于稍后需要的小值,请使用 store。通过 API.read 读取 results.d.ts 以查看类型、限制和生命周期,或参阅 跨单元格复用数据。过大的最终对象和数组可能返回自动 value.reference,而不是不可恢复的显示前缀;使用其 id 配合 results.load。更大的预览会显示明确采样的路径、计数和观察到的形状。这些样本不是模式;在处理完整数据之前,请先加载原始值。

type ToolCatalogMetadata = {
  callableName: string;
  toolName: string;
  label?: string;
  description: string;
  source: "openclaw" | "client" | "mcp";
  apiPath?: string;
  input?: string;
  output?: string;
};

type ToolCatalogHandle = ((input?: unknown) => Promise<unknown>) &
  ToolCatalogMetadata & {
    describe(): Promise<ToolCatalogDescription | McpCatalogDescription>;
    toJSON(): ToolCatalogMetadata;
  };

返回 await catalog.search(...) 或 catalog.all() 会将每个可调用句柄序列化为此有界元数据。序列化不会调用 describe(),也不会启动另一个桥接请求;在同一程序内部,句柄仍保持可调用。

input 是常见情况下有界的 TypeScript 风格签名。当仍需要精确完整模式时,使用句柄的 describe()。客户端条目使用 input: "unknown",以便其不受信任的模式保持延迟,直到调用 describe()。output 仅当存在从受信任的 OpenClaw 核心或插件 outputSchema 派生的完整紧凑提示时才存在。MCP 和客户端输出模式声明不会被提升到此受信任目录提示中。

插件工具使用 source: "openclaw";没有单独的 "plugin" source 值。搜索包括可见的 MCP 工具,并使用与原生工具相同的排序和总结果限制。MCP 句柄具有 source: "mcp"、完全限定的 callableName(例如 MCP.accounting.listInvoices)、原始 MCP toolName,以及 apiPath(例如 mcp/accounting.d.ts)。其远程描述限制为 512 个 UTF-16 码元,且不拆分代理对;输入和输出提示仍然缺失。返回或发出 MCP 发现元数据时使用常规不可信内容包装器,即使未调用任何 MCP 工具。

MCP 句柄通过一个对象参数调用现有命名空间路径,包括其输入默认值、策略检查、审批以及原生 MCP 结果投影。它们的 describe() 返回精确工具的 $api(method, { schema: true }) 头部和模式。在选择 $api 声明时,规范化方法名优先于冲突的原始工具名。使用 (await API.read(handle.apiPath)).content 获取整个服务器的 TypeScript 声明。搜索也接受完全限定的 callableName。catalog.all() 继续只列出原生和客户端句柄;搜索不会将远程工具添加到该列表或可信快速索引中。

完整模式仅在需要时加载:

type ToolCatalogDescription = Omit<ToolCatalogMetadata, "toolName"> & {
  name: string;
  parameters: unknown;
  outputSchema?: unknown;
};

MCP 描述形状:

type McpCatalogDescription = {
  kind: "mcp_api";
  scope: "tool";
  server: { identifier: string; serverName: string };
  header: string;
  tools: unknown[];
  schemas: Record<string, unknown>;
  note: string;
};

目录辅助类型:

type ToolCatalog = {
  search(query: string, options?: { limit?: number }): Promise<ToolCatalogHandle[]>;
  all(): readonly ToolCatalogHandle[];
};

catalog.search(...) 返回可调用句柄的冻结数组;如果没有工具匹配,则返回空数组。如果匹配的可调用名称超出可用的程序数据收件箱容量,搜索会拒绝并给出缩小请求范围的指导。它绝不会静默替换为空或部分匹配列表。错误之后,更窄的搜索仍然可用。

精确的可调用拼写优先于不区分大小写的匹配。当启用的名称仅在大小写上不同时,使用句柄的 callableName 来查找同一工具。

已配对的 Gateway 节点可通过 nodes 全局对象使用:

const available = await nodes.list();
const node = await nodes.get(available[0].id);
const status = await node.invoke("device.status");

nodes.list() 返回已配对节点的 id、名称、平台、连接状态和已通告的命令。API 声明描述了这些字段和节点句柄方法。命令参数和结果保持为 unknown,因为每个节点命令都定义自己的负载;在组合它之前先检查结果。nodes.get(idOrName) 先解析精确 id,再解析显示名称,并返回包含 id、name 和 invoke(command, params?) 的句柄。调用使用常规的 nodes 工具路径,因此配对、命令策略、作用域、审批、超时、钩子和遥测均保持不变。仅当节点通告 fs.listDir 时,句柄才包含 listDir(path)。它不包含 exec:通用节点接口将 system.run 保留给带有节点主机的常规 shell exec 工具。

直接调用快速索引全局对象,或在需要查找时使用可调用目录句柄:

const content = await read({ path: "README.md" });

const [tool] = await catalog.search("...");
const result = await tool({ query: "OpenClaw" });

const [search] = await catalog.search("search the web", { limit: 1 });
const schema = await search.describe();
const hits = await search({ query: "OpenClaw code mode" });

调用原生全局对象或原生目录句柄会直接返回常规工具的 JSON details 值。当工具将其结果标记为 isError: true,且其 details 中没有非空的 message 或 error 字符串时,该值会包含工具的文本内容作为 message,以便来宾代码和模型能够看到调用失败的原因。MCP 句柄保留原生 MCP 结果(content、可选的 structuredContent 和可选的 isError)。精确目录 id 和原始 { tool, result } 信封对来宾不可见。

ls、find 和 grep 工具会在 content 中包含其有界的列表或搜索文本,包括空结果消息和截断通知。目录页面保留 nextAfter;搜索结果保留其现有的限制和截断元数据。

会话存储

使用 await store(key, value) 和 await load(key) 在同一会话的单元格和轮次之间保留小型 JSON 值,包括 Gateway 重启:

await store("shipmentSummary", { unpaid: 3, totalTons: 42 });

在后续的单元格或轮次中:

const summary = await load("shipmentSummary");
return summary;

键必须是非空字符串,最多 256 个字符;无效键会以 TypeError 拒绝。值使用常规桥接 JSON 规范化。每个序列化值最多可使用 256 KiB 的编码 JSON,所有存储值合计最多可使用 1 MiB。超出任一限制都会以 RangeError 拒绝,并保持存储不变。await store(key, undefined) 会删除一个键。await load(key) 在缺失时返回 undefined,否则返回一个分离副本;编辑该副本不会更改已保存的值。

写入按单元格缓冲。该单元格中后续的加载会看到其待处理写入,包括在 wait 之后。只有当单元格结算为 completed 时,写入才会对其他单元格可用。失败、超时、中止、过期或已释放的单元格会丢弃其待处理写入。如果持久化失败,单元格仍保持为已完成并带有警告,且运行的投影保持不变。在依赖该写入之前,请验证转录:持久提交之后仍可能发生追加错误。

会话转录拥有已提交值。分叉和分支仅继承其自身转录路径上的值;压缩会保留这些值。自定义存储条目不会进入模型上下文。加载网络派生数据时,其溯源信息会带入接收单元格的正常不可信内容包装器。

两个执行器都支持在具有绑定会话的交互式单元格中使用这些辅助函数。无头单元格和 restartSafe 单元格会拒绝存储操作,没有可用会话管理器的单元格也是如此。请阅读 API.read("results.d.ts") 了解契约。

读取分页文件数据

对于文本文件页面,read(...) 会在 content 中返回文件文本;文件名解析和分页通知保留在人类可读的工具显示中,而不是结构化文件数据中。现有的文件脱敏仍然适用。解析前检查 kind:"truncated" 表示在 continuation 处还有更多数据可用。使用相同的路径以及返回的 offset、可选的 cursor 和可选的 limit 读取下一页。使用 "\n" 连接行续接;直接追加游标续接。不要从文件数据中剥离显示通知模式:这些字符串可能是实际文件内容。每次调用仍会遵守其显式的 limit;如果仍有更多文件数据,结果将是 "truncated",其续接描述下一页。

本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw