跳转至

配置 — 内置工具设置

单个内置工具的设置。某次运行是否可以调用它们,由工具策略决定。

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(默认未设置)为自动化审批中通过 Always allow 铸造的长期授权设置默认有效期,单位为天(1–3650)。未设置时,授权保持有效,直到被撤销或所属自动化的实质性定义发生变化;暂停并重新启用相同定义不会撤销它们。条款在铸造时冻结,因此更改该值只影响未来铸造的授权;参见自动化长期授权。

tools.loopDetection

滚动工具循环检测默认禁用。设置 enabled: true 可启用它。可以在 tools.loopDetection 中全局定义设置,并在 agents.entries.*.tools.loopDetection 中按 agent 覆盖。

独立地,即使 enabled 为 false,连续三次相同的工具错误也总会以记录的失败和恢复指导结束该轮。 参数或结果发生变化以及成功调用会重置该错误连续计数。 参见工具循环检测,了解独立的压缩后 守卫和滚动检测行为。

{
  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:<id>,或 cli:command;匹配的条目会移动到该能力回退顺序的前面。针对各能力的提示词、限制、请求设置、范围、附件策略和音频转录回显,对于已配置和自动检测的模型仍保持默认值;模型条目可以覆盖模型特定字段。

媒体模型条目字段

提供商条目(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:每个条目的覆盖项。
  • 匹配的图像模型 timeoutSeconds 条目在 agent 调用显式 view_image 工具时也会应用。对于图像理解,此超时应用于请求本身,不会因之前的准备工作而减少。
  • 失败会回退到下一个条目。

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

tools.updatePlan

progress_card 的紧急关闭开关,progress_card 是用于非平凡多步骤工作跟踪的持久计划和状态备注。

{
  tools: {
    updatePlan: false, // hide progress_card from every run
  },
}
  • 默认:对所有提供商和模型均为 true。设置为 false 可保持该工具关闭;没有针对特定模型的自动启用规则。
  • 工具描述会告知模型保持计划为最新状态,最多使用一个 in_progress 步骤,并且仅在 Markdown 能提供超出步骤本身的信息时才添加 Markdown。
  • 在新的 tools.allow 和 tools.deny 策略中使用 progress_card。现有策略中命名 update_plan 的会映射到 progress_card,因此已发布的允许列表和拒绝列表保持其原有含义。

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

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