跳转至

工具策略

工具端钩子:参数重写、拦截、审批、exec 环境贡献以及转录持久化。属于 插件钩子 指南的一部分。

工具调用策略

before_tool_call 接收:

  • event.toolName
  • event.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.sessionKey
  • event.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