close
OpenClaw Internals
  • 中文

      • 工具策略

      一句话概括

      工具策略系统通过 7 步级联策略管道过滤每次 LLM 调用可用的工具，直接控制 JSON schema 的 token 成本。

      职责

      • 通过 7 步策略级联过滤可用工具（profile → provider → global → agent → group）
      • 将插件工具组展开为单独的工具名称
      • 对子 agent 执行工具限制（按深度的硬编码拒绝列表）
      • 对安全敏感操作应用仅所有者工具策略
      • 对未知白名单条目（无匹配插件的插件工具）发出警告

      架构图

      关键源码文件

      文件行数角色
      src/agents/tool-policy-pipeline.ts108管道编排器：buildDefaultToolPolicyPipelineSteps()、applyToolPolicyPipeline()
      src/agents/tool-policy.ts205策略工具：buildPluginToolGroups()、expandPluginGroups()、stripPluginOnlyAllowlist()、normalizeToolName()
      src/agents/pi-tools.policy.ts315策略解析：resolveEffectiveToolPolicy()、resolveSubagentToolPolicy()、filterToolsByPolicy()、resolveGroupToolPolicy()

      Token 优化影响

      机制Token 节省详情
      Per-agent 白名单工具 token 的最多 80%限制 agent 仅使用需要的工具
      子 agent 拒绝列表子 agent 的约 30-50%嵌套 agent 的硬编码拒绝
      Provider 特定策略可变不同模型可能需要不同工具集

      量化影响

      24 核心工具 × 约 150 tokens/schema = 约 3,600 tokens
+ 插件工具（每个约 50-200 tokens）

限制策略（允许 10 个工具）：
  10 × 约 150 = 约 1,500 tokens（节省约 2,100）

子 agent 策略（6 个工具）：
  6 × 约 150 = 约 900 tokens（节省约 2,700）

      与其他模块的关系

      • 依赖：config/（策略配置）、plugins/（插件工具元数据）
      • 被依赖：agents/pi-embedded-runner/（每次 LLM 调用前调用管道）、system-prompt.ts（过滤后工具决定摘要章节）

      我的认知盲区

      • SUBAGENT_TOOL_DENY_ALWAYS 和 SUBAGENT_TOOL_DENY_LEAF 的精确工具列表
      • 工具 schema 是否有缓存还是每次调用重新生成
      • tools.alsoAllow — 警告中提到的增量插件工具启用
      • resolveGroupToolPolicy() 如何与渠道能力交互

      相关贡献

      • 暂无

      变更频率

      • tool-policy-pipeline.ts：低 — 7 步级联稳定
      • tool-policy.ts：低 — 工具函数很少变更
      • pi-tools.policy.ts：中 — 子 agent 限制和群组策略随功能演进