工具策略
工具端钩子:参数重写、拦截、审批、exec 环境贡献以及转录持久化。属于 插件钩子 指南的一部分。
工具调用策略¶
before_tool_call 接收:
event.toolNameevent.params- 可选的
event.toolKind和event.toolInputKind,是宿主权威判别器,用于有意共享名称的工具;例如,外层代码模式exec调用使用toolKind: "code_mode_exec",并且对于接受的 Code Mode 输入包含toolInputKind: "javascript" - 可选的
event.derivedPaths,是宿主尽力推导的目标路径提示,适用于apply_patch等已知工具信封;这些路径可能不完整,或过度近似工具实际会触及的内容(例如,输入格式错误或输入不完整时) - 可选的
event.runId - 可选的
event.toolCallId - 上下文字段,例如
ctx.agentId、ctx.sessionKey、ctx.sessionId、ctx.runId、ctx.toolKind、ctx.toolInputKind,以及诊断用ctx.trace - 可选的
ctx.abortSignal,当所属工具调用被取消时会中止;处理器应将其传递给可取消的 I/O,并移除它们注册的任何监听器 - 可选的
ctx.requester,是发起当前消息运行的宿主推导请求者。它可以包含channel、accountId、senderId、senderIsOwner以及提供商原生的roleIds。缺失字段表示未证明,而非虚假保证;当策略要求时,应失败关闭。
它可以返回:
type BeforeToolCallResult = {
params?: Record<string, unknown>;
block?: boolean;
blockReason?: string;
requireApproval?: {
title: string;
description: string;
scope?: ApprovalScope;
severity?: "info" | "warning" | "critical";
timeoutMs?: number;
allowedDecisions?: Array<"allow-once" | "allow-always" | "deny">;
pluginId?: string;
onResolution?: (
decision: "allow-once" | "allow-always" | "deny" | "timeout" | "cancelled",
) => Promise<void> | void;
};
};
类型化生命周期钩子的守卫行为:
block: true是终态,并跳过较低优先级的处理器。block: false被视为未做决定。- 返回
params以重写宿主拥有的工具参数。每个处理器看到的是原始事件的隔离副本,而不是先前返回的重写。在请求审批之前,最后返回的params生效。 - 第一个
requireApproval生效,宿主会为其盖上插件 id。它会冻结所选参数快照:后续处理器可以拦截,但不能更改已批准的参数。 - 原生工具中继可能有更窄的契约。Codex 原生工具支持拦截和观察,但会拒绝参数重写;参见 Codex 钩子边界。
requireApproval会暂停代理运行,并通过插件审批询问用户。/approve可以同时批准 exec 和插件审批。在 Codex app-server 报告模式的原生PreToolUse中继中,这会委托给匹配的 app-server 审批请求;参见 Codex 运行时。- 较低优先级的
block: true仍可在较高优先级钩子请求审批后拦截。 onResolution接收已解决的决策:allow-once、allow-always、deny、timeout或cancelled。
例如,在 register(api) 内部添加以下内容,以便在宿主拥有的 exec 调用之前询问。before_tool_call 无需选择加入会话访问:
api.on(
"before_tool_call",
() => ({
requireApproval: {
title: "Run command",
description: "Allow this exec tool call?",
severity: "info",
timeoutMs: 60_000,
},
}),
{ matcher: ["exec"], priority: 50 },
);
单文件中的发送者感知策略¶
独立的插件文件可以将部署特定策略保留在代码中,而不是添加另一个配置模式。此示例为所有者提供所有工具,允许已配置的维护者使用保守的工具和消息操作集,并向已由通道配置授权的发送者公开 /fix:
import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";
const AGENT_ID = "maintenance-agent";
const MAINTAINER_SCOPES = [
{
channel: "discord",
accountId: "operations",
senderIds: new Set(["maintainer-user-id"]),
roleIds: new Set(["maintainer-role-id"]),
},
];
const MAINTAINER_TOOLS = new Set(["read", "web_fetch", "web_search", "session_status", "message"]);
const MAINTAINER_MESSAGE_ACTIONS = new Set(["react", "reply", "thread-create", "thread-reply"]);
export default definePluginEntry({
id: "maintenance-access",
name: "Maintenance access",
description: "Apply sender-aware tool policy to the maintenance agent.",
register(api) {
api.on("before_tool_call", (event, ctx) => {
if (ctx.agentId !== AGENT_ID) {
return;
}
const requester = ctx.requester;
if (requester?.senderIsOwner === true) {
return;
}
const maintainerScope = requester
? MAINTAINER_SCOPES.find(
(scope) =>
scope.channel === requester.channel && scope.accountId === requester.accountId,
)
: undefined;
const isMaintainer =
maintainerScope !== undefined &&
((requester?.senderId !== undefined && maintainerScope.senderIds.has(requester.senderId)) ||
requester?.roleIds?.some((roleId) => maintainerScope.roleIds.has(roleId)) === true);
if (!isMaintainer) {
return { block: true, blockReason: "Maintainer access required." };
}
if (event.toolName === "message") {
const action = typeof event.params.action === "string" ? event.params.action : "";
if (MAINTAINER_MESSAGE_ACTIONS.has(action)) {
return;
}
return { block: true, blockReason: `Owner required for message.${action || "unknown"}.` };
}
if (MAINTAINER_TOOLS.has(event.toolName)) {
return;
}
return { block: true, blockReason: `Owner required for ${event.toolName}.` };
});
api.registerCommand({
name: "fix",
description: "Ask the maintenance agent to investigate and fix an issue.",
acceptsArgs: true,
requireAuth: true,
handler: async (ctx) =>
ctx.agentId === AGENT_ID
? { continueAgent: true }
: { text: "This command is only available in the maintenance conversation." },
});
},
});
将该文件添加到 plugins.load.paths;默认混合重载模式会应用该更改:
{
agents: {
entries: {
"maintenance-agent": {
workspace: "~/.openclaw/workspace-maintenance",
},
},
},
bindings: [
{
agentId: "maintenance-agent",
match: {
channel: "discord",
accountId: "operations",
peer: { kind: "channel", id: "maintenance-channel-id" },
},
},
],
plugins: {
load: { paths: ["~/.openclaw/policies/maintenance-access.ts"] },
},
}
AGENT_ID 必须指定绑定到维护会话的代理。该绑定会为普通消息和 /fix 选择该代理;独立文件仍然是所有者与维护者工具策略的唯一负责人。编辑该文件本身后,运行 openclaw plugins reload maintenance-access。
requireAuth: true 会复用每个通道现有的发送者准入机制。对于 Discord,服务器或通道的 users/roles 允许列表可以授权维护受众。其他通道可以使用稳定的发送者 ID。随后,该钩子会在运行中的每次工具调用上应用更细粒度的逐工具决策,包括 Codex 原生 PreToolUse 调用。它可以否决模型可见的某个工具,但不能添加宿主省略的工具。现有的沙箱、执行审批、仅限所有者的核心工具以及通道策略仍然适用;该钩子不能越过它们授予权限。
如所示,将发送者和角色 ID 限定到确切的通道/账户对;两者都是提供商本地命名空间。保持允许列表保守。只有当部署的沙箱和审批策略使其安全时,才添加写入或执行工具。对于自动化或系统运行,需明确决定缺失的 ctx.requester 是否应通过;示例对限定范围的代理拒绝它。
有关审批路由、决策行为,以及何时使用 requireApproval 而不是可选工具或执行审批,请参阅 插件权限请求。
需要宿主级策略的插件可以使用 api.registerTrustedToolPolicy(...) 注册受信任的工具策略。它们会在普通 before_tool_call 钩子之前以及正常钩子决策之前运行。内置受信任策略最先运行;已安装插件的受信任策略按插件加载顺序接下来运行;普通 before_tool_call 钩子在它们之后运行。内置插件保留现有的受信任策略路径。已安装插件必须显式启用,并在 contracts.trustedToolPolicies 中声明每个策略 ID;未声明的 ID 会在注册前被拒绝。策略 ID 的作用域属于注册它的插件,因此不同插件可以复用相同的本地 ID。仅将此层级用于宿主受信任的关卡,例如工作区策略、预算执行或保留工作流安全。
受信任策略可以将 matcher 设置为 before_tool_call 接受的同一规范工具 ID 列表。省略 matcher 可保留匹配所有行为。
工具调用观察¶
after_tool_call 观察已经运行的工具调用。对于记录受控调用执行了什么内容的插件,它是 before_tool_call 的另一半。它接收与 before_tool_call 相同的上下文类型(PluginHookToolContext);可用的上下文字段取决于发出事件的执行框架。其事件包含:
event.toolName:工具名称。event.params:工具参数,包括来自before_tool_call的调整。- 可选
event.runId:所属运行标识符。 - 可选
event.toolCallId:工具调用标识符。 - 可选
event.result:由执行框架提供的工具结果。 - 可选
event.error:由执行框架提供或提取的错误消息。 - 可选
event.durationMs:在已知开始时间时的经过毫秒数。
type AfterToolCallEvent = {
toolName: string;
params: Record<string, unknown>;
runId?: string;
toolCallId?: string;
result?: unknown;
error?: string;
durationMs?: number;
};
这是一个观察钩子,因此它无法改变已经发生的事情:
- 处理程序并发运行,其返回值会被忽略。
- 抛出异常或超时的处理程序会被记录日志,执行继续。
matcher接受与before_tool_call相同的规范工具 ID 列表。
result 和 error 都是可选的,因此一个同时不包含二者的事件并不能证明工具成功。从 error 缺失推断成功的处理程序可能将失败的调用记录为成功;应将无法读取的结果视为未知,而不是视为任一结果。result 对 exec 和 bash 类工具承载的内容在 #102961 中单独跟踪。
不要使用此钩子来强制实施策略。正如 钩子参考 所述,应使用失败关闭的关卡,而不是假设观察或投递钩子在失败时会拒绝该操作。
执行环境钩子¶
resolve_exec_env 允许插件在命令运行前为 OpenClaw exec 工具调用提供环境变量。它不是针对每个执行框架原生 shell 的钩子。它接收:
event.sessionKeyevent.toolName,始终为"exec"event.host,为"gateway"、"sandbox"或"node"之一- 诸如
ctx.agentId、ctx.sessionKey、ctx.sessionId、ctx.messageProvider和ctx.channelId等上下文字段
返回一个 Record<string, string> 以合并到 exec 环境中。处理程序按优先级顺序运行;对于同一键,后面的结果会覆盖前面的结果。
钩子输出在合并前会经过宿主 exec 环境键策略过滤。PATH 始终会被丢弃(命令解析和安全 bin 检查依赖于它)。无效键以及危险宿主覆盖键,例如 LD_*、DYLD_*、NODE_OPTIONS、代理变量(HTTP_PROXY、HTTPS_PROXY、ALL_PROXY、NO_PROXY)和 TLS 覆盖变量(NODE_TLS_REJECT_UNAUTHORIZED、SSL_CERT_FILE 及类似项),会被丢弃。过滤后的插件环境变量会包含在 Gateway 审批/审计元数据中,并转发到 node-host 执行请求。
工具结果持久化¶
tool_result_persist 和 before_message_write 是同步钩子。不要将它们的处理程序设为 async:返回的 promise 会被忽略并带有警告。每个处理程序接收上一个处理程序返回的消息。tool_result_persist 返回 { message } 以替换工具结果;before_message_write 可以返回 { message } 或 { block: true } 以防止该转录写入。阻止持久化并不构成对工具执行的否决。
这些钩子作用于 OpenClaw 拥有的 transcript 写入。它们不会重写 Codex 原生工具记录;参见 Codex transcript 边界。
工具结果可以包含用于 UI 渲染、诊断、媒体路由或插件拥有的元数据的结构化 details。将 details 视为运行时元数据,而不是提示内容:
- OpenClaw 会在 provider 重放和压缩输入之前剥离
toolResult.details,以免元数据成为模型上下文。 - 持久化的会话条目仅保留大小受限的
details。超大的 details 会被替换为紧凑摘要和persistedDetailsTruncated: true。 tool_result_persist和before_message_write在最终持久化上限之前运行。保持返回的details尽量小,并避免将仅与提示相关的文本只放在details中;请将模型可见的工具输出放在content中。
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw