跳转至

配置 — 内置工具设置

各个内置工具的设置。一次运行是否能够调用它们，由工具策略决定。

tools.exec

{
  tools: {
    exec: {
      backgroundMs: 10000,
      timeoutSeconds: 1800,
      cleanupMs: 1800000,
      approvalRunningNoticeMs: 10000,
      notifyOnExit: true,
      notifyOnExitEmptySuccess: false,
      commandHighlighting: false,
      applyPatch: {
        enabled: true,
        allowModels: ["gpt-6-astra"],
      },
    },
  },
}

除 applyPatch.allowModels 外，所示值均为默认值（默认情况下为空/未设置，表示任何兼容模型都可以使用 apply_patch）。当需要审批的 exec 运行时间过长时，approvalRunningNoticeMs 会发出运行中通知；0 可禁用它。

tools.exec.grantExpiryDays（默认未设置）为常设授权（standing grants）设置默认有效期（以天为单位，1–3650），这些授权由自动化审批中的 Always allow 操作签发。未设置时，授权将一直有效，直到被撤销或所属自动化的实质性定义发生变更；暂停并重新启用同一份定义不会撤销这些授权。条款在签发时即被固定，因此更改该值只会影响未来的授权；参见自动化常设授权。

tools.loopDetection

工具循环安全检查默认处于禁用状态。设置 enabled: true 即可启用检测。设置可在 tools.loopDetection 中全局定义，并在 agents.entries.*.tools.loopDetection 处按代理覆盖。

{
  tools: {
    loopDetection: {
      enabled: true,
    },
  },
}

tools.web

{
  tools: {
    web: {
      search: {
        enabled: true,
        provider: "brave", // optional; omit for auto-detect
        maxResults: 5,
        timeoutSeconds: 30,
        cacheTtlMinutes: 15,
      },
      fetch: {
        enabled: true,
        provider: "firecrawl", // optional; omit for auto-detect
        maxChars: 20000,
        maxCharsCap: 20000,
        maxResponseBytes: 750000,
        timeoutSeconds: 30,
        cacheTtlMinutes: 15,
        maxRedirects: 3,
        readability: true,
        userAgent: "custom-ua",
      },
    },
  },
  plugins: {
    entries: {
      brave: {
        config: {
          webSearch: { apiKey: "brave_api_key" }, // or BRAVE_API_KEY env
        },
      },
    },
  },
}

网络搜索提供商的凭据位于 plugins.entries.<plugin>.config.webSearch 之下，如 Brave 所示；参见网络搜索。所示的 tools.web 值均为默认值，但 provider 和 userAgent 除外。maxResponseBytes 会被限制在 32000–10000000 范围内；maxChars 会被限制在 maxCharsCap 以内（提高 maxCharsCap 可允许更大的响应）。

tools.media

配置对入站媒体内容（图像/音频/视频）的理解：

{
  tools: {
    media: {
      concurrency: 2,
      models: [
        { provider: "openai", model: "gpt-4o-mini-transcribe", capabilities: ["audio"] },
        {
          type: "cli",
          command: "whisper",
          args: ["--model", "base", "{{AttachmentPath}}"],
          capabilities: ["audio"],
        },
        { provider: "ollama", model: "gemma4:26b", capabilities: ["image"] },
        { provider: "google", model: "gemini-3-flash-preview", capabilities: ["video"] },
      ],
      audio: { enabled: true, preferredModel: "openai/gpt-4o-mini-transcribe" },
      image: { enabled: true, preferredModel: "ollama/gemma4:26b" },
      video: { enabled: true },
    },
  },
}

tools.media.models 是唯一已配置的模型列表。每个条目声明其处理的能力。可选的 preferredModel 选择器接受 provider/model、模型 ID、用于 provider 默认条目的 provider:<id>，或 cli:command；匹配的条目会移到该能力回退顺序的前端。对于已配置和自动检测到的模型，各能力对应的提示词、限制、请求设置、作用域、附件策略以及音频转写回显均保持默认值；模型条目可以覆盖特定于模型的字段。

媒体模型条目字段

Provider 条目（type: "provider" 或省略）：

  • provider：API 提供方 ID（openai、anthropic、google/gemini、groq 等）
  • model：模型 ID 覆盖项
  • profile / preferredProfile：已存储的认证配置文件选择

CLI 条目（type: "cli"）：

  • command：要运行的可执行程序
  • args：模板化参数（支持 {{AttachmentPath}}、{{AttachmentUrl}}、{{AttachmentContentType}}、{{AttachmentDir}}、{{AttachmentIndex}}、{{Prompt}}、{{MaxChars}} 等；openclaw doctor --fix 会将已弃用的 {input} 占位符迁移为 {{AttachmentPath}}）。较旧的 {{MediaPath}}、{{MediaUrl}}、{{MediaType}} 和 {{MediaDir}} 别名在兼容期内仍然可用，但现已弃用。

通用字段：

  • capabilities：包含 image、audio、video 中一个或多个的列表。
  • prompt、maxChars、maxBytes、timeoutSeconds、language：条目级覆盖值。
  • 当代理调用显式的 view_image 工具时，匹配的图像模型 timeoutSeconds 条目同样适用。对于图像理解，此超时适用于请求本身，不会因之前的准备工作而减少。
  • 失败时会回退到下一个条目。

Provider 认证遵循标准顺序：SQLite 认证配置文件 → 环境变量 → models.providers.*.apiKey。

tools.updatePlan

progress_card 的总开关——即用于跟踪较为复杂的多步骤工作的持久化计划与状态说明。

{
  tools: {
    updatePlan: false, // hide progress_card from every run
  },
}
  • 默认值：每个 provider 和模型均为 true。设置为 false 可保持该工具关闭；不存在模型特定的自动启用规则。
  • 该工具的描述要求模型保持计划为最新状态，最多使用一个 in_progress 步骤，并且仅在能提供步骤之外的信息时才添加 Markdown。
  • 在新的 tools.allow 和 tools.deny 策略中使用 progress_card。现有引用 update_plan 的策略会映射到 progress_card，因此随附的允许列表和拒绝列表仍保持原有含义。

旧版配置使用了 tools.experimental.planTool。运行 openclaw doctor --fix 可将该值迁移到 tools.updatePlan。

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