工具

OpenClaw 为浏览器、画布、节点和定时任务提供一流的代理工具。这些工具取代了旧的 openclaw-* 技能：工具是类型化的，无需 shell 调用，代理应该直接依赖它们。

禁用工具

你可以通过 openclaw.json 中的 tools.allow / tools.deny 全局允许/拒绝工具（deny 优先）。这可以防止不允许的工具被发送到模型提供商。


json
{
  "tools": { "deny": ["browser"] }
}

注意事项：

▹匹配不区分大小写
▹支持 * 通配符（"*" 表示所有工具）
▹如果 tools.allow 仅引用未知或未加载的插件工具名称，OpenClaw 会记录警告并忽略白名单，以便核心工具保持可用

工具配置文件（基础白名单）

tools.profile 在 tools.allow/tools.deny 之前设置基础工具白名单。

每个代理覆盖： agents.list[].tools.profile

配置文件：

▹minimal：仅 session_status
▹coding：group:fs、group:runtime、group:sessions、group:memory、image
▹messaging：group:messaging、sessions_list、sessions_history、sessions_send、session_status
▹full：无限制（与未设置相同）

示例（默认仅消息传递，也允许 Slack + Discord 工具）：


json
{
  "tools": {
    "profile": "messaging",
    "allow": ["slack", "discord"]
  }
}

工具组（简写）

工具策略支持扩展为多个工具的 group:* 条目。在 tools.allow / tools.deny 中使用这些。

可用组：

▹group:runtime：exec、bash、process
▹group:fs：read、write、edit、apply_patch
▹group:sessions：sessions_list、sessions_history、sessions_send、sessions_spawn、session_status
▹group:memory：memory_search、memory_get
▹group:web：web_search、web_fetch
▹group:ui：browser、canvas
▹group:automation：cron、gateway
▹group:messaging：message
▹group:nodes：nodes
▹group:openclaw：所有内置 OpenClaw 工具（不包括提供商插件）

核心工具清单

exec

在工作区中运行 shell 命令。

核心参数：

▹command（必需）
▹yieldMs（超时后自动后台运行，默认 10000）
▹background（立即后台运行）
▹timeout（秒；超时则终止进程，默认 1800）
▹elevated（布尔值；如果启用/允许提升模式，则在主机上运行）
▹host（sandbox | gateway | node）
▹security（deny | allowlist | full）
▹ask（off | on-miss | always）
▹node（host=node 时的节点 id/名称）

需要真正的 TTY？设置 pty: true。

process

管理后台 exec 会话。

核心操作： list、poll、log、write、kill、clear、remove

browser

控制专用的 OpenClaw 管理浏览器。

核心操作：

▹status、start、stop、tabs、open、focus、close
▹snapshot（aria/ai）
▹screenshot（返回图像块 + MEDIA:<path>）
▹act（UI 操作：click/type/press/hover/drag/select/fill/resize/wait/evaluate）
▹navigate、console、pdf、upload、dialog

配置文件管理：

▹profiles — 列出所有浏览器配置文件及状态
▹create-profile — 创建新配置文件，自动分配端口（或 cdpUrl）
▹delete-profile — 停止浏览器，删除用户数据，从配置中移除（仅本地）
▹reset-profile — 终止配置文件端口上的孤立进程（仅本地）

canvas

驱动节点 Canvas（present、eval、snapshot、A2UI）。

核心操作： present、hide、navigate、eval、snapshot、a2ui_push、a2ui_reset

nodes

发现和定位配对的节点；发送通知；捕获相机/屏幕。

核心操作：

▹status、describe
▹pending、approve、reject（配对）
▹notify（macOS system.notify）
▹run（macOS system.run）
▹camera_snap、camera_clip、screen_record
▹location_get

web_search

使用 Brave Search API 搜索网络。

核心参数：

▹query（必需）
▹count（1-10；默认来自 tools.web.search.maxResults）

需要 Brave API 密钥。

web_fetch

从 URL 获取并提取可读内容（HTML → markdown/text）。

核心参数：

▹url（必需）
▹extractMode（markdown | text）
▹maxChars（截断长页面）

image

使用配置的图像模型分析图像。

核心参数：

▹image（必需的路径或 URL）
▹prompt（可选；默认为"描述图像。"）
▹model（可选覆盖）
▹maxBytesMb（可选大小上限）

message

跨 Discord/Google Chat/Slack/Telegram/WhatsApp/Signal/iMessage/MS Teams 发送消息和渠道操作。

核心操作： send、poll、react、reactions、read、edit、delete、pin、unpin、list-pins、permissions、thread-create、thread-list、thread-reply、search、sticker、member-info、role-info、emoji-list、emoji-upload、sticker-upload、role-add、role-remove、channel-info、channel-list、voice-status、event-list、event-create、timeout、kick、ban

cron

管理网关定时任务和唤醒。

核心操作： status、list、add、update、remove、run、runs、wake

gateway

重启或对运行中的网关进程应用更新（就地）。

核心操作：

▹restart（授权 + 发送 SIGUSR1 进行进程内重启）
▹config.get / config.schema
▹config.apply（验证 + 写入配置 + 重启 + 唤醒）
▹config.patch（合并部分更新 + 重启 + 唤醒）
▹update.run（运行更新 + 重启 + 唤醒）

sessions_list / sessions_history / sessions_send / sessions_spawn / session_status

列出会话、检查转录历史或发送到另一个会话。

核心参数：

▹sessions_list：kinds?、limit?、activeMinutes?、messageLimit?（0 = 无）
▹sessions_history：sessionKey（或 sessionId）、limit?、includeTools?
▹sessions_send：sessionKey（或 sessionId）、message、timeoutSeconds?（0 = 即发即弃）
▹sessions_spawn：task、label?、agentId?、model?、thinking?、runTimeoutSeconds?、thread?、mode?、cleanup?
▹session_status：sessionKey?（默认当前；接受 sessionId）、model?（默认清除覆盖）

memory_search / memory_get

对 MEMORY.md + memory/*.md 进行向量搜索。

apply_patch

跨一个或多个文件应用结构化补丁。用于多块编辑。

实验性： 通过 tools.exec.applyPatch.enabled 启用（仅 OpenAI 模型）。

循环检测（工具调用循环防护）

OpenClaw 跟踪最近的工具调用历史，并在检测到重复的无进展循环时阻止或警告。

通过 tools.loopDetection.enabled: true 启用（默认为 false）。


json
{
  "tools": {
    "loopDetection": {
      "enabled": true,
      "warningThreshold": 10,
      "criticalThreshold": 20,
      "globalCircuitBreakerThreshold": 30,
      "historySize": 30,
      "detectors": {
        "genericRepeat": true,
        "knownPollNoProgress": true,
        "pingPong": true
      }
    }
  }
}

工具如何呈现给代理

工具通过两个并行渠道公开：

▹系统提示文本：人类可读的列表 + 指导
▹工具架构：发送到模型 API 的结构化函数定义

这意味着代理可以看到"存在哪些工具"和"如何调用它们"。如果工具未出现在系统提示或架构中，模型无法调用它。

工具

禁用工具

工具配置文件（基础白名单）

工具组（简写）

核心工具清单

exec

process

browser

canvas

nodes

web_search

web_fetch

image

message

cron

gateway

sessions_list / sessions_history / sessions_send / sessions_spawn / session_status

memory_search / memory_get

apply_patch

循环检测（工具调用循环防护）

工具如何呈现给代理

下一步