第四章：工具与功能

约 2465 字大约 8 分钟

本章介绍 OpenClaw 智能体可以使用的所有内置工具、节点系统、AI 模型提供商，以及 CLI 命令行参考。

4.1 工具系统概览

OpenClaw 为智能体提供了一套完整的一等公民工具（First-class Agent Tools），包括：文件操作、命令执行、浏览器控制、节点管理、定时任务等。

全局工具配置

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

deny 优先于 allow：被禁止的工具不会发送给模型提供商
支持大小写不敏感匹配
支持 "*" 通配符（表示所有工具）

4.2 工具配置档案（Profiles）

使用 tools.profile 设置基础工具集：

档案	包含工具
`minimal`	仅 `session_status`
`coding`	文件系统、运行时、会话、内存、图像
`messaging`	消息发送、会话查看
`full`（默认）	无限制，所有工具

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

4.3 工具分组（Tool Groups）

分组	包含工具
`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`	所有内置工具（不含插件工具）

4.4 核心工具详解

`exec` — 执行 Shell 命令

在工作区执行 Shell 命令，是最强大的工具之一。

主要参数：

参数	说明
`command`	要执行的命令（必填）
`yieldMs`	超时后自动转为后台执行（默认 10000ms）
`background`	立即在后台执行
`timeout`	最大执行时间（秒），超时后终止进程（默认 1800）
`elevated`	在宿主机以完整权限运行（沙箱模式下有效）
`host`	`sandbox`、`gateway` 或 `node`
`security`	`deny`、`allowlist` 或 `full`
`pty`	需要真实 TTY 时设为 `true`

使用示例：

在工作区运行 git 命令：git status
在后台执行长时间任务，完成后通知我

`process` — 管理后台进程

管理 exec 创建的后台会话：

动作	说明
`list`	列出所有后台会话
`poll`	获取新输出和退出状态
`log`	按行读取日志（支持 `offset`/`limit`）
`write`	向进程写入输入
`kill`	终止进程
`clear` / `remove`	清除会话记录

`read` / `write` / `edit` — 文件操作

read：读取文件内容
write：写入文件（覆盖）
edit：精确替换文件中的内容
apply_patch：跨文件应用结构化补丁（多块编辑）

`web_search` — 网页搜索

使用 Brave Search API 搜索网络：

{
  "tools": {
    "web": {
      "search": {
        "enabled": true,
        "maxResults": 5
      }
    }
  }
}

需要 Brave API Key：openclaw configure --section web 或设置 BRAVE_API_KEY

`web_fetch` — 网页内容提取

从 URL 抓取并提取可读内容（HTML → Markdown/文本）：

{
  "tools": {
    "web": {
      "fetch": {
        "enabled": true,
        "maxCharsCap": 50000
      }
    }
  }
}

对于 JavaScript 渲染的网页，优先使用 browser 工具

`browser` — 浏览器控制

控制专用浏览器实例，实现完整的网页自动化：

主要动作：

动作	说明
`status` / `start` / `stop`	浏览器生命周期管理
`open`	打开 URL
`snapshot`	截取页面快照（AI 模式或 ARIA 可访问性树）
`screenshot`	截图（返回图片 + `MEDIA:<path>`）
`act`	UI 操作：点击/输入/按键/悬停/拖拽/滚动
`navigate`	导航到 URL
`pdf`	导出为 PDF
`upload`	上传文件
`console`	读取控制台日志

多配置文件支持：

{
  "browser": {
    "enabled": true,
    "defaultProfile": "chrome"
  }
}

使用示例：

打开 GitHub 并截图我的 PR 列表
在亚马逊上搜索某商品并获取价格
自动填写并提交某表单

`canvas` — 节点 Canvas 控制

控制连接节点（iOS/Android/macOS）上的 Canvas 界面：

动作	说明
`present`	在节点上显示内容
`hide`	隐藏 Canvas
`navigate`	导航到 URL
`eval`	执行 JavaScript
`snapshot`	截图
`a2ui_push`	推送 A2UI 内容

`nodes` — 节点管理

发现和操作已配对的节点设备：

