OpenClaw 提供了细粒度的工具权限控制体系，让你精确管理 AI Agent 能使用哪些工具——从全局默认到 per-Agent、per-Provider 的精细覆盖。
工具组（Tool Groups）
OpenClaw 将相关工具打包成组，方便批量配置：
| 组名 | 包含工具 |
|---|---|
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 | 所有内置 OpenClaw 工��（不含插件） |
工具配置文件（Tool Profiles）
用于快速设置工具白名单基础：
| Profile | 说明 |
|---|---|
minimal | 只有 session_status |
coding | 文件系统 + 运行时 + 会话 + 记忆 + 图像 |
messaging | 消息发送 + 会话管理 |
full | 无限制（默认） |
json
{
"tools": {
"profile": "messaging",
"allow": ["slack", "discord"]
}
}json
{
"tools": {
"profile": "coding",
"deny": ["group:runtime"]
}
}全局 Allow/Deny 策略
json
{
"tools": {
"allow": ["group:fs", "browser"],
"deny": ["exec"]
}
}注意：deny 优先于 allow，匹配大小写不敏感，支持 * 通配符（"*" 代表所有工具）。
per-Agent 工具覆盖
json
{
"tools": { "profile": "coding" },
"agents": {
"list": [
{
"id": "support",
"tools": {
"profile": "messaging",
"allow": ["slack"]
}
}
]
}
}全局使用 coding profile，support Agent 只使用 messaging profile + Slack 工具。
per-Provider 工具限制
针对特定模型提供商进一步限制工具：
json
{
"tools": {
"profile": "coding",
"byProvider": {
"google-antigravity": { "profile": "minimal" },
"openai/gpt-5.2": { "allow": ["group:fs", "sessions_list"] }
}
}
}byProvider 只能收窄工具集（在全局策略基础上进一步限制），不能扩展。
核心工具详解
exec（运行 Shell 命令）
json
{
"command": "npm test",
"yieldMs": 10000,
"background": false,
"timeout": 1800,
"elevated": false,
"host": "sandbox",
"security": "allowlist",
"pty": false
}yieldMs：超时后自动后台化（默认 10 秒）elevated：在主机运行（绕过沙箱，受tools.elevated控制）host：sandbox | gateway | nodesecurity：deny | allowlist | fullpty: true：需要 TTY 的命令（如交互式 CLI）
process（管理后台任务）
支持操作：list, poll, log, write, kill, clear, remove
poll：获取新输出和退出状态log：支持offset/limit按行读取（省略 offset 获取最后 N 行）- 会话按 Agent 隔离：其他 Agent 的后台任务不可见
web_search（网页搜索）
需要 Brave API Key：
bash
openclaw configure --section web # 或设置 BRAVE_API_KEY 环境变量json
{
"tools": {
"web": {
"search": {
"enabled": true,
"maxResults": 5
}
}
}
}web_fetch（抓取网页内容）
json
{
"url": "https://example.com",
"extractMode": "markdown",
"maxChars": 50000
}extractMode 可选：markdown（默认）或 text。
工具循环检测（Loop Detection）
防止 Agent 陷入重复调用循环：
json
{
"tools": {
"loopDetection": {
"enabled": true,
"warningThreshold": 10,
"criticalThreshold": 20,
"globalCircuitBreakerThreshold": 30,
"historySize": 30,
"detectors": {
"genericRepeat": true,
"knownPollNoProgress": true,
"pingPong": true
}
}
}
}三种检测器：
genericRepeat：重复相同工具 + 相同参数knownPollNoProgress：重复 poll 类工具且输出相同pingPong：A/B/A/B 交替但无进展
apply_patch（多文件结构化补丁）
json
{
"tools": {
"exec": {
"applyPatch": {
"enabled": true,
"workspaceOnly": true
}
}
}
}workspaceOnly: true 限制补丁只能修改工作区目录内的文件（默认），设为 false 才允许修改工作区外文件。目前仅 OpenAI 模型支持。
原文：Tools - OpenClaw | 来源：OpenClaw 官方文档