[OpenClaw 文档]工具--内置工具

本文档汇总了 OpenClaw 官方文档站 工具 > 内置工具 子模块下的全部 12 篇内容，源自 docs.openclaw.ai/zh-CN。

📄 apply_patch 工具

原文：https://docs.openclaw.ai/zh-CN/tools/apply-patch

使用结构化补丁格式应用文件更改。它很适合多文件或多 hunk 编辑，在这些场景中单个 edit 调用会比较脆弱。

该工具接受单个 input 字符串，其中包装一个或多个文件操作：

*** Begin Patch
*** Add File: path/to/file.txt
+line 1
+line 2
*** Update File: src/app.ts
@@
-old line
+new line
*** Delete File: obsolete.txt
*** End Patch

参数

• input（必需）：完整补丁内容，包括 *** Begin Patch 和 *** End Patch。

说明

• 补丁路径支持相对路径（从工作区目录开始）和绝对路径。
• tools.exec.applyPatch.workspaceOnly 默认值为 true（限制在工作区内）。仅当你有意让 apply_patch 在工作区目录外写入/删除时，才将它设为 false。
• 在 *** Update File: hunk 中使用 *** Move to: 来重命名文件。
• *** End of File 在需要时标记仅 EOF 插入。
• 默认可用于 OpenAI 和 OpenAI Codex 模型。设置
  tools.exec.applyPatch.enabled: false 可禁用它。
• 可选择通过
  tools.exec.applyPatch.allowModels
  按模型设置门控。
• 配置仅位于 tools.exec 下。

示例

{
  "tool": "apply_patch",
  "input": "*** Begin Patch\n*** Update File: src/index.ts\n@@\n-const foo = 1\n+const foo = 2\n*** End Patch"
}

相关

用于变更呈现的只读 diff 查看器。


来自智能体的 shell 命令执行。


使用 xAI 的沙箱隔离远程 Python 分析。

📄 Brave 搜索

原文：https://docs.openclaw.ai/zh-CN/brave-search

此页面已移至 Brave Search。

相关

• Web 工具

📄 提升权限模式

原文：https://docs.openclaw.ai/zh-CN/tools/elevated

当智能体在沙箱内运行时，它的 exec 命令会被限制在沙箱环境中。提升模式允许智能体改为跳出沙箱，在沙箱外运行命令，并带有可配置的审批门禁。

提升模式只有在智能体沙箱隔离时才会改变行为。对于未沙箱隔离的智能体，exec 已经在主机上运行。

指令

使用斜杠命令按会话控制提升模式：

也可以使用 /elev on|off|ask|full。

发送不带参数的 /elevated 可查看当前级别。

工作原理

必须在配置中启用提升模式，并且发送者必须在允许列表中：

```json5
{
  tools: {
    elevated: {
      enabled: true,
      allowFrom: {
        discord: ["user-id-123"],
        whatsapp: ["+15555550123"],
      },
    },
  },
}
```

发送仅包含指令的消息来设置会话默认值：

```
/elevated full
```

或者内联使用它（仅应用于该消息）：

```
/elevated on run the deployment script
```

启用提升模式后，exec 调用会离开沙箱。有效主机默认为 gateway，或者当配置的/会话的 exec 目标为 node 时为 node。在 full 模式下，会跳过 exec 审批。在 on/ask 模式下，配置的审批规则仍然适用。

解析顺序

1. 消息上的内联指令（仅应用于该消息）
2. 会话覆盖（通过发送仅包含指令的消息设置）
3. 全局默认值（配置中的 agents.defaults.elevatedDefault）

可用性和允许列表

• 全局门禁：tools.elevated.enabled（必须为 true）
• 发送者允许列表：tools.elevated.allowFrom，按渠道列出
• 每智能体门禁：agents.list[].tools.elevated.enabled（只能进一步限制）
• 每智能体允许列表：agents.list[].tools.elevated.allowFrom（发送者必须同时匹配全局 + 每智能体）
• Discord 回退：如果省略 tools.elevated.allowFrom.discord，则使用 channels.discord.allowFrom 作为回退
• 所有门禁都必须通过；否则提升模式会被视为不可用

允许列表条目格式：

提升模式不控制什么

• 工具策略：如果工具策略拒绝 exec，提升模式无法覆盖它。
• 主机选择策略：提升模式不会把 auto 变成不受限制的跨主机覆盖。它使用配置的/会话的 exec 目标规则，只有当目标已经是 node 时才选择 node。
• 独立于 /exec：/exec 指令会为授权发送者调整每会话 exec 默认值，并且不需要提升模式。

bash 聊天命令（! 前缀；/bash 别名）是一个单独门禁，除了它自己的 tools.bash.enabled 标志外，还要求启用 tools.elevated。禁用提升模式也会锁定 ! shell 命令。

相关内容

来自智能体的 Shell 命令执行。


exec 的审批和允许列表系统。


Gateway 网关级沙箱配置。


三个门禁在工具调用期间如何组合。

📄 Exec 工具

原文：https://docs.openclaw.ai/zh-CN/tools/exec

在工作区中运行 shell 命令。exec 是一个可变更的 shell 表面：只要所选主机或沙箱文件系统允许，命令就可以创建、编辑或删除文件。禁用 OpenClaw 文件系统工具（例如 write、edit 或 apply_patch）不会让 exec 变成只读。

通过 process 支持前台 + 后台执行。如果不允许使用 process，exec 会同步运行，并忽略 yieldMs/background。
后台会话按智能体限定范围；process 只能看到同一智能体的会话。

参数

要运行的 Shell 命令。

命令的工作目录。

键/值环境覆盖项，会合并到继承的环境之上。

在此延迟（毫秒）后自动将命令转入后台。

立即将命令转入后台，而不是等待 yieldMs。

覆盖本次调用配置的 exec 超时时间。仅当命令应在没有 exec 进程超时限制的情况下运行时，才设置 timeout: 0。

可用时在伪终端中运行。用于仅支持 TTY 的 CLI、编码智能体和终端 UI。

执行位置。auto 会在沙箱运行时处于活动状态时解析为 sandbox，否则解析为 gateway。

普通工具调用会忽略此项。gateway / node 的安全性由
tools.exec.security 和 ~/.openclaw/exec-approvals.json 控制；提升模式只有在操作员明确授予提升访问权限时，才能强制 security=full。

gateway / node 执行的审批提示行为。

当 host=node 时使用的节点 id/名称。

请求提升模式 — 逃逸沙箱并进入配置的主机路径。只有当 elevated 解析为 full 时，才会强制 security=full。

注意事项：

• host 默认为 auto：当会话的沙箱运行时处于活动状态时使用沙箱，否则使用 Gateway 网关。
• host 只接受 auto、sandbox、gateway 或 node。它不是主机名选择器；类似主机名的值会在命令运行前被拒绝。
• auto 是默认路由策略，不是通配符。从 auto 可以按调用使用 host=node；只有在没有沙箱运行时处于活动状态时，才允许按调用使用 host=gateway。
• 没有额外配置时，host=auto 仍然可以“直接工作”：没有沙箱意味着它解析为 gateway；有实时沙箱意味着它留在沙箱中。
• elevated 会逃逸沙箱并进入配置的主机路径：默认是 gateway，或者当 tools.exec.host=node（或会话默认值为 host=node）时是 node。它仅在当前会话/提供商启用提升访问权限时可用。
• gateway/node 审批由 ~/.openclaw/exec-approvals.json 控制。
• node 需要已配对的节点（配套应用或无头节点主机）。
• 如果有多个节点可用，请设置 exec.node 或 tools.exec.node 以选择一个。
• exec host=node 是节点的唯一 shell 执行路径；旧版 nodes.run 包装器已移除。
• timeout 适用于前台、后台、yieldMs、Gateway 网关、沙箱以及节点 system.run 执行。如果省略，OpenClaw 会使用 tools.exec.timeoutSec；显式的 timeout: 0 会禁用该调用的 exec 进程超时。
• 在非 Windows 主机上，exec 会在设置了 SHELL 时使用它；如果 SHELL 是 fish，它会优先使用 PATH 中的 bash（或 sh）
  以避免与 fish 不兼容的脚本，然后在两者都不存在时回退到 SHELL。
• 在 Windows 主机上，exec 优先发现 PowerShell 7（pwsh）（Program Files、ProgramW6432，然后是 PATH），
  然后回退到 Windows PowerShell 5.1。
• 主机执行（gateway/node）会拒绝 env.PATH 和加载器覆盖项（LD_*/DYLD_*），以
  防止二进制劫持或注入代码。
• OpenClaw 会在派生的命令环境中（包括 PTY 和沙箱执行）设置 OPENCLAW_SHELL=exec，这样 shell/profile 规则就可以检测 exec 工具上下文。
• openclaw channels login 会被 exec 阻止，因为它是交互式频道认证流程；请在 Gateway 网关主机上的终端中运行它，或者在存在频道原生登录工具时从聊天中使用该工具。
• 重要：沙箱隔离默认关闭。如果沙箱隔离关闭，隐式 host=auto
  会解析为 gateway。显式 host=sandbox 仍会失败关闭，而不是静默
  在 Gateway 网关主机上运行。启用沙箱隔离，或使用带审批的 host=gateway。
• 脚本预检（针对常见 Python/Node shell 语法错误）只检查有效 workdir 边界内的文件。如果脚本路径解析到 workdir 之外，
  则会跳过该文件的预检。
• 对于现在开始的长时间运行工作，启动一次即可，并在启用自动
  完成唤醒且命令发出输出或失败时依赖它。
  使用 process 查看日志、状态、输入或进行干预；不要用
  sleep 循环、timeout 循环或重复轮询来模拟调度。
• 对于应在稍后或按计划发生的工作，请使用 cron，而不是
  exec sleep/延迟模式。

配置

