OpenClaw 工具权限精细化管理

2026-01-15 · 7 分钟安全运维

工具权限概述

OpenClaw 中的工具（Tools）赋予 AI 与外部系统交互的能力，包括文件读写、命令执行、网页浏览等。权限管理的核心原则是：最小权限原则，只开放 AI 实际需要的工具。

允许与拒绝列表

工具权限通过 allow 和 deny 列表控制，deny 优先级高于 allow：

{
  tools: {
    // 允许使用的工具
    allow: [
      "fs_read",
      "fs_write",
      "search",
      "web_fetch"
    ],

    // 禁止使用的工具（优先级高于 allow）
    deny: [
      "exec",
      "browser"
    ]
  }
}

当 allow 和 deny 同时包含某个工具时，deny 生效。

工具组（Group）

为了方便管理，OpenClaw 将工具按功能分组，使用 group: 前缀引用：

{
  tools: {
    allow: [
      "group:fs",        // 文件系统工具组
      "group:web"        // 网络工具组
    ],
    deny: [
      "group:runtime"    // 运行时工具组
    ]
  }
}

内置工具组

工具组	包含工具	说明
`group:fs`	fs_read, fs_write, fs_list, fs_search	文件系统操作
`group:runtime`	exec, shell, process	命令执行和进程管理
`group:sessions`	session_create, session_switch, session_list	会话管理
`group:web`	web_fetch, web_search	网络请求和搜索
`group:ui`	browser, screenshot, clipboard	用户界面交互

提权工具（Elevated Tools）

某些工具需要更高权限才能执行，可以配置按频道白名单控制：

{
  tools: {
    elevated: {
      // 需要提权的工具列表
      tools: ["exec", "fs_write", "browser"],

      // 按频道设置提权白名单
      channelWhitelist: {
        whatsapp: [
          "+8613800138000"   // 仅该号码可使用提权工具
        ],
        discord: [
          "user_123456789"   // 仅该用户可使用提权工具
        ]
      }
    }
  }
}

非白名单用户调用提权工具时，AI 会回复权限不足的提示。

配置模板

OpenClaw 预设了几种常用的工具权限配置模板：

最小化配置（minimal）

{
  tools: {
    // 仅允许只读操作
    allow: [
      "fs_read",
      "fs_list",
      "search"
    ],
    deny: ["*"]  // 拒绝其余所有
  }
}

编码助手配置（coding）

{
  tools: {
    allow: [
      "group:fs",       // 文件读写
      "exec",           // 命令执行
      "web_fetch",      // 抓取文档
      "search"          // 代码搜索
    ],
    deny: [
      "browser",        // 不需要浏览器
      "group:sessions"  // 不需要会话管理
    ]
  }
}

消息助手配置（messaging）

{
  tools: {
    allow: [
      "fs_read",        // 读取知识库
      "search",         // 搜索
      "web_fetch",      // 查询网页
      "calendar"        // 日历管理
    ],
    deny: [
      "group:runtime",  // 禁止命令执行
      "group:ui",       // 禁止 UI 操作
      "fs_write"        // 禁止写文件
    ]
  }
}

完整配置（full）

{
  tools: {
    allow: ["*"],       // 允许所有工具
    deny: []            // 无限制
  }
}

警告：完整配置仅适合受信任的内部使用场景，面向公众时切勿使用。

按 Agent 配置工具

不同的 Agent 可以有不同的工具权限：

{
  agents: {
    "code-reviewer": {
      tools: {
        allow: ["fs_read", "fs_list", "search"],
        deny: ["fs_write", "exec"]
      }
    },
    "devops": {
      tools: {
        allow: ["group:fs", "group:runtime", "web_fetch"],
        deny: []
      }
    },
    "customer-service": {
      tools: {
        allow: ["search", "calendar"],
        deny: ["group:fs", "group:runtime", "group:ui"]
      }
    }
  }
}

浏览器控制安全考虑

浏览器工具的权限等级相当于 operator 级别，能够操作网页、填写表单、甚至执行 JavaScript。启用时必须慎重：

{
  tools: {
    browser: {
      // 是否启用
      enabled: false,

      // 如需启用，严格限制
      allowedDomains: [
        "docs.example.com",
        "wiki.internal.com"
      ],

      // 禁止执行 JavaScript
      javascript: false,

      // 禁止表单提交
      formSubmit: false
    }
  }
}

查看可用工具

# 列出所有工具及其权限状态
openclaw tools list

# 查看特定工具的详细信息
openclaw tools info exec

# 检查当前生效的权限配置
openclaw tools permissions

常见问题排查

工具被拒绝但已在 allow 中：检查 deny 列表或所属的 group 是否被 deny
提权工具无法使用：确认用户 ID 在 channelWhitelist 中，注意 ID 格式
工具不存在：运行 openclaw tools list 查看完整工具名称
权限变更未生效：发送 SIGUSR1 信号热重载，或重启网关