Skip to Content
👋 欢迎来到 HowToUseMoltbot 快速入门
工具工具

工具总览

Moltbot 提供一套强大的内置工具，赋予代理真实能力——从控制浏览器到执行 shell 命令、搜索网页、管理会话。与旧版需要 shell 调用的 moltbot-* 技能不同，这些是通过代理运行时直接工作的一等类型化工具。

可用工具

核心工具集包括：

  • 浏览器自动化：通过快照、点击与截图驱动 Chrome/Brave
  • Shell 执行：运行命令，支持后台与审批门控
  • Web 访问：搜索（Brave/Perplexity）与内容提取的页面抓取
  • 会话管理：列表、查看与跨代理会话发送消息
  • 节点控制：操作已配对的 macOS/iOS 设备，发送通知、使用摄像头、录屏
  • 调度：管理 cron 任务与唤醒事件
  • 网关操作：重启网关或原地应用配置更新
  • Canvas：驱动可视画布（仅 macOS 节点）
  • 图像分析：用配置的视觉模型分析图像

还有可选插件工具如 Lobster（工作流引擎）和 LLM Task（结构化 JSON 输出）。

访问控制

全局允许/拒绝

最简单的工具限制方式是在配置中使用 tools.allow 和 tools.deny。拒绝优先级更高。

{
  "tools": {
    "deny": ["browser", "exec"]
  }
}

支持 * 通配符，"*" 表示所有工具。匹配不区分大小写。

工具配置

无需逐个列举工具，可使用配置作为基线：

  • minimal：仅 session_status（只读会话信息）
  • coding：文件工具 + 运行时 + 会话 + 内存 + 图像分析
  • messaging：消息发送 + 基础会话工具
  • full：全部（等同于不设置配置）

可通过 agents.list[].tools.profile 按代理覆盖。

示例——默认为 messaging，但也允许 Slack 与 Discord 工具：

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

示例——全局 coding 配置，但拒绝 shell 执行：

{
  "tools": {
    "profile": "coding",
    "deny": ["group:runtime"]
  }
}

按提供商限制

有时你希望对特定模型提供商做更严格控制。使用 tools.byProvider 可根据提供商甚至特定模型收窄工具集。

此项在基础配置之后、全局 allow/deny 列表之前生效。

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

也可针对单一模型：

{
  "tools": {
    "byProvider": {
      "openai/gpt-5.2": { "allow": ["group:fs", "sessions_list"] }
    }
  }
}

工具组（快捷方式）

无需逐个列举工具，可使用工具组：

  • 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:moltbot → 所有内置工具（不含插件工具）

示例：

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

插件工具

插件可在内置工具集之外添加自己的工具。安装见 Plugins，工具说明如何注入提示见 Skills。

值得关注的插件工具：

  • Lobster：带类型化流水线与审批门控的工作流运行时
  • LLM Task：运行结构化仅 JSON 的 LLM 任务（适合工作流步骤）

若白名单仅引用未加载的插件工具名，Moltbot 会记录警告并保留核心工具可用（避免意外锁死）。

工具参考

exec

在工作区运行 shell 命令，支持前台与后台执行。

关键参数：

  • command（必填）
  • yieldMs（此延迟后自动后台，默认 10 秒）
  • background（立即后台启动）
  • timeout（运行超时则终止，默认 30 分钟）
  • host（sandbox | gateway | node）——执行位置
  • security（deny | allowlist | full）——强制模式
  • ask（off | on-miss | always）——审批提示
  • elevated（在允许时以 full security 在网关主机上运行）
  • pty（在伪终端中运行，用于交互式 CLI）

使用 process 工具轮询、发送输入或终止后台会话。

沙箱环境下，exec 默认在 Docker 中运行。设置 host=gateway 或 elevated=true 可在主机上运行（需审批门控，除非显式允许）。

完整说明见 Exec 工具 与 Exec 审批。

browser

控制专用 Chrome/Brave 配置（与个人浏览器隔离）。

常用操作：

  • status、start、stop——管理浏览器进程
  • tabs、open、focus、close——标签控制
  • snapshot——获取页面文本表示（AI 或 ARIA 格式）
  • screenshot——捕获像素（整页或特定元素）
  • act——点击、输入、悬停、拖拽、选择、填表
  • navigate、console、pdf、upload、dialog——高级操作

多配置支持： 使用 profile 指定命名浏览器配置（如 clawd、work、chrome）。配置可指向本地托管浏览器或远程 CDP 端点。

目标选择：

  • target=sandbox——Docker 中的浏览器（需启用沙箱）
  • target=host——网关机器上的浏览器
  • target=node——已配对的 macOS/Linux 节点上的浏览器

快照返回 ref ID（数字如 12 或基于角色如 e12），用于 act 点击或输入。无脆弱的 CSS 选择器。

设置、配置与 Chrome 扩展中继见 Browser 工具。

使用 Brave Search API（默认）或 Perplexity Sonar 搜索网页。

参数：

  • query（必填）
  • count（1–10 个结果）
  • country、search_lang、ui_lang、freshness（可选过滤器）

设置： 从 brave.com/search/api  获取 Brave API key，然后运行 moltbot configure --section web 或设置 BRAVE_API_KEY。

结果默认缓存 15 分钟。

Perplexity 设置与配置见 Web 工具。

web_fetch

抓取 URL 并提取可读内容（HTML → markdown 或纯文本）。

参数：

  • url（必填）
  • extractMode（markdown | text）
  • maxChars（截断长页）

默认使用 Readability 提取，可选 Firecrawl 回退处理重度 JS 或有反爬保护的站点。