• tools.exec.notifyOnExit（默认值：true）：为 true 时，转入后台的 exec 会话会在退出时入队一个系统事件并请求 Heartbeat。
• tools.exec.approvalRunningNoticeMs（默认值：10000）：当受审批限制的 exec 运行时间超过此值时发出一次“running”通知（0 表示禁用）。
• tools.exec.timeoutSec（默认值：1800）：默认的每命令 exec 超时时间，单位为秒。按调用的 timeout 会覆盖它；按调用的 timeout: 0 会禁用 exec 进程超时。
• tools.exec.host（默认值：auto；当沙箱运行时处于活动状态时解析为 sandbox，否则解析为 gateway）
• tools.exec.security（默认值：沙箱为 deny，未设置时 Gateway 网关 + 节点为 full）
• tools.exec.ask（默认值：off）
• 无审批主机 exec 是 Gateway 网关 + 节点的默认行为。如果你想要审批/允许列表行为，请同时收紧 tools.exec.* 和主机 ~/.openclaw/exec-approvals.json；请参阅 Exec approvals。
• YOLO 来自主机策略默认值（security=full、ask=off），而不是来自 host=auto。如果你想强制 Gateway 网关或节点路由，请设置 tools.exec.host 或使用 /exec host=...。
• 在 security=full 加 ask=off 模式下，主机 exec 会直接遵循配置的策略；没有额外的启发式命令混淆预过滤器或脚本预检拒绝层。
• tools.exec.node（默认值：未设置）
• tools.exec.strictInlineEval（默认值：false）：为 true 时，内联解释器 eval 形式（例如 python -c、node -e、ruby -e、perl -e、php -r、lua -e 和 osascript -e）始终需要显式审批。allow-always 仍可持久保存良性的解释器/脚本调用，但内联 eval 形式每次仍会提示。
• tools.exec.commandHighlighting（默认值：false）：为 true 时，审批提示可以在命令文本中突出显示由解析器推导出的命令范围。全局或按智能体设置为 true，即可启用命令文本高亮，而不改变 exec 审批策略。
• tools.exec.pathPrepend：要为 exec 运行前置到 PATH 的目录列表（仅限 Gateway 网关 + 沙箱）。
• tools.exec.safeBins：仅 stdin 的安全二进制文件，可在没有显式允许列表条目的情况下运行。行为详情请参阅 Safe bins。
• tools.exec.safeBinTrustedDirs：用于 safeBins 路径检查的额外显式信任目录。PATH 条目永远不会自动受信任。内置默认值是 /bin 和 /usr/bin。
• tools.exec.safeBinProfiles：每个安全二进制文件的可选自定义 argv 策略（minPositional、maxPositional、allowedValueFlags、deniedFlags）。

示例：

{
  tools: {
    exec: {
      pathPrepend: ["~/bin", "/opt/oss/bin"],
    },
  },
}

PATH 处理

• host=gateway：将你的登录 shell PATH 合并到 exec 环境中。主机执行会
  拒绝 env.PATH 覆盖项。守护进程本身仍使用最小化 PATH 运行：
• macOS：/opt/homebrew/bin、/usr/local/bin、/usr/bin、/bin
• Linux：/usr/local/bin、/usr/bin、/bin
• host=sandbox：在容器内运行 sh -lc（登录 shell），因此 /etc/profile 可能会重置 PATH。
  OpenClaw 会通过内部环境变量（无 shell 插值）在 profile 加载后前置 env.PATH；
  tools.exec.pathPrepend 也适用于此处。
• host=node：只会把你传入的未被阻止的环境覆盖项发送到节点。主机执行会
  拒绝 env.PATH 覆盖项，节点主机也会忽略它们。如果你需要在节点上添加额外 PATH 条目，
  请配置节点主机服务环境（systemd/launchd），或将工具安装到标准位置。

按智能体绑定节点（在配置中使用智能体列表索引）：

openclaw config get agents.list
openclaw config set agents.list[0].tools.exec.node "node-id-or-name"

控制 UI：Nodes 选项卡包含一个小型“Exec node binding”面板，用于相同设置。

会话覆盖项（/exec）

使用 /exec 设置 host、security、ask 和 node 的按会话默认值。
发送不带参数的 /exec 可显示当前值。

示例：

/exec host=auto security=allowlist ask=on-miss node=mac-1

授权模型

/exec 仅对授权发送者生效（频道允许列表/配对加 commands.useAccessGroups）。
它只更新会话状态，不会写入配置。要硬性禁用 exec，请通过工具
策略拒绝它（tools.deny: ["exec"] 或按智能体设置）。主机审批仍会适用，除非你显式设置
security=full 和 ask=off。

Exec 审批（配套应用 / 节点主机）

沙箱隔离的智能体可以要求在 exec 运行于 Gateway 网关或节点主机之前进行逐请求审批。
有关策略、允许列表和 UI 流程，请参阅 Exec approvals。

需要审批时，exec 工具会立即返回
status: "approval-pending" 和一个审批 id。审批通过（或拒绝/超时）后，
Gateway 网关会发出系统事件（Exec finished / Exec denied）。如果命令在
tools.exec.approvalRunningNoticeMs 之后仍在运行，则会发出一次 Exec running 通知。
在带有原生审批卡片/按钮的渠道中，智能体应优先依赖该
原生 UI，并且只有当工具结果明确表示聊天审批不可用或手动审批是
唯一路径时，才包含手动 /approve 命令。

允许列表 + 安全二进制文件

手动允许列表强制执行会匹配解析后的二进制路径 glob 和裸命令名称
glob。裸名称只匹配通过 PATH 调用的命令，因此当命令是 rg 时，rg 可以匹配
/opt/homebrew/bin/rg，但不能匹配 ./rg 或 /tmp/rg。
当 security=allowlist 时，只有每个管道
段都在允许列表中或是安全二进制文件时，shell 命令才会被自动允许。链接（;、&&、||）和重定向
在允许列表模式下会被拒绝，除非每个顶层段都满足
允许列表（包括安全二进制文件）。重定向仍不受支持。
持久的 allow-always 信任不会绕过该规则：链式命令仍要求每个
顶层段匹配。

autoAllowSkills 是 exec 审批中的一个独立便捷路径。它不同于
手动路径允许列表条目。若需要严格的显式信任，请保持 autoAllowSkills 禁用。

将这两个控制项用于不同任务：

• tools.exec.safeBins：小型、仅通过 stdin 使用的流式过滤器。
• tools.exec.safeBinTrustedDirs：用于 safe-bin 可执行文件路径的显式额外可信目录。
• tools.exec.safeBinProfiles：用于自定义 safe bins 的显式 argv 策略。
• 允许列表：对可执行文件路径的显式信任。

不要把 safeBins 当作通用允许列表，也不要添加解释器/运行时二进制文件（例如 python3、node、ruby、bash）。如果你需要这些，请使用显式允许列表条目，并保持审批提示启用。
当解释器/运行时 safeBins 条目缺少显式配置文件时，openclaw security audit 会发出警告，并且 openclaw doctor --fix 可以脚手架化缺失的自定义 safeBinProfiles 条目。
当你显式将 jq 等宽行为 bin 加回 safeBins 时，openclaw security audit 和 openclaw doctor 也会发出警告。
如果你显式允许列表化解释器，请启用 tools.exec.strictInlineEval，这样内联代码求值形式仍然需要新的审批。

有关完整策略详情和示例，请参阅 Exec 审批 和 Safe bins 与允许列表。

示例

前台：

{ "tool": "exec", "command": "ls -la" }

后台 + 轮询：

{"tool":"exec","command":"npm run build","yieldMs":1000}
{"tool":"process","action":"poll","sessionId":"<id>"}

轮询用于按需获取状态，而不是等待循环。如果启用了自动完成唤醒，命令在输出内容或失败时可以唤醒会话。

发送按键（tmux 风格）：

{"tool":"process","action":"send-keys","sessionId":"<id>","keys":["Enter"]}
{"tool":"process","action":"send-keys","sessionId":"<id>","keys":["C-c"]}
{"tool":"process","action":"send-keys","sessionId":"<id>","keys":["Up","Up","Enter"]}

提交（仅发送 CR）：

{ "tool": "process", "action": "submit", "sessionId": "<id>" }

粘贴（默认使用括号粘贴）：

{ "tool": "process", "action": "paste", "sessionId": "<id>", "text": "line1\nline2\n" }

apply_patch

apply_patch 是 exec 的子工具，用于结构化多文件编辑。
默认情况下，它对 OpenAI 和 OpenAI Codex 模型启用。仅在你想禁用它或将其限制到特定模型时使用配置：

{
  tools: {
    exec: {
      applyPatch: { workspaceOnly: true, allowModels: ["gpt-5.5"] },
    },
  },
}

注意事项：

• 仅适用于 OpenAI/OpenAI Codex 模型。
• 工具策略仍然适用；allow: ["write"] 会隐式允许 apply_patch。
• deny: ["write"] 不会拒绝 apply_patch；请显式拒绝 apply_patch，或在补丁写入也应被阻止时使用 deny: ["group:fs"]。
• 配置位于 tools.exec.applyPatch 下。
• tools.exec.applyPatch.enabled 默认为 true；将其设为 false 可为 OpenAI 模型禁用该工具。
• tools.exec.applyPatch.workspaceOnly 默认为 true（限制在工作区内）。只有在你有意让 apply_patch 写入/删除工作区目录之外的内容时，才将其设为 false。

相关内容

• Exec 审批 — shell 命令的审批门禁
• 沙箱隔离 — 在沙箱隔离环境中运行命令
• 后台进程 — 长时间运行的 exec 和 process 工具
• 安全 — 工具策略和提升访问权限

📄 Exec 审批

原文：https://docs.openclaw.ai/zh-CN/tools/exec-approvals

Exec 审批是配套应用 / 节点主机防护栏，用于允许
沙箱隔离智能体在真实主机（gateway 或 node）上运行命令。一个
安全联锁：只有当策略 + 允许列表 +（可选）用户审批全部一致时，命令才会被允许。Exec 审批叠加在
工具策略和提权门控之上（除非提权设置为 full，此时会
跳过审批）。

有效策略是 tools.exec.* 和审批默认值中更严格的那个；如果省略了某个审批字段，则使用
tools.exec 值。主机 exec 也会使用该机器上的本地审批状态 -
主机本地的 ~/.openclaw/exec-approvals.json 中的 ask: "always" 会持续
提示，即使会话或配置默认值请求 ask: "on-miss"。

检查有效策略

当本地作用域请求 host=node 时，exec-policy show 会报告该
作用域在运行时由节点管理，而不是假装本地
审批文件是真实来源。

如果配套应用 UI 不可用，任何通常会
提示的请求都会由询问回退解析（默认值：deny）。

原生聊天审批客户端可以在待处理审批消息上填充特定于渠道的快捷操作。
例如，Matrix 会填充反应快捷方式
（✅ 允许一次，❌ 拒绝，♾️ 始终允许），同时仍然在消息中保留
/approve ... 命令作为回退。

适用位置

Exec 审批在执行主机本地强制执行：

• Gateway 网关主机 → Gateway 网关机器上的 openclaw 进程。
• 节点主机 → 节点运行器（macOS 配套应用或无头节点主机）。

信任模型

