OpenClaw从入门到应用——工具（Tools）

通过OpenClaw实现副业收入《OpenClaw赚钱实录从“养龙虾“到可持续变现的实践指南》OpenClaw 提供了一流的代理工具用于浏览器、画布、节点和定时任务。这些工具取代了旧的openclaw-*技能新工具是带类型的不再通过 shell 调用代理应直接依赖它们。禁用工具你可以通过openclaw.json中的tools.allow/tools.deny来全局允许/禁用工具deny优先。这可以阻止被禁用的工具被发送给模型提供商。{ tools: { deny: [browser] }, }注意匹配时不区分大小写。支持*通配符*表示所有工具。如果tools.allow只引用了未知或未加载的插件工具名称OpenClaw 会记录警告并忽略该允许列表以便核心工具保持可用。工具配置文件基础允许列表tools.profile在应用tools.allow/tools.deny之前设置一个基础工具允许列表。代理级覆盖agents.list[].tools.profile。配置文件minimal仅session_statuscodinggroup:fs,group:runtime,group:sessions,group:memory,imagemessaginggroup:messaging,sessions_list,sessions_history,sessions_send,session_statusfull无限制与未设置相同示例默认仅限消息功能同时也允许 Slack Discord 工具{ tools: { profile: messaging, allow: [slack, discord], }, }示例使用编码配置文件但全局禁用 exec/process{ tools: { profile: coding, deny: [group:runtime], }, }示例全局编码配置文件仅支持消息功能的代理{ tools: { profile: coding }, agents: { list: [ { id: support, tools: { profile: messaging, allow: [slack] }, }, ], }, }特定于提供商的工具策略使用tools.byProvider可以针对特定提供商或单个provider/model进一步限制工具而无需更改全局默认设置。代理级覆盖agents.list[].tools.byProvider。此策略在基础工具配置文件之后、允许/禁用列表之前应用因此它只能缩小工具集。提供商的键可以接受provider例如google-antigravity或provider/model例如openai/gpt-5.2。示例保持全局编码配置文件但对 Google Antigravity 使用最小工具集{ tools: { profile: coding, byProvider: { google-antigravity: { profile: minimal }, }, }, }示例针对不稳定端点的特定提供商/模型允许列表{ tools: { allow: [group:fs, group:runtime, sessions_list], byProvider: { openai/gpt-5.2: { allow: [group:fs, sessions_list] }, }, }, }示例针对单个提供商的代理特定覆盖{ agents: { list: [ { id: support, tools: { byProvider: { google-antigravity: { allow: [message, sessions_list] }, }, }, }, ], }, }工具组简写工具策略全局、代理、沙箱支持group:*条目这些条目会展开为多个工具。在tools.allow/tools.deny中使用它们。可用的组group:runtimeexec,bash,processgroup:fsread,write,edit,apply_patchgroup:sessionssessions_list,sessions_history,sessions_send,sessions_spawn,session_statusgroup:memorymemory_search,memory_getgroup:webweb_search,web_fetchgroup:uibrowser,canvasgroup:automationcron,gatewaygroup:messagingmessagegroup:nodesnodesgroup:openclaw所有 OpenClaw 内置工具不包括提供商插件示例仅允许文件工具 浏览器{ tools: { allow: [group:fs, browser], }, }插件 工具插件可以注册额外的工具和 CLI 命令超越核心集。安装和配置请参阅插件有关如何将工具使用指南注入提示的信息请参阅技能。一些插件会随工具一起提供自己的技能例如语音通话插件。可选的插件工具Lobster带可恢复审批的类型化工作流运行时需要在网关主机上安装 Lobster CLI。LLM Task仅限 JSON 的 LLM 步骤用于结构化工作流输出可选的模式验证。Diffs只读差异查看器和 PNG 或 PDF 文件渲染器用于前后文本或统一补丁。工具清单apply_patch跨一个或多个文件应用结构化补丁。用于多块编辑。实验性功能通过tools.exec.applyPatch.enabled启用仅限 OpenAI 模型。tools.exec.applyPatch.workspaceOnly默认为true限制在工作区内。只有当你故意希望apply_patch在工作区目录之外写入/删除时才将其设置为false。exec在工作区中运行 shell 命令。核心参数command必需yieldMs超时后自动后台运行默认 10000background立即后台运行timeout秒如果超过则终止进程默认 1800elevated布尔值如果启用了提权模式且被允许则在主机上运行仅在代理被沙箱化时改变行为hostsandbox | gateway | nodesecuritydeny | allowlist | fullaskoff | on-miss | alwaysnode用于hostnode的节点 ID/名称需要真正的 TTY设置pty: true。注意当后台运行时返回带有sessionId的status: running。使用process来轮询/记录/写入/终止/清理后台会话。如果process被禁用exec将同步运行并忽略yieldMs/background。elevated受tools.elevated以及任何agents.list[].tools.elevated覆盖的限制两者都必须允许并且是hostgatewaysecurityfull的别名。elevated仅在代理被沙箱化时改变行为否则无操作。hostnode可以针对 macOS 配套应用程序或无头节点主机openclaw node run。网关/节点审批和允许列表Exec 审批。process管理后台 exec 会话。核心操作list,poll,log,write,kill,clear,remove注意poll在完成时返回新的输出和退出状态。log支持基于行的offset/limit省略offset以获取最后 N 行。process的作用域是每个代理来自其他代理的会话不可见。loop-detection工具调用循环防护OpenClaw 会跟踪最近的工具调用历史并在检测到重复的无进展循环时阻止或发出警告。通过tools.loopDetection.enabled: true启用默认为false。{ tools: { loopDetection: { enabled: true, warningThreshold: 10, criticalThreshold: 20, globalCircuitBreakerThreshold: 30, historySize: 30, detectors: { genericRepeat: true, knownPollNoProgress: true, pingPong: true, }, }, }, }genericRepeat重复相同工具 相同参数的调用模式。knownPollNoProgress重复的类似轮询工具且输出相同。pingPong交替A/B/A/B无进展模式。代理级覆盖agents.list[].tools.loopDetection。web_search使用 Perplexity、Brave、Gemini、Grok 或 Kimi 搜索网络。核心参数query必需count1–10默认来自tools.web.search.maxResults注意需要所选提供商的 API 密钥推荐openclaw configure --section web。通过tools.web.search.enabled启用。响应会被缓存默认 15 分钟。设置请参阅 Web 工具。web_fetch从 URL 获取并提取可读内容HTML → markdown/text。核心参数url必需extractModemarkdown|textmaxChars截断长页面注意通过tools.web.fetch.enabled启用。maxChars受tools.web.fetch.maxCharsCap限制默认 50000。响应会被缓存默认 15 分钟。对于 JS 密集型网站优先使用浏览器工具。设置请参阅 Web 工具。请参阅 Firecrawl 了解可选的防机器人回退。browser控制由 OpenClaw 管理的专用浏览器。核心操作status,start,stop,tabs,open,focus,closesnapshotaria/aiscreenshot返回图像块 MEDIA:pathactUI 操作click/type/press/hover/drag/select/fill/resize/wait/evaluatenavigate,console,pdf,upload,dialog配置文件管理profiles— 列出所有浏览器配置文件及其状态create-profile— 使用自动分配的端口或cdpUrl创建新配置文件delete-profile— 停止浏览器删除用户数据从配置中移除仅本地reset-profile— 终止配置文件端口上的孤立进程仅本地常用参数profile可选默认为browser.defaultProfiletargetsandbox|host|nodenode可选选择特定的节点 ID/名称注意需要browser.enabledtrue默认为true设置为false以禁用。所有操作都接受可选的profile参数以支持多实例。省略profile将使用安全的默认设置由 OpenClaw 管理的独立浏览器openclaw。当需要现有的登录信息/cookie 且用户在场以点击/批准任何附加提示时使用profileuser访问真实的本地主机浏览器。仅对 Chrome 扩展程序/工具栏按钮附加流程使用profilechrome-relay。profileuser和profilechrome-relay仅限主机不要将它们与沙箱/节点目标结合使用。当省略profile时使用browser.defaultProfile默认为openclaw。配置文件名称仅限小写字母数字和连字符最多 64 个字符。端口范围18800-18899最多约 100 个配置文件。远程配置文件仅可附加无法启动/停止/重置。如果连接了具有浏览器能力的节点该工具可能会自动路由到它除非你固定了target。当安装了 Playwright 时snapshot默认为ai使用aria获取无障碍树。snapshot也支持角色快照选项interactive,compact,depth,selector它们返回像e12这样的引用。act需要来自snapshot的ref来自 AI 快照的数字12或来自角色快照的e12在极少数需要 CSS 选择器的情况下使用evaluate。默认避免使用act→wait仅在特殊情况下使用没有可靠的 UI 状态可以等待。upload可以选择传递ref以在准备就绪后自动点击。upload也支持inputRefaria 引用或elementCSS 选择器来直接设置input typefile。canvas驱动节点画布present, eval, snapshot, A2UI。核心操作present,hide,navigate,evalsnapshot返回图像块 MEDIA:patha2ui_push,a2ui_reset注意在底层使用网关的node.invoke。如果没有提供node该工具会选择一个默认节点单个已连接节点或本地 mac 节点。A2UI 仅支持 v0.8没有createSurfaceCLI 会拒绝带有行错误的 v0.9 JSONL。快速测试openclaw nodes canvas a2ui push --node id --text Hello from A2UI。nodes发现并定位配对的节点发送通知捕获相机/屏幕。核心操作status,describepending,approve,reject配对notifymacOSsystem.notifyrunmacOSsystem.runcamera_list,camera_snap,camera_clip,screen_recordlocation_get,notifications_list,notifications_actiondevice_status,device_info,device_permissions,device_health注意相机/屏幕命令需要节点应用程序处于前台。图像返回图像块 MEDIA:path。视频返回FILE:pathmp4。位置返回 JSON 负载纬度/经度/精度/时间戳。run参数commandargv 数组可选的cwd,envKEYVAL,commandTimeoutMs,invokeTimeoutMs,needsScreenRecording。示例run{action:run,node:office-mac,command:[echo,Hello],env:[FOObar],commandTimeoutMs:12000,invokeTimeoutMs:45000,needsScreenRecording:false}image使用配置的图像模型分析图像。核心参数image必需的路径或 URLprompt可选默认为“描述图像。”model可选覆盖maxBytesMb可选大小限制注意仅在配置了agents.defaults.imageModel主模型或备用模型时可用或者可以从你的默认模型 配置的身份验证中推断出隐式图像模型时可用尽力而为的配对。直接使用图像模型独立于主聊天模型。pdf分析一个或多个 PDF 文档。有关完整行为、限制、配置和示例请参阅 PDF 工具。message跨 Discord/Google Chat/Slack/Telegram/WhatsApp/Signal/iMessage/MS Teams 发送消息和频道操作。核心操作send文本 可选媒体MS Teams 还支持用于自适应卡片的cardpollWhatsApp/Discord/MS Teams 投票react/reactions/read/edit/deletepin/unpin/list-pinspermissionsthread-create/thread-list/thread-replysearchstickermember-info/role-infoemoji-list/emoji-upload/sticker-uploadrole-add/role-removechannel-info/channel-listvoice-statusevent-list/event-createtimeout/kick/ban注意send通过网关路由 WhatsApp其他频道直接发送。poll对 WhatsApp 和 MS Teams 使用网关Discord 投票直接发送。当消息工具调用绑定到活动聊天会话时发送操作将被限制在该会话的目标范围内以避免跨上下文泄漏。cron管理网关定时任务和唤醒。核心操作status,listadd,update,remove,run,runswake将系统事件排队 可选立即心跳注意add需要一个完整的定时任务对象与cron.addRPC 相同的模式。update使用{ jobId, patch }为兼容性接受id。gateway重新启动或对正在运行的网关进程应用更新就地。核心操作restart授权并发送SIGUSR1进行进程内重启openclaw gateway就地重启config.schema.lookup一次检查一个配置路径而无需将完整模式加载到提示上下文中config.getconfig.apply验证 写入配置 重启 唤醒config.patch合并部分更新 重启 唤醒update.run运行更新 重启 唤醒注意config.schema.lookup需要一个目标配置路径例如gateway.auth或agents.list.*.heartbeat。路径在处理plugins.entries.id时可能包含斜杠分隔的插件 ID例如plugins.entries.pack/one.config。使用delayMs默认为 2000以避免中断正在进行的回复。config.schema仍然可用于内部控制 UI 流程不通过代理gateway工具公开。restart默认启用设置commands.restart: false以禁用它。sessions_list/sessions_history/sessions_send/sessions_spawn/session_status列出会话、检查记录历史或发送到另一个会话。核心参数sessions_listkinds?,limit?,activeMinutes?,messageLimit?0 无限制sessions_historysessionKey或sessionId,limit?,includeTools?sessions_sendsessionKey或sessionId,message,timeoutSeconds?0 即发即忘sessions_spawntask,label?,runtime?,agentId?,model?,thinking?,cwd?,runTimeoutSeconds?,thread?,mode?,cleanup?,sandbox?,streamTo?,attachments?,attachAs?session_statussessionKey?默认为当前接受sessionId,model?default清除覆盖注意main是规范的直接聊天键global/unknown 被隐藏。messageLimit 0为每个会话获取最后 N 条消息过滤掉工具消息。会话目标由tools.sessions.visibility控制默认为tree当前会话 生成的子代理会话。如果你为多个用户运行共享代理请考虑设置tools.sessions.visibility: self以防止跨会话浏览。当timeoutSeconds 0时sessions_send等待最终完成。传递/通知在完成后进行并且是尽力而为的status: ok确认代理运行已完成而不是通知已传递。sessions_spawn支持runtime: subagent | acpsubagent为默认值。有关 ACP 运行时行为请参阅 ACP 代理。对于 ACP 运行时streamTo: parent将初始运行进度摘要作为系统事件路由回请求者会话而不是直接传递子消息。sessions_spawn启动一个子代理运行并将一个通知回复发送回请求者聊天。支持一次性模式mode: run和持久线程绑定模式mode: session配合thread: true。如果thread: true且省略了mode则mode默认为session。mode: session需要thread: true。如果省略了runTimeoutSeconds当设置了agents.defaults.subagents.runTimeoutSeconds时OpenClaw 会使用该值否则超时默认为0无超时。Discord 线程绑定流程依赖于session.threadBindings.*和channels.discord.threadBindings.*。回复格式包括Status,Result和紧凑的统计信息。Result是助手的完成文本如果缺失则使用最新的toolResult作为回退。手动完成模式生成首先直接发送并在瞬时故障时进行队列回退和重试status: ok表示运行已完成不表示通知已传递。sessions_spawn支持子代理运行时的内联文件附件ACP 会拒绝它们。每个附件具有name,content可选的encodingutf8或base64和mimeType。文件被具体化到子工作区的.openclaw/attachments/uuid/中并附带一个.manifest.json元数据文件。该工具返回一个包含count,totalBytes、每个文件的sha256和relDir的收据。附件内容会自动从记录持久化中删除。通过tools.sessions_spawn.attachments配置限制enabled,maxTotalBytes,maxFiles,maxFileBytes,retainOnSessionKeep。attachAs.mountPath是为将来挂载实现保留的提示。sessions_spawn是非阻塞的并立即返回status: accepted。ACPstreamTo: parent响应可能包含streamLogPath会话范围的*.acp-stream.jsonl用于跟踪进度历史。sessions_send运行一个回复式乒乓回复REPLY_SKIP以停止最大回合数由session.agentToAgent.maxPingPongTurns决定0–5。在乒乓之后目标代理运行一个通知步骤回复ANNOUNCE_SKIP以抑制通知。沙箱限制当当前会话被沙箱化且agents.defaults.sandbox.sessionToolsVisibility: spawned时OpenClaw 将tools.sessions.visibility限制为tree。agents_list列出当前会话可能通过sessions_spawn定位的代理 ID。注意结果受每个代理的允许列表限制agents.list[].subagents.allowAgents。当配置为[*]时该工具包括所有已配置的代理并标记allowAny: true。参数通用基于网关的工具canvas,nodes,crongatewayUrl默认为ws://127.0.0.1:18789gatewayToken如果启用了身份验证timeoutMs注意当设置了gatewayUrl时请显式包含gatewayToken。工具不会继承覆盖的配置或环境凭据缺少显式凭据将被视为错误。浏览器工具profile可选默认为browser.defaultProfiletargetsandbox|host|nodenode可选固定特定的节点 ID/名称故障排除指南Linux 启动/CDP 问题浏览器故障排除LinuxWSL2 网关 Windows 远程 Chrome CDPWSL2 Windows 远程 Chrome CDP 故障排除推荐的代理流程浏览器自动化browser→status/startsnapshotai 或 ariaactclick/type/press如果需要视觉确认使用screenshot画布渲染canvas→presenta2ui_push可选snapshot节点定位nodes→status在所选节点上执行describenotify/run/camera_snap/screen_record安全性避免直接使用system.run仅在获得用户明确同意后使用nodes→run。尊重用户对相机/屏幕捕获的同意。在调用媒体命令之前使用status/describe确保权限。工具是如何呈现给代理的工具通过两个并行渠道公开系统提示文本人类可读的列表 指南。工具模式发送给模型 API 的结构化函数定义。这意味着代理既可以看到“存在哪些工具”也可以看到“如何调用它们”。如果某个工具没有出现在系统提示或模式中模型就无法调用它。