动作	说明
`status` / `describe`	查看节点状态
`notify`	发送系统通知（macOS）
`run`	在节点上执行命令
`camera_snap`	拍照
`camera_clip`	录制视频片段
`screen_record`	屏幕录制
`location_get`	获取地理位置

`message` — 跨渠道消息发送

向 Discord、Telegram、WhatsApp、Slack 等发送消息：

动作	说明
`send`	发送文本/媒体消息
`react`	添加表情反应
`edit` / `delete`	编辑/删除消息
`thread-create`	创建讨论线程
`search`	搜索消息历史
`role-add` / `role-remove`	管理 Discord 角色

`cron` — 定时任务管理

管理 Gateway 的 Cron 定时任务：

每天早上8点检查我的邮件并总结
每周一生成工作计划报告

动作	说明
`add`	添加定时任务
`update`	更新任务
`remove`	删除任务
`run`	立即运行一次
`status` / `list`	查看任务状态

`gateway` — 网关控制

重启或更新运行中的 Gateway：

动作	说明
`restart`	原地重启 Gateway
`config.get`	读取配置
`config.patch`	合并部分配置更新
`config.apply`	验证并应用配置
`update.run`	更新 + 重启

`sessions_*` — 会话管理

工具	说明
`sessions_list`	列出所有会话
`sessions_history`	查看会话历史记录
`sessions_send`	向另一个会话发送消息
`sessions_spawn`	创建子智能体任务
`session_status`	查看当前会话状态

`image` — 图像分析

使用配置的图像模型分析图片：

{
  "agent": {
    "imageModel": "anthropic/claude-opus-4-6"
  }
}

4.5 循环检测（防卡死）

当智能体陷入重复调用循环时，自动阻断：

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

检测器	触发条件
`genericRepeat`	重复调用相同工具+相同参数
`knownPollNoProgress`	轮询类工具输出无变化
`pingPong`	A→B→A→B 交替无进展模式

4.6 节点系统（Nodes）

节点是连接到 Gateway 的伴侣设备，扩展了智能体的物理能力。

节点类型

节点类型	能力
macOS 节点	Canvas、摄像头、屏幕录制、系统命令
iOS 节点	Canvas、摄像头、位置
Android 节点	Canvas、摄像头、位置
Headless 节点	远程命令执行（无 UI）

配置远程节点

# 在远程机器上运行节点
openclaw node run --host <gateway地址> --port 18789 --display-name "远程节点"

# 安装为系统服务（开机自启）
openclaw node install --host <gateway地址> --port 18789

节点 CLI 命令

# 查看节点状态
openclaw nodes status
openclaw nodes describe --node <节点ID或名称>

# 审批待配对节点
openclaw nodes pending
openclaw nodes approve <requestId>

# 重命名节点
openclaw nodes rename --node <id> --name "办公室 Mac"

# 摄像头操作
openclaw nodes camera snap --node <节点>            # 拍照
openclaw nodes camera clip --node <节点> --duration 10s  # 录视频

# 屏幕录制
openclaw nodes screen record --node <节点> --duration 10s --fps 10

# 获取位置
openclaw nodes location get --node <节点>

# Canvas 操作
openclaw nodes canvas snapshot --node <节点> --format png
openclaw nodes canvas present --node <节点> --target https://example.com
openclaw nodes canvas eval --node <节点> --js "document.title"

# 发送系统通知
openclaw nodes notify --node <节点> --title "提醒" --body "任务完成"

# 执行命令
openclaw nodes run --node <节点> -- echo "Hello"

节点执行命令配置

# 设置默认命令执行目标为节点
openclaw config set tools.exec.host node
openclaw config set tools.exec.security allowlist
openclaw config set tools.exec.node "节点ID或名称"

4.7 AI 模型提供商

OpenClaw 支持多种 LLM 提供商，通过统一的 provider/model 格式配置。

支持的提供商

提供商	示例模型
Anthropic	`anthropic/claude-opus-4-6`
OpenAI	`openai/gpt-4o`
Google	`google/gemini-2.0-flash`
Venice AI	`venice/llama-3.3-70b`（隐私优先，推荐）
Qwen	`qwen/qwen-max`
OpenRouter	`openrouter/...`
Mistral	`mistral/mistral-large`
Moonshot（Kimi）	`moonshot/kimi-k1-pro`
LiteLLM	统一网关代理多个提供商
Cloudflare AI	Workers AI 推理
Together AI	`together/...`

