配置 — 内置工具设置
单个内置工具的设置。某次运行是否可以调用它们,由工具策略决定。
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.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 是用于非平凡多步骤工作跟踪的持久计划和状态备注。
- 默认:对所有提供商和模型均为
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