12.2 自定义工具：把副作用关进可控边界

自定义工具的难点不在“写一个函数”，而在“如何把副作用做成可控、可审计、可回滚的工程能力”。在 OpenClaw 中，插件负责引入工具能力，工具策略负责收敛可执行边界，多智能体与沙箱工具负责把高风险动作隔离在受控执行域。本节聚焦工具扩展的落地方法，强调配置层面的确定性约束与可验证的验收路径。

12.2.1 自定义工具的最小原则：输入可验证，输出可回放

将工具纳入系统之前，应先明确三项契约：

1. 输入约束：参数必须可验证，避免把“自由文本”直接作为高风险工具参数。

2. 输出约束：输出必须结构化，避免回注导致上下文膨胀。

3. 副作用边界：写操作必须具备幂等或对账路径，失败时必须给出人工核查步骤。

这些约束不依赖模型能力，属于工具设计的确定性底线。

12.2.2 把工具接入工具策略：分层规则与拒绝优先

工具治理应落在工具策略层。官方文档给出了工具的允许、拒绝与按渠道/群组分层限制机制，并强调拒绝规则优先：https://docs.openclaw.ai/tools。

下面示例展示了一个常见写法：默认禁止高风险写工具，仅在受控入口策略中按需放开。

{
  tools: {
    profile: 'coding',
    deny: ['shell.*', 'fs.write*', 'fs.delete*'],
  },
  channels: {
    webchat: {
      groups: {
        '*': {
          tools: { deny: ['shell.*'] },
        },
      },
    },
    ops: {
      groups: {
        '*': {
          tools: { deny: ['shell.*'] },
          toolsBySender: {
            'admin_user': { alsoAllow: ['sandbox.*', 'fs.write*'] },
          },
        },
      },
    },
  },
}

当某个请求触发了写工具但被拒绝时，日志应给出明确拒绝原因，便于追溯是策略拒绝还是参数不合法。

12.2.3 高风险工具的隔离执行：多智能体沙箱工具

对于涉及代码执行、文件写入或系统操作的高风险工具，建议配合多智能体沙箱工具将执行域隔离出来。官方文档给出了沙箱工具的能力边界与认证配置，并指出认证配置文件位于 ~/.openclaw/agents/<agentId>/agent/auth-profiles.json：https://docs.openclaw.ai/tools/multi-agent-sandbox-tools。

工程上建议采用“少数智能体拥有写能力”的模式：

1. 大多数入口智能体只允许读工具与诊断命令。

2. 少数运维智能体在明确入口与审计前提下允许沙箱写工具。

这与第7章的入口绑定与路由策略配合使用，可以把越权风险收敛到可计算范围。

12.2.4 验收与排障：先看策略加载，再看单次调用链

自定义工具上线后的验收建议固定为两步：

1. 配置验收：用 status --deep 确认 tools.deny 与 channels.*.groups.*.tools 限制已加载。

2. 行为验收：用结构化日志观察工具调用与拒绝事件，确保拒绝规则生效。

openclaw status --deep
openclaw logs --follow --json

如果发现工具被误允许，优先回到工具策略检查 deny 与渠道/群组级策略限制；如果发现工具执行失败，优先区分外部依赖故障与参数不合法，再决定是否允许有界重试。