• 通过 Gateway 网关认证的调用方是该 Gateway 网关的可信操作员。
• 已配对节点会把该可信操作员能力扩展到节点主机。
• Exec 审批会降低意外执行风险，但不是按用户划分的身份验证边界，也不是文件系统只读策略。
• 一旦获批，命令就可以根据所选主机或沙箱文件系统权限修改文件。
• 已批准的节点主机运行会绑定规范执行上下文：规范 cwd、精确 argv、存在时的 env 绑定，以及适用时固定的可执行文件路径。
• 对于 shell 脚本和直接的解释器/运行时文件调用，OpenClaw 也会尝试绑定一个具体的本地文件操作数。如果该绑定文件在审批后、执行前发生变化，则该运行会被拒绝，而不是执行已漂移的内容。
• 文件绑定有意采用尽力而为方式，不是每个解释器/运行时加载器路径的完整语义模型。如果审批模式无法精确识别一个要绑定的具体本地文件，它会拒绝铸造由审批支持的运行，而不是假装已经完整覆盖。

macOS 拆分

• 节点主机服务通过本地 IPC 将 system.run 转发给 macOS 应用。
• macOS 应用强制执行审批，并在 UI 上下文中执行命令。

设置和存储

审批存放在执行主机上的本地 JSON 文件中：

~/.openclaw/exec-approvals.json

示例 schema：

{
  "version": 1,
  "socket": {
    "path": "~/.openclaw/exec-approvals.sock",
    "token": "base64url-token"
  },
  "defaults": {
    "security": "deny",
    "ask": "on-miss",
    "askFallback": "deny",
    "autoAllowSkills": false
  },
  "agents": {
    "main": {
      "security": "allowlist",
      "ask": "on-miss",
      "askFallback": "deny",
      "autoAllowSkills": true,
      "allowlist": [
        {
          "id": "B0C8C0B3-2C2D-4F8A-9A3C-5A4B3C2D1E0F",
          "pattern": "~/Projects/**/bin/rg",
          "source": "allow-always",
          "commandText": "rg -n TODO",
          "lastUsedAt": 1737150000000,
          "lastUsedCommand": "rg -n TODO",
          "lastResolvedPath": "/Users/user/Projects/.../bin/rg"
        }
      ]
    }
  }
}

策略开关

exec.security

- deny - 阻止所有主机 exec 请求。
- allowlist - 仅允许允许列表中的命令。
- full - 允许所有内容（等同于提权）。

exec.ask

- off - 从不提示。
- on-miss - 仅当允许列表不匹配时提示。
- always - 每条命令都提示。当有效询问模式为 always 时，allow-always 持久信任不会抑制提示。

askFallback

需要提示但无法访问 UI 时的解析方式。

• deny - 阻止。
• allowlist - 仅当允许列表匹配时允许。
• full - 允许。

tools.exec.strictInlineEval

当为 true 时，OpenClaw 会将内联代码求值形式视为仅可通过审批运行，
即使解释器二进制文件本身已在允许列表中。对于无法清晰映射到一个稳定文件
操作数的解释器加载器，这是纵深防御。

严格模式会捕获的示例：

• python -c
• node -e, node --eval, node -p
• ruby -e
• perl -e, perl -E
• php -r
• lua -e
• osascript -e

在严格模式下，这些命令仍然需要显式审批，并且
allow-always 不会自动为它们持久化新的允许列表条目。

tools.exec.commandHighlighting

只控制 exec 审批提示中的呈现。启用后，
OpenClaw 可以附加解析器派生的命令范围，以便 Web 审批
提示能够高亮命令 token。将其设置为 true 可启用
命令文本高亮。

此设置不会改变 security、ask、允许列表匹配、
严格内联求值行为、审批转发或命令执行。
它可以在 tools.exec.commandHighlighting 下全局设置，或在每个
智能体的 agents.list[].tools.exec.commandHighlighting 下设置。

YOLO 模式（无审批）

如果你希望主机 exec 无需审批提示即可运行，必须打开
两个策略层 - OpenClaw 配置中的请求 exec 策略
（tools.exec.*）以及 ~/.openclaw/exec-approvals.json 中的主机本地审批策略。

除非你显式收紧，否则 YOLO 是默认主机行为：

重要区别：

• tools.exec.host=auto 选择 exec 在哪里运行：有沙箱时在沙箱中运行，否则在 Gateway 网关中运行。
• YOLO 选择主机 exec 如何获批：security=full 加 ask=off。
• 在 YOLO 模式下，OpenClaw 不会在已配置的主机 exec 策略之上添加单独的启发式命令混淆审批门控或脚本预检拒绝层。
• auto 不会让 Gateway 网关路由成为来自沙箱隔离会话的自由覆盖。来自 auto 的按调用 host=node 请求是允许的；只有在没有活动沙箱运行时时，来自 auto 的 host=gateway 才被允许。要获得稳定的非自动默认值，请设置 tools.exec.host，或显式使用 /exec host=...。

暴露自身非交互式权限模式的 CLI 支持提供商可以遵循此策略。当 OpenClaw 请求的 exec
策略为 YOLO 时，Claude CLI 会添加
--permission-mode bypassPermissions。可以在 agents.defaults.cliBackends.claude-cli.args / resumeArgs 下使用显式 Claude 参数覆盖该后端行为 -
例如 --permission-mode default、acceptEdits 或
bypassPermissions。

如果你想要更保守的设置，请将任一层收紧回
allowlist / on-miss 或 deny。

持久 Gateway 网关主机“永不提示”设置

bash
openclaw config set tools.exec.host gateway
openclaw config set tools.exec.security full
openclaw config set tools.exec.ask off
openclaw gateway restart


bash
openclaw approvals set --stdin <<'EOF'
{
version: 1,
defaults: {
security: "full",
ask: "off",
askFallback: "full"
}
}
EOF

本地快捷方式

openclaw exec-policy preset yolo

该本地快捷方式会同时更新：

• 本地 tools.exec.host/security/ask。
• 本地 ~/.openclaw/exec-approvals.json 默认值。

它有意仅限本地。要远程更改 Gateway 网关主机或节点主机
审批，请使用 openclaw approvals set --gateway 或
openclaw approvals set --node <id|name|ip>。

节点主机

对于节点主机，请改为在该节点上应用相同的审批文件：

openclaw approvals set --node <id|name|ip> --stdin <<'EOF'
{
  version: 1,
  defaults: {
    security: "full",
    ask: "off",
    askFallback: "full"
  }
}
EOF

仅本地限制：

• openclaw exec-policy 不会同步节点审批。
• openclaw exec-policy set --host node 会被拒绝。
• 节点 exec 审批会在运行时从节点获取，因此面向节点的更新必须使用 openclaw approvals --node ...。

仅会话快捷方式

• /exec security=full ask=off 只更改当前会话。
• /elevated full 是一个应急快捷方式，也会跳过该会话的 exec 审批。

如果主机审批文件仍然比配置更严格，则更严格的主机
策略仍然胜出。

允许列表（按智能体）

允许列表按智能体划分。如果存在多个智能体，请在 macOS 应用中切换你正在编辑的智能体。模式是 glob 匹配。

模式可以是已解析的二进制路径 glob，也可以是裸命令名 glob。
裸名称只匹配通过 PATH 调用的命令，因此当命令为 rg 时，rg 可以匹配
/opt/homebrew/bin/rg，但不能匹配 ./rg 或
/tmp/rg。如果你想信任一个特定的二进制位置，请使用路径 glob。

旧版 agents.default 条目会在加载时迁移到 agents.main。
诸如 echo ok && pwd 这样的 shell 链仍然需要每个顶层片段
都满足允许列表规则。

示例：

