工具总览

OpenClaw Agent 通过**内置工具（Tools）**与外界交互——读写文件、执行命令、控制浏览器、管理后台进程等。工具是 Agent 能力的核心扩展点。

工具控制策略

全局允许/禁止

通过 tools.allow 和 tools.deny 控制哪些工具可以被发送给模型（deny 优先级更高）：

{
  tools: { deny: ["browser"] },  // 禁用浏览器工具
}

• 匹配不区分大小写
• 支持 * 通配符（"*" 表示所有工具）
• 若 tools.allow 仅包含未知/未加载的工具名，OpenClaw 会发出警告并忽略该允许列表，保证核心工具可用

工具配置文件（Profile）

tools.profile 设置基础工具允许列表，Per-Agent 可通过 agents.list[].tools.profile 覆盖：

Profile	包含工具
minimal	仅 session_status
coding	文件组、运行时组、会话组、记忆组、image
messaging	消息发送/接收相关工具
full	无限制（与未设置相同）

// 示例：消息助手默认只开放消息工具，加上 Slack/Discord
{
  tools: {
    profile: "messaging",
    allow: ["slack", "discord"],
  },
}

// 示例：编码助手全局 coding profile，但支持 Agent 改用 messaging
{
  tools: { profile: "coding" },
  agents: {
    list: [
      {
        id: "support",
        tools: { profile: "messaging", allow: ["slack"] },
      },
    ],
  },
}

按 Provider 限制工具

tools.byProvider 可针对特定 Provider（或 provider/model）进一步收窄工具集，在全局 Profile 和 allow/deny 之间生效：

{
  tools: {
    profile: "coding",
    byProvider: {
      "google-antigravity": { profile: "minimal" },
    },
  },
}

工具组（快捷方式）

在 tools.allow / tools.deny 中使用 group:* 批量引用工具：

组名	包含工具
group:runtime	exec、bash、process
group:fs	read、write、edit、apply_patch
group:sessions	sessions 系列工具
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	所有内置工具（不含 Provider 插件）

// 只允许文件工具 + 浏览器
{
  tools: {
    allow: ["group:fs", "browser"],
  },
}

工具清单

文件系统工具

工具	功能
read	读取文件内容
write	写入文件
edit	精确字符串替换
apply_patch	应用多文件 diff 补丁（实验性，OpenAI 模型专用）

执行工具

工具	功能
exec	在工作区执行 Shell 命令，支持前台/后台
process	管理后台 exec 会话（poll/log/kill 等）

详见 exec 工具。

浏览器工具

工具	功能
browser	控制 OpenClaw 管理的 Chromium 浏览器
canvas	驱动 Node Canvas（展示、A2UI）

详见 浏览器工具。

网络工具

工具	功能
web_search	联网搜索（Perplexity/Brave/Gemini 等）
web_fetch	抓取 URL 内容（HTML → Markdown）

消息工具

工具	功能
message	跨渠道发送/接收/管理消息

message 工具支持 Discord、Google Chat、Slack、Telegram、WhatsApp、Signal、iMessage、MS Teams，操作包括发送、编辑、删除、置顶、投票、线程管理等。

记忆工具

工具	功能
memory_search	对工作区记忆进行语义检索
memory_get	读取指定记忆文件/行范围

系统工具

工具	功能
nodes	管理配对节点（macOS/iOS），发送通知、拍照、录屏
image	用图像模型分析图片
pdf	分析 PDF 文档
cron	管理定时任务（Gateway 调度器）
gateway	重启 Gateway、应用配置变更

会话工具

工具	功能
sessions_list	列出所有会话
sessions_history	查看会话对话历史
sessions_send	向另一个会话发消息
sessions_spawn	启动子 Agent 任务
session_status	查看/修改当前会话状态
agents_list	列出可用的 Agent（用于 sessions_spawn）

防循环检测

当 Agent 陷入重复调用工具但没有进展的循环时，可启用防循环检测：

{
  tools: {
    loopDetection: {
      enabled: true,
      warningThreshold: 10,
      criticalThreshold: 20,
      detectors: {
        genericRepeat: true,      // 相同工具+相同参数重复调用
        knownPollNoProgress: true, // poll 类工具输出无变化
        pingPong: true,           // A/B/A/B 交替无进展
      },
    },
  },
}

插件工具

插件可以注册额外工具。常见可选插件工具：

• Lobster：可恢复审批的工作流运行时
• LLM Task：结构化输出的 JSON-only LLM 步骤
• Diffs：只读 diff 查看器，可渲染 PNG/PDF

工具的注入方式

工具通过两个并行通道呈现给 Agent：

1. 系统提示文本：可读的工具列表 + 使用指导
2. Tool Schema：发送给模型 API 的结构化函数定义

两者缺一不可。如果工具未出现在系统提示或 Schema 中，模型无法调用它。