配置默认模型

{
  "agent": {
    "model": "anthropic/claude-opus-4-6"
  }
}

认证

# 通过向导一键认证
openclaw onboard

# 或者手动配置
openclaw configure --section providers

按提供商限制工具

{
  "tools": {
    "profile": "coding",
    "byProvider": {
      "google-antigravity": {"profile": "minimal"},
      "openai/gpt-5.2": {"allow": ["group:fs", "sessions_list"]}
    }
  }
}

4.8 插件与技能（Skills）

插件（Plugins）

插件可以注册额外的工具和 CLI 命令：

# 安装插件
openclaw plugins install <插件名>

# 查看已安装插件
openclaw plugins list

可用插件工具：

Lobster：可恢复审批的类型化工作流运行时
LLM Task：结构化 JSON 输出的 LLM 步骤

技能（Skills）

技能是向智能体注入工具使用指南的机制，存储在工作区的 skills/ 目录：

~/.openclaw/workspace/
└── skills/
    ├── gmail.md          # Gmail 技能
    ├── github.md         # GitHub 技能
    └── calendar.md       # 日历技能

~/.openclaw/skills/       # 共享技能（所有智能体可用）

# 技能管理
openclaw skills list
openclaw skills install <技能名>

4.9 CLI 命令行参考

全局标志

标志	说明
`--dev`	使用隔离的开发环境（`~/.openclaw-dev`）
`--profile <名称>`	使用命名配置文件（`~/.openclaw-<名称>`）
`--no-color`	禁用 ANSI 颜色输出
`--json`	JSON 格式输出
`-V` / `--version`	显示版本号

命令速查表

openclaw
├── setup            初始化工作区
├── onboard          引导式全功能配置向导
├── configure        分模块配置
├── config           读写配置
│   ├── get          读取配置项
│   ├── set          写入配置项
│   └── unset        删除配置项
├── doctor           诊断并修复配置问题
├── dashboard        打开 Web 控制台
├── update           更新 OpenClaw
├── status           查看运行状态
├── health           健康检查
├── logs             查看日志
├── gateway          网关管理
│   ├── install      安装为系统服务
│   ├── start/stop   启动/停止
│   └── status       服务状态
├── channels         渠道管理
│   ├── login        渠道登录（扫码等）
│   └── status       渠道状态
├── agents           智能体管理
│   ├── add          添加新智能体
│   └── list         列出所有智能体
├── sessions         会话管理
├── nodes            节点管理
│   ├── status       节点状态
│   ├── approve      审批节点
│   ├── camera       摄像头操作
│   ├── canvas       Canvas 操作
│   └── notify       发送通知
├── node             节点主机
│   ├── run          运行节点
│   └── install      安装节点服务
├── devices          设备配对管理
├── cron             定时任务管理
├── memory           记忆管理
├── skills           技能管理
├── plugins          插件管理
├── pairing          配对管理
├── approvals        执行审批管理
├── sandbox          沙箱管理
├── browser          浏览器管理
├── models           模型列表
├── security         安全审计
└���─ secrets          密钥管理

常用命令示例

# 状态检查
openclaw status
openclaw status --all      # 完整诊断
openclaw status --deep     # 包含 Gateway 健康探测
openclaw health --json     # JSON 格式健康快照

# 配置管理
openclaw config get agent.model
openclaw config set agent.model "anthropic/claude-opus-4-6"
openclaw config unset agent.heartbeat.every

# 日志查看
openclaw logs --follow          # 实时跟踪日志
openclaw logs --tail 100        # 最后100行

# 模型列表
openclaw models list

# 内存管理
openclaw memory search "项目"
openclaw memory get <key>

# 安全审计
openclaw security audit

# 密钥管理
openclaw secrets reload

4.10 下一步

第五章：网关配置 — 深入网关运维和安全配置
第六章：参考与附录 — 积分说明、故障排查等