一、核心概念
1. 什么是工具（Tools）
工具是智能体和外部系统交互的原子能力。纯大模型仅能生成文本，搭配工具后可执行命令、读写文件、访问网页、运行代码等，从单纯聊天机器人变为可落地的自动化助手。
2. 工具 / 技能 / 插件 三层架构（核心区分）
三者层级从上到下，职责、生效规则完全不同：
- 插件（Plugin）：系统底层扩展，新增渠道、模型、语音等底层能力，修改后必须重启网关。
- 技能（Skill）：业务流程封装（
SKILL.md），基于工具组合成完整任务，热加载无需重启。 - 工具（Tool）：最小原子操作（读文件、执行命令、浏览器操作等），系统内置、开箱即用。
二、内置工具总览
表格
| 工具名 | 功能 | 典型场景 |
|---|---|---|
exec | 执行 Shell 终端命令 | 运维、项目部署、文件查询 |
read | 读取本地文件 | 查看配置、代码、日志 |
write | 写入 / 创建 / 修改本地文件 | 写代码、生成配置、保存文本 |
web_search | 全网搜索 | 查资料、查实时资讯 |
browser | 操控 Chromium 浏览器 | 爬取网页、自动填表、页面截图 |
code_execution | 沙箱运行 Python 代码 | 数据分析、数学计算、绘图 |
image | 图像处理、识图、生图 | 图片解析、简单修图 |
message | 主动向用户发消息 | 流程提醒、结果推送 |
memory_search/memory_get | 长期记忆检索与读取 | 上下文回溯、历史记录查询 |
process | 进程管理 | 查看、启停后台进程 |
cron | 定时任务管理 | 周期性自动任务 |
gateway | 网关状态管理 | 查看运行状态、简单运维 |
三、工具权限管控（重点，生产环境必配）
配置文件：~/.openclaw/openclaw.json
支持 权限预设、黑白名单、工具分组 三种管理方式。
1. 权限预设 Profile（一键场景配置）
预设模板，快速匹配使用场景，优先级高于默认规则。
表格
| 预设值 | 包含工具 | 适用场景 |
|---|---|---|
full | 全部工具 | 本地可信环境、全功能调试 |
coding | read / write / exec / browser / web_search | 编程、开发、项目管理 |
messaging | message /web_search/memory 系列 | 纯聊天、客服、问答机器人 |
minimal | read / web_search | 最小权限，只读 + 搜索，安全优先 |
配置示例：
json
{
"tools": {
"profile": "coding"
}
}
2. 黑白名单 allow /deny
（1）白名单 allow
仅允许列表内工具，其余全部禁用（推荐安全方案）
json
{
"tools": {
"allow": ["read", "write", "web_search"]
}
}
（2）黑名单 deny
禁用列表内工具，其余全部可用
json
{
"tools": {
"deny": ["exec", "browser"]
}
}
优先级规则
deny>allow：同时配置时，黑名单先生效- 仅
allow：只放行列表工具 - 仅
deny：禁用列表工具，其余全开 - 都不配置：使用默认
profile
3. 工具分组 Group（批量管理）
系统内置分组，不用逐个写工具名，简化配置：
表格
| 分组名 | 包含工具 |
|---|---|
group:fs | read、write（文件操作） |
group:web | browser、web_search（网络相关） |
group:runtime | exec、code_execution、process（命令 / 代码执行） |
group:ui | message、image（交互、图片） |
group:sessions | memory_search、memory_get（记忆 / 会话） |
示例：放行文件 + 网络工具
json
{
"tools": {
"allow": ["group:fs", "group:web"]
}
}
4. 预设 + 黑白名单 组合微调
基于预设模板，再单独禁用个别工具：
json
{
"tools": {
"profile": "coding",
"deny": ["browser"]
}
}
5. 多智能体独立权限
不同 Agent 配置不同工具权限，实现隔离：
json
{
"agents": {
"coder": {
"tools": {
"profile": "coding"
}
},
"chatbot": {
"tools": {
"profile": "messaging"
}
}
}
}
四、核心高级工具详解
1. exec 终端命令执行工具
直接运行宿主机 Shell 命令，运维、开发高频使用。
执行审批（生产环境安全加固）
防止误删、高危命令，支持白名单 / 黑名单两种审批模式。
mode: allow白名单：列表内命令直接执行，其余需要人工确认mode: deny黑名单：列表内命令必须确认，其余直接执行
推荐安全配置（白名单）
json
{
"tools": {
"exec": {
"approvals": {
"mode": "allow",
"commands": [
"ls", "cat", "pwd", "whoami", "date",
"git status", "git log", "git diff"
]
}
}
}
}
列表外命令（rm/mv/chmod 等）执行前会弹窗确认。
2. code_execution 沙箱代码执行
独立沙箱环境运行 Python，与宿主机环境隔离，预装 pandas/numpy/matplotlib 等数据分析库。
- 用途：数值计算、数据处理、报表绘图、算法验证
- 特点：安全隔离，不会影响系统文件 / 进程
- 区别：
exec是宿主机命令，code_execution是沙箱代码
3. browser 浏览器自动化工具
操控 Chromium/Chrome 实现网页自动化：打开链接、点击、输入、截图、提取文本。
1）启用配置
json
{
"tools": {
"allow": ["browser"]
}
}
2）环境依赖
- 桌面端：本地安装 Chrome / Chromium 即可
- Linux 服务器：安装依赖 bash运行
sudo apt install chromium-browser - WSL2：需连接 Windows 端 Chrome 调试端口
3）会话保持（手动登录免重复验证）
手动登录网站并保存 Cookie，后续自动复用登录态：
bash
运行
openclaw browser-login
弹出浏览器，完成登录后关闭窗口，会话自动保存。
4）典型使用场景
网页信息抓取、自动填表、页面截图、Web 功能测试。
五、使用最佳实践 & 安全规范
- 最小权限原则 按需分配权限：聊天机器人用
messaging，开发助手用coding，不要一律开full。 - 生产环境强制开启 exec 审批 服务器环境严禁放任
exec无限制执行，防止误删文件、篡改系统。 - 区分两类代码执行
- 系统运维、终端操作 → 用
exec+ 审批 - 数据计算、算法代码 → 优先用沙箱
code_execution
- 系统运维、终端操作 → 用
- 不信任第三方场景，禁用高危工具 对外公开机器人：直接
deny: ["exec", "browser", "write"]，仅保留读和搜索。 - 分组简化管理 批量管控优先使用
group:分组，配置更简洁、不易出错。
六、常见问题
- 工具无法使用 检查
allow/deny/profile配置，确认工具已放行；修改配置后重启网关生效。 - 执行命令一直等待确认 属于正常审批机制，把常用安全命令加入
exec.approvals.commands白名单即可自动执行。 - 浏览器工具启动失败 系统未安装 Chrome/Chromium，或服务器缺少依赖，执行
sudo apt install chromium-browser补全环境。 - 代码执行报错
code_execution是独立沙箱，宿主机 Python 库不会同步，使用内置预装库即可。
七、快速配置模板（直接复用）
模板 1：本地开发（全功能）
json
{
"tools": {
"profile": "full"
}
}
模板 2：编程助手（推荐）
json
{
"tools": {
"profile": "coding",
"exec": {
"approvals": {
"mode": "allow",
"commands": ["ls", "cat", "pwd", "git status"]
}
}
}
}
模板 3：对外聊天机器人（最小安全权限）
json
{
"tools": {
"profile": "messaging",
"deny": ["exec", "browser", "write"]
}
}