详见 Web 工具 与 Firecrawl。

process

管理后台 exec 会话。

操作：

  • list——显示活跃/最近会话
  • poll——检查新输出（完成时返回退出码）
  • log——用 offset/limit 按行读取输出
  • write、send-keys、submit、paste——发送输入
  • kill、clear、remove——停止或清理会话

后台会话按代理划分。一个代理看不到另一个代理的会话。

apply_patch

在一次调用中应用结构化多文件编辑。当普通 edit 工具过于脆弱时有用。

格式：

*** Begin Patch
*** Add File: path/to/new.txt
+行内容
*** Update File: src/app.ts
@@
-旧行
+新行
*** Delete File: obsolete.txt
*** End Patch

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

详见 Apply Patch。

sessions_list / sessions_history / sessions_send / sessions_spawn

跨对话处理代理会话。

sessions_list：列出活跃会话，可选消息预览
sessions_history：读取会话转录（按键或 ID）
sessions_send：向另一会话发送消息，可选等待回复
sessions_spawn：在后台启动子代理运行（完成后通知回传）
session_status：显示当前会话信息或覆盖模型

适用于多代理设置、委托或检查其他对话中发生的情况。

详见 Session 工具 与 Subagents 子代理。

agents_list

列出当前会话可通过 sessions_spawn 指定的代理 ID。遵循每代理白名单（agents.list[].subagents.allowAgents）。

message

跨 Discord、Telegram、Slack、WhatsApp、Google Chat、Signal、iMessage 与 MS Teams 发送消息并执行频道特定操作（反应、编辑、投票、线程等）。

常用操作：

  • send——文本 + 可选媒体（图像、文件、位置）
  • react、edit、delete、pin
  • poll——创建投票（WhatsApp、Discord、MS Teams）
  • thread-create、thread-reply——线程管理
  • search、permissions、member-info、role-info
  • 管理：timeout、kick、ban

频道特定功能如 Adaptive Cards（Teams）、贴纸（Telegram）、表情上传均通过同一工具。

cron

管理网关上的定时任务。

操作：

  • list、status——查看任务与最近运行
  • add、update、remove——增删改
  • run——立即触发任务
  • wake——入队系统事件（可选带立即心跳）

任务使用标准 cron 语法，可运行 shell 命令或触发代理消息。

详见 Cron CLI。

gateway

重启网关或在不停机的情况下应用配置更新。

操作：

  • restart——发送 SIGUSR1 进行进程内重启
  • config.get、config.schema——查看当前配置
  • config.apply、config.patch——校验并写入配置，然后重启
  • update.run——应用更新并重启

适用于自行管理基础设施的代理。

重启需在配置中设置 commands.restart: true。

nodes

发现与控制已配对的 macOS/iOS 设备。

操作：

  • status、describe——查看已连接内容与可用能力
  • pending、approve、reject——管理配对请求
  • notify——发送 macOS 通知
  • run——在节点上执行命令（需审批门控）
  • camera_snap、camera_clip、screen_record——捕获媒体
  • location_get——GPS 坐标（需 iOS/macOS 位置权限）

图像作为媒体块返回，视频返回文件路径。摄像头/录屏需将节点应用前置。

详见 Nodes CLI。

canvas

驱动 macOS 节点上的可视画布。

操作：

  • present、hide、navigate——显示/隐藏/控制画布窗口
  • eval——在画布上下文中运行 JavaScript
  • snapshot——捕获截图
  • a2ui_push、a2ui_reset——A2UI 渲染（v0.8 格式）

底层使用 node.invoke。仅连接一个节点时自动选择。

image

用配置的视觉模型分析图像。

参数：

  • image（路径或 URL）
  • prompt（可选，默认”Describe the image.”）
  • model（可选覆盖）
  • maxBytesMb（大小上限）

仅当配置了 agents.defaults.imageModel 或 Moltbot 能从主模型与认证配置推断出图像模型时可用。

常见模式

浏览器自动化：

  1. browser status / browser start
  2. browser snapshot 获取页面结构
  3. 用快照中的 ref 执行 browser act 点击/输入
  4. browser screenshot 进行视觉确认

Shell 任务：

  1. 用命令执行 exec
  2. 若后台运行，用 process 轮询直到完成
  3. 用 process log 读取输出

多代理委托：

  1. sessions_spawn 启动子代理任务
  2. 在后台运行，完成后通知回传
  3. 用 sessions_history 查看发生了什么

节点捕获：

  1. nodes status 查看已连接内容
  2. nodes camera_snap 或 nodes screen_record
  3. 结果作为媒体块或文件路径返回

安全说明

  • exec 与 nodes run 权限大。在真实主机上运行时应使用审批门控（ask: "on-miss" 或 "always"）与白名单。
  • 摄像头/录屏需要同意。始终先用 nodes describe 检查权限。
  • Elevated 模式（elevated: true 或 host: "gateway" 配合 security: "full"）会绕过部分安全检查——仅为可信代理保留。
  • 浏览器隔离：clawd 浏览器配置与你的个人浏览器分离，但仍可访问已登录会话，请谨慎对待。

完整说明见 安全 与 沙箱。

工具工作原理

代理运行时，Moltbot 以两种方式暴露工具：

  1. 系统提示：人类可读的描述，让模型知道可用内容
  2. 工具模式：发送给模型 API 的类型化函数定义（OpenAI function calling、Anthropic tools 等）

若工具不在这两处，模型就看不到。这就是为何 allow/deny 列表在提示构建之前生效——被拒绝的工具永远不会到达模型。

推荐阅读

最后更新于:
Web 工具