工具和插件

智能体在生成文本之外做的所有事情都通过工具完成。 工具让智能体能够读取文件、运行命令、浏览 Web、发送 消息，并与设备交互。

# 工具、Skills 和插件

OpenClaw 有三层协同工作：

# 内置工具

这些工具随 OpenClaw 发布，无需安装任何插件即可使用：

工具	作用	页面
exec / process	运行 shell 命令，管理后台进程	Exec, Exec 审批
code_execution	运行沙箱隔离的远程 Python 分析	代码执行
browser	控制 Chromium 浏览器（导航、点击、截图）	浏览器
web_search / x_search / web_fetch	搜索 Web、搜索 X 帖子、抓取页面内容	Web, Web 抓取
read / write / edit	工作区中的文件 I/O
apply_patch	多段文件补丁	应用补丁
message	跨所有渠道发送消息	智能体发送
canvas	驱动节点 Canvas（展示、求值、快照）
nodes	发现并定位已配对设备
cron / gateway	管理定时任务；检查、修补、重启或更新 Gateway 网关
image / image_generate	分析或生成图像	图像生成
music_generate	生成音乐曲目	音乐生成
video_generate	生成视频	视频生成
tts	一次性文本转语音转换	TTS
sessions_* / subagents / agents_list	会话管理、Status 和子智能体编排	子智能体
session_status	轻量级 /status 风格回读和会话模型覆盖	会话工具

处理图像时，使用 image 进行分析，使用 image_generate 进行生成或编辑。如果你面向 openai/*、google/*、fal/* 或其他非默认图像提供商，请先配置该提供商的身份验证/API key。

处理音乐时，使用 music_generate。如果你面向 google/*、minimax/* 或其他非默认音乐提供商，请先配置该提供商的身份验证/API key。

处理视频时，使用 video_generate。如果你面向 qwen/* 或其他非默认视频提供商，请先配置该提供商的身份验证/API key。

对于由工作流驱动的音频生成，当 ComfyUI 等插件注册了 music_generate 时使用它。这不同于用于文本转语音的 tts。

session_status 是会话组中的轻量级 Status/回读工具。 它会回答关于当前会话的 /status 风格问题，并且可以 可选地设置每会话模型覆盖；model=default 会清除该 覆盖。与 /status 一样，它可以从最新转录使用记录中 回填稀疏的 token/cache 计数器和活动运行时模型标签。

gateway 是用于 Gateway 网关操作的仅所有者运行时工具：

• config.schema.lookup 用于在编辑前查看一个限定路径的配置子树
• config.get 用于当前配置快照 + 哈希
• config.patch 用于带重启的部分配置更新
• config.apply 仅用于完整配置替换
• update.run 用于显式自更新 + 重启

对于部分更改，优先使用 config.schema.lookup，然后使用 config.patch。仅当你有意替换整个配置时才使用 config.apply。 如需更完整的配置文档，请阅读配置和 配置参考。 该工具还会拒绝更改 tools.exec.ask 或 tools.exec.security； 旧版 tools.bash.* 别名会规范化到相同的受保护 exec 路径。

# 插件提供的工具

插件可以注册额外工具。一些示例：

• Diffs — diff 查看器和渲染器
• LLM 任务 — 用于结构化输出的仅 JSON LLM 步骤
• Lobster — 带可恢复审批的类型化工作流运行时
• 音乐生成 — 由工作流支持的提供商共享的 music_generate 工具
• OpenProse — markdown 优先的工作流编排
• Tokenjuice — 压缩嘈杂的 exec 和 bash 工具结果

插件工具仍然使用 api.registerTool(...) 编写，并在 插件清单的 contracts.tools 列表中声明。OpenClaw 会在发现期间捕获经过验证的 工具描述符，并按插件来源和契约缓存它，因此 后续工具规划可以跳过插件运行时加载。工具执行仍会加载 所属插件并调用实时注册的实现。

# 工具配置

# 允许和拒绝列表

通过配置中的 tools.allow / tools.deny 控制智能体可以调用哪些工具。 拒绝始终优先于允许。

{
  tools: {
    allow: ["group:fs", "browser", "web_search"],
    deny: ["exec"],
  },
}

当显式允许列表解析不到任何可调用工具时，OpenClaw 会以关闭方式失败。 例如，tools.allow: ["query_db"] 只有在已加载插件确实 注册了 query_db 时才有效。如果没有任何内置工具、插件或内置 MCP 工具匹配 允许列表，运行会在模型调用前停止，而不是继续作为 可能幻觉出工具结果的纯文本运行。

# 工具配置文件

tools.profile 会在应用 allow/deny 前设置一个基础允许列表。 每智能体覆盖：agents.list[].tools.profile。

配置文件	包含内容
full	所有核心和可选插件工具；用于更广泛命令/控制访问的不受限基线
coding	group:fs、group:runtime、group:web、group:sessions、group:memory、cron、image、image_generate、music_generate、video_generate
messaging	group:messaging、sessions_list、sessions_history、sessions_send、session_status
minimal	仅 session_status

coding 包含轻量 Web 工具（web_search、web_fetch、x_search）， 但不包含完整的浏览器控制工具。浏览器自动化可以驱动真实 会话和已登录配置文件，因此请使用 tools.alsoAllow: ["browser"] 或每智能体 agents.list[].tools.alsoAllow: ["browser"] 显式添加它。

coding 和 messaging 配置文件还允许插件键 bundle-mcp 下 已配置的内置 MCP 工具。当你希望 某个配置文件保留其常规内置工具但隐藏所有已配置 MCP 工具时，添加 tools.deny: ["bundle-mcp"]。 minimal 配置文件不包含内置 MCP 工具。

示例（默认使用最广的工具范围）：

{
  tools: {
    profile: "full",
  },
}

# 工具组

在允许/拒绝列表中使用 group:* 简写：

组	工具
group:runtime	exec, process, code_execution（bash 可作为 exec 的别名）
group:fs	read, write, edit, apply_patch
group:sessions	sessions_list, sessions_history, sessions_send, sessions_spawn, sessions_yield, subagents, session_status
group:memory	memory_search, memory_get
group:web	web_search, x_search, web_fetch
group:ui	browser, canvas
group:automation	heartbeat_respond, cron, gateway
group:messaging	message
group:nodes	nodes
group:agents	agents_list, update_plan
group:media	image, image_generate, music_generate, video_generate, tts
group:openclaw	所有内置 OpenClaw 工具（不包括插件工具）

sessions_history 返回一个有界且经过安全过滤的回忆视图。它会从助手文本中剥离 思考标签、<relevant-memories> 结构、明文工具调用 XML 载荷（包括 <tool_call>...</tool_call>、 <function_call>...</function_call>、<tool_calls>...</tool_calls>、 <function_calls>...</function_calls> 以及被截断的工具调用块）、 降级后的工具调用结构、泄漏的 ASCII/全角模型控制 token，以及格式错误的 MiniMax 工具调用 XML，然后应用 遮盖/截断以及可能的超大行占位符，而不是作为原始对话记录转储。

# 提供商特定限制

使用 tools.byProvider 限制特定提供商的工具，而无需 更改全局默认值：

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