• rg
• ~/Projects/**/bin/peekaboo
• ~/.local/bin/*
• /opt/homebrew/bin/rg

使用 argPattern 限制参数

当允许列表条目应匹配某个二进制文件和
特定参数形状时，添加 argPattern。OpenClaw 会针对解析后的命令参数评估正则表达式，
不包括可执行 token
（argv[0]）。对于手写条目，参数会用
单个空格连接，因此当你需要精确匹配时请锚定该模式。

{
  "version": 1,
  "agents": {
    "main": {
      "allowlist": [
        {
          "pattern": "python3",
          "argPattern": "^safe\\.py$"
        }
      ]
    }
  }
}

该条目允许 python3 safe.py；python3 other.py 会错过允许列表。如果也存在同一二进制文件的仅路径条目，未匹配的
参数仍然可以回退到该仅路径条目。当目标是将该二进制文件限制为声明的参数时，请省略仅路径
条目。

由审批流程保存的条目可以使用内部分隔符格式，以便进行精确的 argv 匹配。优先使用 UI 或审批流程重新生成这些条目，而不是手动编辑编码值。如果 OpenClaw 无法解析命令片段的 argv，带有 argPattern 的条目将不会匹配。

每个允许列表条目支持：

自动允许 Skills CLI

启用 自动允许 Skills CLI 后，已知 Skills 引用的可执行文件会在节点上被视为已加入允许列表（macOS 节点或无头节点主机）。这会通过 Gateway 网关 RPC 使用 skills.bins 获取 Skill 二进制文件列表。如果你需要严格的手动允许列表，请禁用此功能。

- 这是一个隐式便捷允许列表，独立于手动路径允许列表条目。
- 它面向可信操作员环境，其中 Gateway 网关 和节点位于同一信任边界内。
- 如果你需要严格的显式信任，请保持 autoAllowSkills: false，并且只使用手动路径允许列表条目。

安全二进制文件和审批转发

有关安全二进制文件（仅 stdin 的快速路径）、解释器绑定细节，以及如何将审批提示转发到 Slack/Discord/Telegram（或将它们作为原生审批客户端运行），请参阅
Exec 审批 - 高级。

Control UI 编辑

使用 Control UI → Nodes → Exec approvals 卡片编辑默认值、按智能体覆盖项和允许列表。选择作用域（默认值或某个智能体），调整策略，添加/移除允许列表模式，然后点击 Save。UI 会按模式显示上次使用的元数据，方便你保持列表整洁。

目标选择器会选择 Gateway 网关（本地审批）或一个节点。节点必须声明 system.execApprovals.get/set（macOS 应用或无头节点主机）。如果节点尚未声明 exec 审批，请直接编辑其本地 ~/.openclaw/exec-approvals.json。

CLI：openclaw approvals 支持 Gateway 网关 或节点编辑 - 请参阅
Approvals CLI。

审批流程

当需要提示时，Gateway 网关 会向操作员客户端广播
exec.approval.requested。Control UI 和 macOS 应用通过 exec.approval.resolve 解析它，然后 Gateway 网关 将获批请求转发到节点主机。

对于 host=node，审批请求会包含一个规范的 systemRunPlan 载荷。Gateway 网关 在转发获批的 system.run 请求时，会将该计划用作权威的 command/cwd/session 上下文。

这对于异步审批延迟很重要：

• 节点 exec 路径会预先准备一个规范计划。
• 审批记录会存储该计划及其绑定元数据。
• 一旦获批，最终转发的 system.run 调用会复用已存储的计划，而不是信任后续调用方编辑。
• 如果调用方在审批请求创建后更改 command、rawCommand、cwd、agentId 或 sessionKey，Gateway 网关 会将转发的运行拒绝为审批不匹配。

系统事件

Exec 生命周期会以系统消息形式呈现：

• Exec running（仅当命令超过运行通知阈值时）。
• Exec finished。
• Exec denied。

这些事件会在节点报告事件后发布到智能体的会话。Gateway 网关 主机 exec 审批会在命令完成时发出相同的生命周期事件（也可以在运行时间超过阈值时发出）。受审批控制的 exec 会在这些消息中复用审批 ID 作为 runId，便于关联。

审批被拒绝时的行为

当异步 exec 审批被拒绝时，OpenClaw 会阻止智能体复用会话中同一命令任何较早运行的输出。拒绝原因会附带明确指引，说明没有可用的命令输出，从而阻止智能体声称有新输出，或使用先前成功运行的陈旧结果重复被拒绝的命令。

影响

• full 权限很强；尽可能优先使用允许列表。
• ask 让你保持在环，同时仍允许快速审批。
• 按智能体允许列表可防止一个智能体的审批泄漏到其他智能体。
• 审批仅适用于来自授权发送者的主机 exec 请求。未授权发送者无法发出 /exec。
• /exec security=full 是面向授权操作员的会话级便捷方式，并且按设计会跳过审批。若要硬性阻止主机 exec，请将审批安全性设置为 deny，或通过工具策略拒绝 exec 工具。

相关

安全二进制文件、解释器绑定，以及将审批转发到聊天。


Shell 命令执行工具。


同样会跳过审批的应急路径。


沙箱模式和工作区访问。


安全模型和加固。


何时使用每种控制方式。


Skill 支持的自动允许行为。

📄 Firecrawl

原文：https://docs.openclaw.ai/zh-CN/tools/firecrawl

OpenClaw 可以通过三种方式使用 Firecrawl：

• 作为 web_search 提供商
• 作为显式插件工具：firecrawl_search 和 firecrawl_scrape
• 作为 web_fetch 的后备提取器

它是一项托管的提取/搜索服务，支持机器人规避和缓存，
有助于处理 JS 较重的网站，或会阻止普通 HTTP 抓取的页面。

获取 API key

1. 创建 Firecrawl 账户并生成 API key。
2. 将其存储在配置中，或在 Gateway 网关环境中设置 FIRECRAWL_API_KEY。

配置 Firecrawl 搜索

{
  tools: {
    web: {
      search: {
        provider: "firecrawl",
      },
    },
  },
  plugins: {
    entries: {
      firecrawl: {
        enabled: true,
        config: {
          webSearch: {
            apiKey: "FIRECRAWL_API_KEY_HERE",
            baseUrl: "https://api.firecrawl.dev",
          },
        },
      },
    },
  },
}

注意事项：

• 在新手引导或 openclaw configure --section web 中选择 Firecrawl，会自动启用内置 Firecrawl 插件。
• 使用 Firecrawl 的 web_search 支持 query 和 count。
• 对于 Firecrawl 专用控制项，例如 sources、categories 或结果抓取，请使用 firecrawl_search。
• baseUrl 默认指向托管的 Firecrawl：https://api.firecrawl.dev。仅允许为私有/内部端点使用自托管覆盖；HTTP 仅对这些私有目标可接受。
• FIRECRAWL_BASE_URL 是 Firecrawl 搜索和抓取基础 URL 的共享环境变量后备项。

配置 Firecrawl 抓取 + web_fetch 后备

{
  plugins: {
    entries: {
      firecrawl: {
        enabled: true,
        config: {
          webFetch: {
            apiKey: "FIRECRAWL_API_KEY_HERE",
            baseUrl: "https://api.firecrawl.dev",
            onlyMainContent: true,
            maxAgeMs: 172800000,
            timeoutSeconds: 60,
          },
        },
      },
    },
  },
}

注意事项：

• Firecrawl 后备尝试仅在有 API key 可用时运行（plugins.entries.firecrawl.config.webFetch.apiKey 或 FIRECRAWL_API_KEY）。
• maxAgeMs 控制缓存结果可以多旧（毫秒）。默认值为 2 天。
• 旧版 tools.web.fetch.firecrawl.* 配置会由 openclaw doctor --fix 自动迁移。
• Firecrawl 抓取/基础 URL 覆盖遵循与搜索相同的托管/私有规则：公共托管流量使用 https://api.firecrawl.dev；自托管覆盖必须解析到私有/内部端点。
• firecrawl_scrape 会先拒绝明显的私有、loopback、元数据和非 HTTP(S) 目标 URL，然后再将它们转发给 Firecrawl，这与显式 Firecrawl 抓取调用的 web_fetch 目标安全合同保持一致。

firecrawl_scrape 复用相同的 plugins.entries.firecrawl.config.webFetch.* 设置和环境变量。

自托管 Firecrawl

当你自行运行 Firecrawl 时，请设置 plugins.entries.firecrawl.config.webSearch.baseUrl、
plugins.entries.firecrawl.config.webFetch.baseUrl 或 FIRECRAWL_BASE_URL。
OpenClaw 仅对 loopback、私有网络、.local、.internal 或 .localhost 目标接受 http://。
公共自定义主机会被拒绝，以避免 Firecrawl API key 意外发送到任意端点。

Firecrawl 插件工具

firecrawl_search

当你想使用 Firecrawl 专用搜索控制项，而不是通用 web_search 时，请使用它。

核心参数：

• query
• count
• sources
• categories
• scrapeResults
• timeoutSeconds

firecrawl_scrape

对于 JS 较重或受机器人防护的页面，如果普通 web_fetch 效果较弱，请使用它。

核心参数：

• url
• extractMode
• maxChars
• onlyMainContent
• maxAgeMs
• proxy
• storeInCache
• timeoutSeconds

隐身 / 机器人规避

Firecrawl 为机器人规避暴露了一个 proxy mode 参数（basic、stealth 或 auto）。
OpenClaw 始终对 Firecrawl 请求使用 proxy: "auto" 加 storeInCache: true。
如果省略 proxy，Firecrawl 默认使用 auto。如果 basic 尝试失败，auto 会使用隐身代理重试，这可能比仅 basic 抓取消耗更多 credits。

web_fetch 如何使用 Firecrawl

web_fetch 提取顺序：

1. Readability（本地）
2. Firecrawl（如果被选中，或被自动检测为当前 Web 抓取后备）
3. 基础 HTML 清理（最后后备）

选择旋钮是 tools.web.fetch.provider。如果省略它，OpenClaw
会从可用凭证中自动检测第一个就绪的 Web 抓取提供商。
目前内置提供商是 Firecrawl。

相关

• Web Search 概览 -- 所有提供商和自动检测
• Web Fetch -- 带 Firecrawl 后备的 web_fetch 工具
• Tavily -- 搜索 + 提取工具

📄 LLM 任务

原文：https://docs.openclaw.ai/zh-CN/tools/llm-task

llm-task 是一个可选插件工具，用于运行仅 JSON 的 LLM 任务，并返回结构化输出（可选地根据 JSON Schema 验证）。

这非常适合像 Lobster 这样的工作流引擎：你可以添加单个 LLM 步骤，而不必为每个工作流编写自定义 OpenClaw 代码。

启用插件

1. 启用插件：

{
  "plugins": {
    "entries": {
      "llm-task": { "enabled": true }
    }
  }
}

2. 允许可选工具：

{
  "tools": {
    "alsoAllow": ["llm-task"]
  }
}

仅当你想使用限制性允许列表模式时，才使用 tools.allow。

配置（可选）

{
  "plugins": {
    "entries": {
      "llm-task": {
        "enabled": true,
        "config": {
          "defaultProvider": "openai-codex",
          "defaultModel": "gpt-5.5",
          "defaultAuthProfileId": "main",
          "allowedModels": ["openai/gpt-5.4"],
          "maxTokens": 800,
          "timeoutMs": 30000
        }
      }
    }
  }
}

allowedModels 是 provider/model 字符串的允许列表。如果设置了它，列表之外的任何请求都会被拒绝。

工具参数

• prompt（字符串，必需）
• input（任意，可选）
• schema（对象，可选 JSON Schema）
• provider（字符串，可选）
• model（字符串，可选）
• thinking（字符串，可选）
• authProfileId（字符串，可选）
• temperature（数字，可选）
• maxTokens（数字，可选）
• timeoutMs（数字，可选）

thinking 接受标准 OpenClaw 推理预设，例如 low 或 medium。

输出

返回包含已解析 JSON 的 details.json（并在提供 schema 时对其进行验证）。

示例：Lobster 工作流步骤

重要限制

下面的示例假设独立版 Lobster CLI 正在一个环境中运行，其中 openclaw.invoke 已经具有正确的 Gateway 网关 URL/认证上下文。

对于 OpenClaw 内置的嵌入式 Lobster 运行器，这种嵌套 CLI 模式目前并不可靠：

openclaw.invoke --tool llm-task --action json --args-json '{ ... }'

在嵌入式 Lobster 为此流程提供受支持的桥接之前，请优先使用以下任一方式：

• 在 Lobster 外部直接调用 llm-task 工具，或
• 使用不依赖嵌套 openclaw.invoke 调用的 Lobster 步骤。

独立版 Lobster CLI 示例：

openclaw.invoke --tool llm-task --action json --args-json '{
  "prompt": "Given the input email, return intent and draft.",
  "thinking": "low",
  "input": {
    "subject": "Hello",
    "body": "Can you help?"
  },
  "schema": {
    "type": "object",
    "properties": {
      "intent": { "type": "string" },
      "draft": { "type": "string" }
    },
    "required": ["intent", "draft"],
    "additionalProperties": false
  }
}'

安全说明

• 该工具仅限 JSON，并指示模型只输出 JSON（没有代码围栏，没有评论）。
• 本次运行不会向模型暴露任何工具。
• 除非你使用 schema 进行验证，否则应将输出视为不可信。
• 在任何会产生副作用的步骤（发送、发布、执行）之前放置审批。

相关内容

• Thinking 级别
• 子智能体
• 斜杠命令

📄 龙虾

原文：https://docs.openclaw.ai/zh-CN/tools/lobster

Lobster 是一个工作流 shell，让 OpenClaw 能将多步骤工具序列作为单个、确定性的操作运行，并带有明确的审批检查点。

Lobster 是高于分离式后台工作的一个编写层。对于单个任务之上的流程编排，请参阅 任务流（openclaw tasks flow）。对于任务活动台账，请参阅 openclaw tasks。

钩子

你的助手可以构建管理自身的工具。提出一个工作流需求，30 分钟后你就会拥有一个 CLI 以及可作为一次调用运行的流水线。Lobster 是缺失的那块拼图：确定性流水线、明确审批和可恢复状态。

为什么

如今，复杂工作流需要多次来回工具调用。每次调用都会消耗 token，并且 LLM 必须编排每个步骤。Lobster 将这种编排移入类型化运行时：

• 一次调用，而不是多次：OpenClaw 运行一次 Lobster 工具调用并获得结构化结果。
• 内置审批：副作用（发送邮件、发布评论）会暂停工作流，直到明确批准。
• 可恢复：暂停的工作流会返回一个 token；批准后即可恢复，无需重新运行所有内容。

为什么使用 DSL 而不是普通程序？

Lobster 有意保持小巧。目标不是“一个新语言”，而是一个可预测、AI 友好的流水线规范，具备一等审批和恢复 token。

• 内置批准/恢复：普通程序可以提示人工操作，但它无法在不由你自行发明运行时的情况下，使用持久 token 暂停并恢复。
• 确定性 + 可审计性：流水线是数据，因此易于记录、差异比较、重放和审查。
• 面向 AI 的受限表面：极小语法 + JSON 管道减少“创造性”代码路径，并让验证更现实。
• 内置安全策略：超时、输出上限、沙箱检查和允许列表由运行时强制执行，而不是由每个脚本执行。
• 仍然可编程：每个步骤都可以调用任意 CLI 或脚本。如果你需要 JS/TS，可以从代码生成 .lobster 文件。

工作方式

OpenClaw 使用嵌入式 runner 进程内运行 Lobster 工作流。不会生成外部 CLI 子进程；工作流引擎在 Gateway 网关进程内执行，并直接返回 JSON 信封。
如果流水线为审批而暂停，工具会返回 resumeToken，让你之后继续。

模式：小型 CLI + JSON 管道 + 审批

构建使用 JSON 通信的小命令，然后将它们串成一次 Lobster 调用。（下面的示例命令名称请替换为你自己的名称。）

inbox list --json
inbox categorize --json
inbox apply --json

{
  "action": "run",
  "pipeline": "exec --json --shell 'inbox list --json' | exec --stdin json --shell 'inbox categorize --json' | exec --stdin json --shell 'inbox apply --json' | approve --preview-from-stdin --limit 5 --prompt 'Apply changes?'",
  "timeoutMs": 30000
}

如果流水线请求审批，请使用 token 恢复：

{
  "action": "resume",
  "token": "<resumeToken>",
  "approve": true
}

AI 触发工作流；Lobster 执行步骤。审批门让副作用明确且可审计。

示例：将输入项映射为工具调用：

gog.gmail.search --query 'newer_than:1d' \
  | openclaw.invoke --tool message --action send --each --item-key message --args-json '{"provider":"telegram","to":"..."}'

仅 JSON 的 LLM 步骤（llm-task）

对于需要结构化 LLM 步骤的工作流，启用可选的
llm-task 插件工具并从 Lobster 调用它。这样既能保持工作流
确定性，也能让你使用模型进行分类、总结或起草。

启用该工具：

{
  "plugins": {
    "entries": {
      "llm-task": { "enabled": true }
    }
  },
  "agents": {
    "list": [
      {
        "id": "main",
        "tools": { "alsoAllow": ["llm-task"] }
      }
    ]
  }
}

重要限制：嵌入式 Lobster 与 openclaw.invoke

内置 Lobster 插件会在 Gateway 网关内进程内运行工作流。在这种嵌入式模式下，openclaw.invoke 不会自动为嵌套的 OpenClaw CLI 工具调用继承 Gateway 网关 URL/认证上下文。

这意味着此模式目前在嵌入式 runner 中不可靠：

openclaw.invoke --tool llm-task --action json --args-json '{ ... }'

仅当你在 独立 Lobster CLI 中运行，并且环境中的 openclaw.invoke 已配置正确的 Gateway 网关/认证上下文时，才使用下面的示例。

在独立 Lobster CLI 流水线中使用：

openclaw.invoke --tool llm-task --action json --args-json '{
  "prompt": "Given the input email, return intent and draft.",
  "thinking": "low",
  "input": { "subject": "Hello", "body": "Can you help?" },
  "schema": {
    "type": "object",
    "properties": {
      "intent": { "type": "string" },
      "draft": { "type": "string" }
    },
    "required": ["intent", "draft"],
    "additionalProperties": false
  }
}'

如果你今天使用的是嵌入式 Lobster 插件，请优先选择：

• 在 Lobster 外部直接调用 llm-task 工具，或
• 在添加受支持的嵌入式桥接之前，在 Lobster 流水线内使用非 openclaw.invoke 步骤。

有关详情和配置选项，请参阅 LLM Task。

工作流文件（.lobster）

Lobster 可以运行包含 name、args、steps、env、condition 和 approval 字段的 YAML/JSON 工作流文件。在 OpenClaw 工具调用中，将 pipeline 设置为文件路径。

name: inbox-triage
args:
  tag:
    default: "family"
steps:
  - id: collect
    command: inbox list --json
  - id: categorize
    command: inbox categorize --json
    stdin: $collect.stdout
  - id: approve
    command: inbox apply --approve
    stdin: $categorize.stdout
    approval: required
  - id: execute
    command: inbox apply --execute
    stdin: $categorize.stdout
    condition: $approve.approved

注意：

• stdin: $step.stdout 和 stdin: $step.json 会传递先前步骤的输出。
• condition（或 when）可以根据 $step.approved 控制步骤是否执行。

安装 Lobster

内置 Lobster 工作流会进程内运行；不需要单独的 lobster 二进制文件。嵌入式 runner 随 Lobster 插件一起提供。

如果你需要独立 Lobster CLI 用于开发或外部流水线，请从 Lobster 仓库安装，并确保 lobster 位于 PATH 上。

启用工具

Lobster 是一个可选插件工具（默认未启用）。

推荐方式（增量、安全）：

{
  "tools": {
    "alsoAllow": ["lobster"]
  }
}

或按 Agent 配置：

{
  "agents": {
    "list": [
      {
        "id": "main",
        "tools": {
          "alsoAllow": ["lobster"]
        }
      }
    ]
  }
}

除非你打算在受限允许列表模式下运行，否则避免使用 tools.allow: ["lobster"]。

允许列表对于可选插件是选择启用的。alsoAllow 只启用命名的可选插件工具，同时保留正常的核心工具集。若要限制核心工具，请将 tools.allow 与你需要的核心工具或分组一起使用。

示例：邮件分流

不使用 Lobster：

User: "Check my email and draft replies"
→ openclaw calls gmail.list
→ LLM summarizes
→ User: "draft replies to #2 and #5"
→ LLM drafts
→ User: "send #2"
→ openclaw calls gmail.send
(repeat daily, no memory of what was triaged)

使用 Lobster：

{
  "action": "run",
  "pipeline": "email.triage --limit 20",
  "timeoutMs": 30000
}

返回一个 JSON 信封（已截断）：

{
  "ok": true,
  "status": "needs_approval",
  "output": [{ "summary": "5 need replies, 2 need action" }],
  "requiresApproval": {
    "type": "approval_request",
    "prompt": "Send 2 draft replies?",
    "items": [],
    "resumeToken": "..."
  }
}

用户批准 → 恢复：

{
  "action": "resume",
  "token": "<resumeToken>",
  "approve": true
}

一个工作流。确定性。安全。

工具参数

run

以工具模式运行流水线。

{
  "action": "run",
  "pipeline": "gog.gmail.search --query 'newer_than:1d' | email.triage",
  "cwd": "workspace",
  "timeoutMs": 30000,
  "maxStdoutBytes": 512000
}

带参数运行工作流文件：

{
  "action": "run",
  "pipeline": "/path/to/inbox-triage.lobster",
  "argsJson": "{\"tag\":\"family\"}"
}

resume

在审批后继续暂停的工作流。

{
  "action": "resume",
  "token": "<resumeToken>",
  "approve": true
}

可选输入

• cwd：流水线的相对工作目录（必须保持在 Gateway 网关工作目录内）。
• timeoutMs：如果工作流超过此时长则中止（默认：20000）。
• maxStdoutBytes：如果输出超过此大小则中止（默认：512000）。
• argsJson：传递给 lobster run --args-json 的 JSON 字符串（仅限工作流文件）。

输出信封

Lobster 返回一个 JSON 信封，其中包含三种状态之一：

• ok → 成功完成
• needs_approval → 已暂停；需要 requiresApproval.resumeToken 才能恢复
• cancelled → 明确拒绝或取消

该工具会在 content（美化后的 JSON）和 details（原始对象）中公开该信封。

审批

如果存在 requiresApproval，请检查提示并决定：

• approve: true → 恢复并继续副作用
• approve: false → 取消并结束工作流

使用 approve --preview-from-stdin --limit N 可将 JSON 预览附加到审批请求，无需自定义 jq/heredoc 粘合逻辑。恢复 token 现在很紧凑：Lobster 会将工作流恢复状态存储在其状态目录下，并返回一个小型 token key。

OpenProse

OpenProse 与 Lobster 配合良好：使用 /prose 编排多 Agent 准备工作，然后运行 Lobster 流水线来进行确定性审批。如果 Prose 程序需要 Lobster，请通过 tools.subagents.tools 允许子智能体使用 lobster 工具。请参阅 OpenProse。

安全

• 仅本地进程内 - 工作流在 Gateway 网关进程内执行；插件本身不会发起网络调用。
• 无密钥 - Lobster 不管理 OAuth；它调用负责 OAuth 的 OpenClaw 工具。
• 感知沙箱 - 当工具上下文被沙箱隔离时禁用。
• 已加固 - 嵌入式 runner 会强制执行超时和输出上限。

故障排除

• lobster timed out → 增加 timeoutMs，或拆分较长的流水线。
• lobster output exceeded maxStdoutBytes → 提高 maxStdoutBytes 或减少输出大小。
• lobster returned invalid JSON → 确保流水线以工具模式运行，并且只打印 JSON。
• lobster failed → 检查 Gateway 网关日志以获取嵌入式 runner 错误详情。

了解更多

• 插件
• 插件工具编写

案例研究：社区工作流

一个公开示例：一个“第二大脑”CLI + Lobster 流水线，用于管理三个 Markdown vault（个人、伴侣、共享）。CLI 会为统计信息、收件箱列表和陈旧内容扫描输出 JSON；Lobster 会将这些命令串联成 weekly-review、inbox-triage、memory-consolidation 和 shared-task-sync 等工作流，每个工作流都带有审批门。AI 在可用时负责判断（分类），不可用时则回退到确定性规则。

• 主题帖：https://x.com/plattenschieber/status/2014508656335770033
• 仓库：https://github.com/bloomedai/brain-cli

相关

• 自动化 - 调度 Lobster 工作流
• 自动化概览 - 所有自动化机制
• 工具概览 - 所有可用的 agent 工具

📄 Perplexity 搜索

原文：https://docs.openclaw.ai/zh-CN/perplexity

此页面已移至 Perplexity 搜索。

相关

• Web 工具

📄 表情回应

原文：https://docs.openclaw.ai/zh-CN/tools/reactions

智能体可以使用带有 react 动作的 message
工具在消息上添加和移除 emoji 反应。反应行为因渠道和传输协议而异。

工作方式

{
  "action": "react",
  "messageId": "msg-123",
  "emoji": "thumbsup"
}

• 添加反应时必须提供 emoji。
• 将 emoji 设为空字符串（""）以移除机器人的反应。
• 设置 remove: true 以移除特定 emoji（需要非空 emoji）。
• 在支持状态反应的渠道上，反应中的 trackToolCalls: true 会让运行时在同一轮次中将该被反应的消息用于后续工具进度反应。

渠道行为

- 空 emoji 会移除机器人在该消息上的所有反应。
- remove: true 只会移除指定 emoji。

- 空 emoji 会移除应用在该消息上的反应。
- remove: true 只会移除指定 emoji。

- 空 emoji 会移除机器人的反应。
- remove: true 也会移除反应，但为了通过工具验证仍需要非空 emoji。

- 空 emoji 会移除机器人反应。
- remove: true 会在内部映射为空 emoji（工具调用中仍需要 emoji）。

- 需要非空 emoji。
- remove: true 会移除该特定 emoji 反应。

- 使用带有 add、remove 和 list 动作的 feishu_reaction 工具。
- 添加/移除需要 emoji_type；移除还需要 reaction_id。

- 入站反应通知由 channels.signal.reactionNotifications 控制："off" 会禁用它们，"own"（默认）会在用户对机器人消息做出反应时发出事件，"all" 会为所有反应发出事件。

- 出站反应是 iMessage tapback（love、like、dislike、laugh、emphasize 和 question）。
- 入站 tapback 通知由 channels.imessage.reactionNotifications 控制："off" 会禁用它们，"own"（默认）会在用户对机器人撰写的消息做出反应时发出事件，"all" 会为来自已授权发送者的所有 tapback 发出事件。

反应级别

按渠道配置的 reactionLevel 控制智能体使用反应的范围。值通常为 off、ack、minimal 或 extensive。

• Telegram reactionLevel — channels.telegram.reactionLevel
• WhatsApp reactionLevel — channels.whatsapp.reactionLevel

在各个渠道上设置 reactionLevel，以调整智能体在每个平台上对消息做出反应的活跃程度。

相关内容

• Agent Send — 包含 react 的 message 工具
• 渠道 — 特定于渠道的配置

📄 思考级别

原文：https://docs.openclaw.ai/zh-CN/tools/thinking

它的作用

• 任意入站正文中的内联指令：/t <level>、/think:<level> 或 /thinking <level>。
• 级别（别名）：off | minimal | low | medium | high | xhigh | adaptive | max
• minimal → “思考”
• low → “深度思考”
• medium → “更深度思考”
• high → “ultrathink”（最大预算）
• xhigh → “ultrathink+”（GPT-5.2+ 和 Codex 模型，以及 Anthropic Claude Opus 4.7 effort）
• adaptive → 提供商管理的自适应思考（支持 Claude 4.6 on Anthropic/Bedrock、Anthropic Claude Opus 4.7，以及 Google Gemini 动态思考）
• max → 提供商最大推理（Anthropic Claude Opus 4.7；Ollama 会将其映射到最高原生 think effort）
• x-high、x_high、extra-high、extra high 和 extra_high 映射到 xhigh。
• highest 映射到 high。
• 提供商说明：
• 思考菜单和选择器由提供商配置文件驱动。提供商插件会声明所选模型的确切级别集合，包括二元 on 等标签。
• adaptive、xhigh 和 max 仅会为支持它们的提供商/模型配置文件展示。对于不支持的级别，类型化指令会被拒绝，并返回该模型的有效选项。
• 已存储的不受支持级别会按提供商配置文件排名重新映射。在非自适应模型上，adaptive 回退到 medium，而 xhigh 和 max 会回退到所选模型支持的最大非 off 级别。
• Anthropic Claude 4.6 模型在未设置显式思考级别时默认使用 adaptive。
• Anthropic Claude Opus 4.7 不默认使用自适应思考。除非你显式设置思考级别，否则其 API effort 默认值仍由提供商拥有。
• Anthropic Claude Opus 4.7 将 /think xhigh 映射到自适应思考加 output_config.effort: "xhigh"，因为 /think 是思考指令，而 xhigh 是 Opus 4.7 的 effort 设置。
• Anthropic Claude Opus 4.7 也公开 /think max；它会映射到相同的提供商拥有的最大 effort 路径。
• 直连 DeepSeek V4 模型公开 /think xhigh|max；二者都映射到 DeepSeek reasoning_effort: "max"，而较低的非 off 级别映射到 high。
• 经 OpenRouter 路由的 DeepSeek V4 模型公开 /think xhigh，并发送 OpenRouter 支持的 reasoning_effort 值。已存储的 max 覆盖值会回退到 xhigh。
• 支持思考的 Ollama 模型公开 /think low|medium|high|max；max 映射到原生 think: "high"，因为 Ollama 的原生 API 接受 low、medium 和 high effort 字符串。
• OpenAI GPT 模型会通过特定模型的 Responses API effort 支持来映射 /think。只有目标模型支持时，/think off 才会发送 reasoning.effort: "none"；否则 OpenClaw 会省略禁用推理的 payload，而不是发送不受支持的值。
• 自定义 OpenAI 兼容目录条目可以通过将 models.providers.<provider>.models[].compat.supportedReasoningEfforts 设置为包含 "xhigh" 来选择加入 /think xhigh。这会使用同一套映射出站 OpenAI reasoning effort payload 的 compat 元数据，因此菜单、会话验证、智能体 CLI 和 llm-task 会与传输行为保持一致。
• 过期的已配置 OpenRouter Hunter Alpha refs 会跳过代理推理注入，因为这个已退役路由可能会通过推理字段返回最终答案文本。
• Google Gemini 将 /think adaptive 映射到 Gemini 的提供商拥有的动态思考。Gemini 3 请求会省略固定的 thinkingLevel，而 Gemini 2.5 请求会发送 thinkingBudget: -1；固定级别仍会映射到该模型系列最接近的 Gemini thinkingLevel 或预算。
• Anthropic 兼容流式路径上的 MiniMax（minimax/*）默认使用 thinking: { type: "disabled" }，除非你在模型参数或请求参数中显式设置思考。这样可以避免 MiniMax 非原生 Anthropic 流格式泄漏 reasoning_content delta。
• Z.AI（zai/*）仅支持二元思考（on/off）。任何非 off 级别都会被视为 on（映射到 low）。
• Moonshot（moonshot/*）将 /think off 映射到 thinking: { type: "disabled" }，并将任何非 off 级别映射到 thinking: { type: "enabled" }。启用思考时，Moonshot 仅接受 tool_choice auto|none；OpenClaw 会将不兼容的值规范化为 auto。

解析顺序

1. 消息上的内联指令（仅应用于该消息）。
2. 会话覆盖（通过发送仅包含指令的消息设置）。
3. 每智能体默认值（配置中的 agents.list[].thinkingDefault）。
4. 全局默认值（配置中的 agents.defaults.thinkingDefault）。
5. 回退：可用时使用提供商声明的默认值；否则，支持推理的模型解析为 medium 或该模型最接近的受支持非 off 级别，不支持推理的模型保持 off。

设置会话默认值

• 发送一条仅包含该指令的消息（允许空白），例如 /think:medium 或 /t high。
• 该设置会固定到当前会话（默认按发送者区分）。使用 /think default 清除会话覆盖并继承已配置/提供商默认值；别名包括 inherit、clear、reset 和 unpin。
• /think off 会存储显式 off 覆盖。它会禁用思考，直到你更改或清除会话覆盖。
• 会发送确认回复（Thinking level set to high. / Thinking disabled.）。如果级别无效（例如 /thinking big），命令会被拒绝并给出提示，且会话状态保持不变。
• 发送不带参数的 /think（或 /think:）可查看当前思考级别。

按智能体应用

• 嵌入式 Pi：解析后的级别会传递给进程内 Pi 智能体运行时。
• Claude CLI 后端：使用 claude-cli 时，非 off 级别会作为 --effort 传递给 Claude Code；请参阅 CLI 后端。

快速模式（/fast）

• 级别：on|off|default。
• 仅包含指令的消息会切换会话快速模式覆盖，并回复 Fast mode enabled. / Fast mode disabled.。使用 /fast default 清除会话覆盖并继承已配置默认值；别名包括 inherit、clear、reset 和 unpin。
• 发送不带模式的 /fast（或 /fast status）可查看当前有效的快速模式状态。
• OpenClaw 按以下顺序解析快速模式：
  1. 内联/仅指令 /fast on|off 覆盖（/fast default 清除此层）
  2. 会话覆盖
  3. 每智能体默认值（agents.list[].fastModeDefault）
  4. 每模型配置：agents.defaults.models["<provider>/<model>"].params.fastMode
  5. 回退：off
• 对于 openai/*，快速模式会在受支持的 Responses 请求中发送 service_tier=priority，映射到 OpenAI 优先级处理。
• 对于 openai-codex/*，快速模式会在 Codex Responses 上发送相同的 service_tier=priority 标志。OpenClaw 会在两个认证路径之间保留一个共享的 /fast 开关。
• 对于直连公共 anthropic/* 请求，包括发送到 api.anthropic.com 的 OAuth 认证流量，快速模式映射到 Anthropic 服务层级：/fast on 设置 service_tier=auto，/fast off 设置 service_tier=standard_only。
• 对于 Anthropic 兼容路径上的 minimax/*，/fast on（或 params.fastMode: true）会将 MiniMax-M2.7 重写为 MiniMax-M2.7-highspeed。
• 同时设置时，显式 Anthropic serviceTier / service_tier 模型参数会覆盖快速模式默认值。对于非 Anthropic 代理 base URL，OpenClaw 仍会跳过 Anthropic 服务层级注入。
• /status 仅在启用快速模式时显示 Fast。

详细指令（/verbose 或 /v）

• 级别：on（最小）| full | off（默认）。
• 仅包含指令的消息会切换会话详细模式，并回复 Verbose logging enabled. / Verbose logging disabled.；无效级别会返回提示且不更改状态。
• /verbose off 会存储显式会话覆盖；可在会话 UI 中选择 inherit 来清除它。
• 内联指令仅影响该消息；否则应用会话/全局默认值。
• 发送不带参数的 /verbose（或 /verbose:）可查看当前详细级别。
• 启用详细模式时，发出结构化工具结果的智能体（Pi、其他 JSON 智能体）会将每次工具调用作为独立的仅元数据消息发回，可用时前缀为 <emoji> <tool-name>: <arg>。这些工具摘要会在每个工具启动时立即发送（独立气泡），而不是作为流式 delta 发送。
• 工具失败摘要在普通模式下仍可见，但原始错误详情后缀会被隐藏，除非详细模式为 on 或 full。
• 当详细模式为 full 时，工具输出也会在完成后转发（独立气泡，截断到安全长度）。如果你在运行过程中切换 /verbose on|full|off，后续工具气泡会遵循新设置。
• agents.defaults.toolProgressDetail 控制 /verbose 工具摘要和进度草稿工具行的形态。使用 "explain"（默认）获取紧凑的人类标签，例如 🛠️ Exec: checking JS syntax；调试时若也需要追加原始命令/详情，请使用 "raw"。每智能体 agents.list[].toolProgressDetail 会覆盖默认值。
• explain: 🛠️ Exec: check JS syntax for /tmp/app.js
• raw: 🛠️ Exec: check JS syntax for /tmp/app.js, node --check /tmp/app.js

插件跟踪指令（/trace）

• 级别：on | off（默认）。
• 仅包含指令的消息会切换会话插件跟踪输出，并回复 Plugin trace enabled. / Plugin trace disabled.。
• 内联指令仅影响该消息；否则应用会话/全局默认值。
• 发送不带参数的 /trace（或 /trace:）可查看当前跟踪级别。
• /trace 比 /verbose 范围更窄：它只公开插件拥有的跟踪/调试行，例如 Active Memory 调试摘要。
• 跟踪行可以出现在 /status 中，也可以在普通助手回复后作为后续诊断消息出现。

推理可见性（/reasoning）

• 级别：on|off|stream。
• 仅包含指令的消息会切换是否在回复中显示思考块。
• 启用后，推理会作为单独消息发送，前缀为 Reasoning:。
• stream（仅 Telegram）：在生成回复时将推理流式传输到 Telegram 草稿气泡，然后发送不含推理的最终答案。
• 别名：/reason。
• 发送不带参数的 /reasoning（或 /reasoning:）可查看当前推理级别。
• 解析顺序：内联指令，然后是会话覆盖，然后是每智能体默认值（agents.list[].reasoningDefault），然后是全局默认值（agents.defaults.reasoningDefault），最后是回退（off）。

格式错误的本地模型推理标签会被保守处理。闭合的 <think>...</think> 块在普通回复中保持隐藏，已可见文本之后未闭合的推理也会被隐藏。如果回复完全包裹在单个未闭合的起始标签中，且否则会作为空文本交付，OpenClaw 会移除格式错误的起始标签并交付剩余文本。

相关

• 提权模式文档位于 提权模式。

Heartbeats

• Heartbeat 探测正文是已配置的 Heartbeat 提示（默认：Read HEARTBEAT.md if it exists (workspace context). Follow it strictly. Do not infer or repeat old tasks from prior chats. If nothing needs attention, reply HEARTBEAT_OK.）。Heartbeat 消息中的内联指令照常应用（但应避免从 Heartbeats 更改会话默认值）。
• Heartbeat 交付默认仅发送最终 payload。若还要发送单独的 Reasoning: 消息（可用时），请设置 agents.defaults.heartbeat.includeReasoning: true 或每智能体 agents.list[].heartbeat.includeReasoning: true。

Web 聊天 UI

• Web 聊天思考选择器会在页面加载时，从入站会话存储/配置中映射该会话已存储的等级。
• 选择其他等级会立即通过 sessions.patch 写入会话覆盖项；它不会等到下一次发送，也不是一次性的 thinkingOnce 覆盖项。
• 第一个选项始终是清除覆盖项的选择。当会话继承的是非关闭状态的有效默认值时，它显示 Inherited: <resolved level>；当继承的思考已禁用时，它显示 Off。
• 显式选择器选项会标记为覆盖项，同时在存在提供商标签时保留该标签（例如，对于提供商标记的 max 选项，显示为 Override: maximum）。
• 选择器使用 Gateway 网关会话行/默认值返回的 thinkingLevels，并将 thinkingOptions 保留为旧版标签列表。浏览器界面不会保留自己的提供商正则表达式列表；插件拥有模型专属的等级集合。
• /think:<level> 仍然可用，并会更新同一个已存储会话等级，因此聊天指令和选择器会保持同步。

提供商配置档案

• 提供商插件可以公开 resolveThinkingProfile(ctx)，用于定义模型支持的等级和默认值。
• 代理 Claude 模型的提供商插件应复用 openclaw/plugin-sdk/provider-model-shared 中的 resolveClaudeThinkingProfile(modelId)，以便直接 Anthropic 目录和代理目录保持一致。
• 每个配置档案等级都有一个已存储的规范 id（off、minimal、low、medium、high、xhigh、adaptive 或 max），并且可以包含一个显示用 label。二元提供商使用 { id: "low", label: "on" }。
• 需要验证显式思考覆盖项的工具插件应使用 api.runtime.agent.resolveThinkingPolicy({ provider, model }) 加上 api.runtime.agent.normalizeThinkingLevel(...)；它们不应保留自己的提供商/模型等级列表。
• 能访问已配置自定义模型元数据的工具插件可以将 catalog 传入 resolveThinkingPolicy，这样 compat.supportedReasoningEfforts 的选择加入会反映在插件侧验证中。
• 已发布的旧版钩子（supportsXHighThinking、isBinaryThinking 和 resolveDefaultThinkingLevel）仍作为兼容适配器保留，但新的自定义等级集合应使用 resolveThinkingProfile。
• Gateway 网关行/默认值会公开 thinkingLevels、thinkingOptions 和 thinkingDefault，这样 ACP/聊天客户端会渲染与运行时验证所用一致的配置档案 ID 和标签。

📄 Web 搜索

原文：https://docs.openclaw.ai/zh-CN/tools/web

web_search 工具会使用你配置的提供商搜索 Web，并返回结果。结果会按查询缓存 15 分钟（可配置）。

OpenClaw 还包含用于搜索 X（原 Twitter）帖子的 x_search，以及用于轻量级 URL 获取的 web_fetch。在此阶段，web_fetch 保持本地执行，而 web_search 和 x_search 可以在底层使用 xAI Responses。

web_search 是一个轻量级 HTTP 工具，不是浏览器自动化。对于
JS 密集型网站或登录，请使用 Web Browser。对于
获取特定 URL，请使用 Web Fetch。

快速开始

选择一个提供商并完成任何必需的设置。有些提供商无需密钥，而另一些使用 API 密钥。详情请参阅下面的提供商页面。


bash
openclaw configure --section web
这会存储提供商和任何所需凭证。你也可以设置环境变量（例如 BRAVE_API_KEY），并跳过 API 支持提供商的此步骤。


智能体现在可以调用 web_search：

```javascript
await web_search({ query: "OpenClaw plugin SDK" });
```

对于 X 帖子，请使用：

```javascript
await x_search({ query: "dinner recipes" });
```

选择提供商

带摘要片段的结构化结果。支持 llm-context 模式、国家/地区和语言筛选。提供免费层级。


无需密钥的后备选项。无需 API 密钥。基于非官方 HTML 的集成。


神经 + 关键词搜索，并支持内容提取（高亮、文本、摘要）。


结构化结果。最适合与 firecrawl_search 和 firecrawl_scrape 搭配进行深度提取。


通过 Google Search grounding 提供带引用的 AI 综合答案。


通过 xAI Web grounding 提供带引用的 AI 综合答案。


通过 Moonshot Web 搜索提供带引用的 AI 综合答案；未 grounding 的聊天后备会显式失败。


通过 MiniMax Token Plan 搜索 API 提供结构化结果。


通过已登录的本地 Ollama 主机或托管的 Ollama API 进行搜索。


带内容提取控制和域名筛选的结构化结果。


自托管元搜索。无需 API 密钥。聚合 Google、Bing、DuckDuckGo 等。


结构化结果，支持搜索深度、主题筛选，以及用于 URL 提取的 tavily_extract。

提供商对比

自动检测

原生 OpenAI Web 搜索

当启用 OpenClaw Web 搜索且未固定托管提供商时，直接的 OpenAI Responses 模型会自动使用 OpenAI 托管的 web_search 工具。这是内置 OpenAI 插件中由提供商拥有的行为，并且仅适用于原生 OpenAI API 流量，不适用于 OpenAI 兼容代理基础 URL 或 Azure 路由。将 tools.web.search.provider 设置为其他提供商（例如 brave）可为 OpenAI 模型保留托管的 web_search 工具，或者将 tools.web.search.enabled: false 设置为禁用托管搜索和原生 OpenAI 搜索。

原生 Codex Web 搜索

支持 Codex 的模型可以选择使用提供商原生 Responses web_search 工具，而不是 OpenClaw 托管的 web_search 函数。

• 在 tools.web.search.openaiCodex 下配置它
• 它仅对支持 Codex 的模型激活（openai-codex/* 或使用 api: "openai-codex-responses" 的提供商）
• 托管的 web_search 仍适用于非 Codex 模型
• mode: "cached" 是默认且推荐的设置
• tools.web.search.enabled: false 会禁用托管搜索和原生搜索

{
  tools: {
    web: {
      search: {
        enabled: true,
        openaiCodex: {
          enabled: true,
          mode: "cached",
          allowedDomains: ["example.com"],
          contextSize: "high",
          userLocation: {
            country: "US",
            city: "New York",
            timezone: "America/New_York",
          },
        },
      },
    },
  },
}

如果启用了原生 Codex 搜索，但当前模型不支持 Codex，OpenClaw 会保留正常的托管 web_search 行为。

网络安全

托管的 web_search 提供商调用使用 OpenClaw 的受保护 fetch 路径。对于受信任的提供商 API 主机，OpenClaw 仅针对该提供商主机名允许 Surge、Clash 和 sing-box 在 198.18.0.0/15 与 fc00::/7 范围内的 fake-IP DNS 响应。其他私有、loopback、链路本地和元数据目标仍会被阻止。

此自动允许不适用于任意 web_fetch URL。对于 web_fetch，仅当你的受信任代理拥有这些合成范围时，才显式启用 tools.web.fetch.ssrfPolicy.allowRfc2544BenchmarkRange 和 tools.web.fetch.ssrfPolicy.allowIpv6UniqueLocalRange。

设置 Web 搜索

文档和设置流程中的提供商列表按字母顺序排列。自动检测会保留单独的优先级顺序。

如果未设置 provider，OpenClaw 会按以下顺序检查提供商，并使用第一个已就绪的提供商：

首先是 API 支持的提供商：

1. Brave -- BRAVE_API_KEY 或 plugins.entries.brave.config.webSearch.apiKey（顺序 10）
2. MiniMax Search -- MINIMAX_CODE_PLAN_KEY / MINIMAX_CODING_API_KEY / MINIMAX_OAUTH_TOKEN / MINIMAX_API_KEY 或 plugins.entries.minimax.config.webSearch.apiKey（顺序 15）
3. Gemini -- plugins.entries.google.config.webSearch.apiKey、GEMINI_API_KEY 或 models.providers.google.apiKey（顺序 20）
4. Grok -- XAI_API_KEY 或 plugins.entries.xai.config.webSearch.apiKey（顺序 30）
5. Kimi -- KIMI_API_KEY / MOONSHOT_API_KEY 或 plugins.entries.moonshot.config.webSearch.apiKey（顺序 40）
6. Perplexity -- PERPLEXITY_API_KEY / OPENROUTER_API_KEY 或 plugins.entries.perplexity.config.webSearch.apiKey（顺序 50）
7. Firecrawl -- FIRECRAWL_API_KEY 或 plugins.entries.firecrawl.config.webSearch.apiKey（顺序 60）
8. Exa -- EXA_API_KEY 或 plugins.entries.exa.config.webSearch.apiKey；可选的 plugins.entries.exa.config.webSearch.baseUrl 会覆盖 Exa 端点（顺序 65）
9. Tavily -- TAVILY_API_KEY 或 plugins.entries.tavily.config.webSearch.apiKey（顺序 70）

之后是无需密钥的后备选项：

10. DuckDuckGo -- 无需账户或 API 密钥的无密钥 HTML 后备选项（顺序 100）
11. Ollama Web 搜索 -- 当你配置的本地 Ollama 主机可访问并已通过 ollama signin 登录时，通过它提供无需密钥的后备选项；当主机需要时可复用 Ollama 提供商 bearer 认证，并且在配置 OLLAMA_API_KEY 后可调用直接的 https://ollama.com 搜索（顺序 110）
12. SearXNG -- SEARXNG_BASE_URL 或 plugins.entries.searxng.config.webSearch.baseUrl（顺序 200）

如果未检测到提供商，它会回退到 Brave（你会收到缺少密钥的错误，提示你配置一个）。

所有提供商密钥字段都支持 SecretRef 对象。对于内置的 API 支持 Web 搜索提供商，包括 Brave、Exa、Firecrawl、Gemini、Grok、Kimi、MiniMax、Perplexity 和 Tavily，位于 plugins.entries.<plugin>.config.webSearch.apiKey 下的插件作用域 SecretRef 都会被解析；无论提供商是通过 tools.web.search.provider 显式选择，还是通过自动检测选中。在自动检测模式下，OpenClaw 只解析选中的提供商密钥 -- 未选中的 SecretRef 保持非活动状态，因此你可以配置多个提供商，而无需为未使用的提供商支付解析成本。

配置

{
  tools: {
    web: {
      search: {
        enabled: true, // default: true
        provider: "brave", // or omit for auto-detection
        maxResults: 5,
        timeoutSeconds: 30,
        cacheTtlMinutes: 15,
      },
    },
  },
}

提供商专用配置（API 密钥、基础 URL、模式）位于
plugins.entries.<plugin>.config.webSearch.* 下。Gemini 还可以复用
models.providers.google.apiKey 和 models.providers.google.baseUrl，作为优先级较低的
回退项，在其专用 Web 搜索配置和 GEMINI_API_KEY 之后使用。示例见
提供商页面。

tools.web.search.provider 会根据内置和已安装插件清单声明的 Web 搜索提供商 ID
进行验证。像 "brvae" 这样的拼写错误会导致配置验证失败，而不是静默回退到自动检测。如果
配置的提供商只有过期的插件证据，例如卸载第三方插件后残留的
plugins.entries.<plugin> 块，OpenClaw 会保持启动韧性并报告警告，方便你重新安装
插件，或运行 openclaw doctor --fix 清理过期配置。

web_fetch 回退提供商选择是独立的：

• 使用 tools.web.fetch.provider 选择它
• 或省略该字段，让 OpenClaw 从可用凭证中自动检测第一个就绪的 Web 抓取
  提供商
• 非沙箱隔离的 web_fetch 可以使用声明了
  contracts.webFetchProviders 的已安装插件提供商；沙箱隔离的抓取保持仅限内置
• 目前内置的 Web 抓取提供商是 Firecrawl，配置位于
  plugins.entries.firecrawl.config.webFetch.* 下

当你在 openclaw onboard 或
openclaw configure --section web 期间选择 Kimi 时，OpenClaw 还可以询问：

• Moonshot API 区域（https://api.moonshot.ai/v1 或 https://api.moonshot.cn/v1）
• 默认 Kimi Web 搜索模型（默认为 kimi-k2.6）

对于 x_search，配置 plugins.entries.xai.config.xSearch.*。它使用与聊天相同的
xAI 凭证配置，或 Grok Web 搜索使用的 XAI_API_KEY / 插件 Web 搜索
凭证。
旧版 tools.web.x_search.* 配置会由 openclaw doctor --fix 自动迁移。
当你在 openclaw onboard 或 openclaw configure --section web 期间选择 Grok 时，
OpenClaw 还可以使用同一密钥提供可选的 x_search 设置。
这是 Grok 路径中的一个单独后续步骤，不是单独的顶层
Web 搜索提供商选择。如果你选择其他提供商，OpenClaw 不会
显示 x_search 提示。

存储 API 密钥

运行 openclaw configure --section web，或直接设置密钥：

```json5
{
  plugins: {
    entries: {
      brave: {
        config: {
          webSearch: {
            apiKey: "YOUR_KEY", // pragma: allowlist secret
          },
        },
      },
    },
  },
}
```

在 Gateway 网关进程环境中设置提供商环境变量：

```bash
export BRAVE_API_KEY="YOUR_KEY"
```

对于 Gateway 网关安装，请将它放在 `~/.openclaw/.env` 中。
请参阅 [环境变量](/zh-CN/help/faq#env-vars-and-env-loading)。

工具参数

并非所有参数都适用于所有提供商。Brave llm-context 模式
会拒绝 ui_lang；date_before 也需要 date_after，因为 Brave 自定义
新鲜度范围同时需要开始日期和结束日期。
Gemini、Grok 和 Kimi 会返回一个带引用的综合答案。它们
接受 count 以兼容共享工具，但它不会改变
有依据答案的形态。Gemini 支持 freshness、date_after 和
date_before，方式是将它们转换为 Google Search grounding 时间范围。
当你使用 Sonar/OpenRouter 兼容路径（plugins.entries.perplexity.config.webSearch.baseUrl /
model 或 OPENROUTER_API_KEY）时，Perplexity 的行为相同。
SearXNG 仅对受信任的专用网络或 loopback 主机接受 http://；
公共 SearXNG 端点必须使用 https://。
Firecrawl 和 Tavily 通过 web_search
仅支持 query 和 count，高级选项请使用它们的专用工具。

x_search

x_search 使用 xAI 查询 X（原 Twitter）帖子，并返回
带引用的 AI 综合答案。它接受自然语言查询和
可选的结构化筛选条件。OpenClaw 仅在服务此工具调用的请求上启用内置 xAI x_search
工具。

xAI 文档说明 x_search 支持关键词搜索、语义搜索、用户
搜索和线程抓取。对于单帖互动统计，例如转帖、
回复、收藏或浏览量，建议对确切帖子 URL
或状态 ID 进行定向查询。宽泛的关键词搜索可能找到正确帖子，但返回的
单帖元数据可能不够完整。一个好的模式是：先定位帖子，然后
运行第二个聚焦该确切帖子的 x_search 查询。

x_search 配置

{
  plugins: {
    entries: {
      xai: {
        config: {
          xSearch: {
            enabled: true,
            model: "grok-4-1-fast-non-reasoning",
            baseUrl: "https://api.x.ai/v1", // optional, overrides webSearch.baseUrl
            inlineCitations: false,
            maxTurns: 2,
            timeoutSeconds: 30,
            cacheTtlMinutes: 15,
          },
          webSearch: {
            apiKey: "xai-...", // optional if an xAI auth profile or XAI_API_KEY is set
            baseUrl: "https://api.x.ai/v1", // optional shared xAI Responses base URL
          },
        },
      },
    },
  },
}

当设置了 plugins.entries.xai.config.xSearch.baseUrl 时，
x_search 会发布到 <baseUrl>/responses。如果省略该字段，
它会回退到 plugins.entries.xai.config.webSearch.baseUrl，然后是
旧版 tools.web.search.grok.baseUrl，最后是公共 xAI 端点。

x_search 参数

x_search 示例

await x_search({
  query: "dinner recipes",
  allowed_x_handles: ["nytfood"],
  from_date: "2026-03-01",
});

// Per-post stats: use the exact status URL or status ID when possible
await x_search({
  query: "https://x.com/huntharo/status/1905678901234567890",
});

示例

// Basic search
await web_search({ query: "OpenClaw plugin SDK" });

// German-specific search
await web_search({ query: "TV online schauen", country: "DE", language: "de" });

// Recent results (past week)
await web_search({ query: "AI developments", freshness: "week" });

// Date range
await web_search({
  query: "climate research",
  date_after: "2024-01-01",
  date_before: "2024-06-30",
});

// Domain filtering (Perplexity only)
await web_search({
  query: "product reviews",
  domain_filter: ["-reddit.com", "-pinterest.com"],
});

工具配置档案

如果你使用工具配置档案或允许列表，请添加 web_search、x_search 或 group:web：

{
  tools: {
    allow: ["web_search", "x_search"],
    // or: allow: ["group:web"]  (includes web_search, x_search, and web_fetch)
  },
}

相关内容

• Web 抓取 -- 抓取 URL 并提取可读内容
• Web 浏览器 -- 用于 JS 密集型站点的完整浏览器自动化
• Grok 搜索 -- 将 Grok 作为 web_search 提供商
• Ollama Web 搜索 -- 通过你的 Ollama 主机进行无需密钥的 Web 搜索