为什么需要权限管理？
想象一下，你的Agent能够删除文件、发送邮件、访问数据库——听起来很强大，但如果它被恶意prompt注入了呢？一个被操控的Agent可能执行rm -rf /或者泄露所有用户数据。这就是权限管理存在的意义：在能力与安全之间划一条红线。
🚨 安全案例：2024年，某AI客服Agent因缺乏权限控制，被prompt注入攻击者诱导执行了系统命令，导致整个生产服务器被清空。教训：永远不要信任LLM的输出。
OpenClaw权限模型
三层权限架构
权限层级
├── Agent级别 (全局限制)
│ ├── 禁止的工具列表
│ ├── 允许的工具列表
│ └── 敏感操作阈值
├── 工具级别 (能力声明)
│ ├── 需要的权限
│ ├── 访问的资源类型
│ └── 危险等级
└── 操作级别 (单次审批)
├── 具体操作参数
├── 用户确认
└── 操作审计权限类型表
| 权限类型 | 说明 | 示例工具 |
|---|---|---|
| file.read | 读取文件 | 文档查看、数据分析 |
| file.write | 写入/创建文件 | 文档编辑、代码生成 |
| file.delete | 删除文件 | 清理临时文件 |
| network.request | 发起网络请求 | API调用、网页抓取 |
| shell.execute | 执行系统命令 | 脚本执行、编译 |
| email.send | 发送邮件 | 通知发送 |
| database.access | 数据库操作 | 查询、插入、更新 |
配置工具权限
声明式权限配置
import { Agent, ToolPermission } from 'openclaw';
const agent = new Agent({
permissions: {
// 白名单模式：只允许这些权限
mode: 'whitelist',
allowed: [
'file.read',
'network.request'
],
// 黑名单模式：禁止这些权限（慎用）
denied: [
'file.delete',
'shell.execute'
],
// 需要审批的权限
requiresApproval: [
'email.send',
'database.write'
]
}
});工具级别权限声明
const emailTool = {
name: 'send_email',
description: '发送邮件给指定收件人',
permissions: {
required: ['email.send'],
riskLevel: 'high',
auditRequired: true,
// 参数级别的权限控制
parameterConstraints: {
to: {
// 只能发送给白名单邮箱
pattern: /^[\w.-]+@(company\.com|partner\.org)$/
},
subject: {
maxLength: 100
}
}
},
handler: async (params) => {
// 执行发送逻辑
}
};
agent.registerTool(emailTool);审批流程
人机审批机制
对于高风险操作，OpenClaw支持用户审批流程：
agent.setApprovalHandler({
// 自动审批规则
autoApprove: (toolCall) => {
// 低风险操作自动通过
if (toolCall.riskLevel === 'low') return true;
// 已批准过的类似操作
if (toolCall.isRepeatOfApproved) return true;
return false;
},
// 需要人工审批时的处理
requestApproval: async (toolCall) => {
// 发送审批请求到用户
const approval = await sendApprovalRequest({
tool: toolCall.name,
params: toolCall.arguments,
reason: toolCall.reason,
timeout: 30000 // 30秒内必须响应
});
return approval.accepted;
},
// 审批超时处理
onTimeout: (toolCall) => {
return 'reject'; // 或 'auto_approve' 根据业务需求
}
});审批界面示例
💡 用户视角：当Agent尝试执行敏感操作时，用户会收到类似这样的审批请求：
Agent请求执行以下操作：
工具: send_email
参数: {
to: "admin@company.com",
subject: "系统报警通知",
body: "CPU使用率超过90%"
}
[允许] [拒绝] [总是允许此类操作]安全沙箱
隔离执行环境
OpenClaw支持在沙箱环境中执行工具，防止意外或恶意操作影响主系统：
agent.setSandbox({
enabled: true,
type: 'docker', // 或 'process', 'vm'
// 沙箱配置
config: {
// 文件系统隔离
filesystem: {
readOnly: ['/etc', '/usr'],
writeOnly: ['/tmp/agent-work']
},
// 网络隔离
network: {
allowDomains: ['api.example.com'],
denyDomains: ['*']
},
// 进程隔离
process: {
maxProcesses: 5,
maxMemory: '256MB',
timeout: 30000
}
}
});最小权限原则
⚠️ 金科玉律：只授予完成任务所需的最小权限。不要因为"可能需要"就授予全部权限。
权限最小化实践
// 错误：授予过多权限
agent.setPermissions(['file.*', 'shell.*']); // ❌
// 正确：只授予需要的权限
agent.setPermissions(['file.read', 'file.write']); // ✅
// 更好：限定具体路径
agent.setPermissions([
{ type: 'file.read', paths: ['/data/input'] },
{ type: 'file.write', paths: ['/data/output'] }
]);审计与追溯
操作日志
agent.enableAudit({
logAll: true,
includeSensitive: false, // 不记录敏感参数值
// 日志存储
storage: {
type: 'file',
path: '/var/log/agent-audit.log',
retention: 30 // 保留30天
},
// 审计事件
events: [
'tool_call',
'tool_result',
'approval_request',
'approval_response',
'permission_denied'
]
});审计报告
// 生成审计报告
const report = await agent.generateAuditReport({
period: 'last_7_days',
filters: {
user: 'user123',
tool: 'send_email'
}
});
console.log(report.summary);
// {
// totalCalls: 156,
// approved: 152,
// rejected: 4,
// autoApproved: 140,
// manualApproved: 12
// }最佳实践
- ✅ 使用白名单而非黑名单
- ✅ 为所有工具声明所需权限
- ✅ 高风险操作必须审批
- ✅ 启用沙箱隔离执行环境
- ✅ 记录所有操作审计日志
- ✅ 定期审查权限配置
- ✅ 敏感数据不在日志中记录
- ✅ 用户可随时撤销权限
常见问题
Q: 白名单和黑名单哪个更好？
白名单更安全。黑名单模式可能漏掉新添加的危险权限，而白名单默认拒绝所有未显式允许的操作。
Q: 如何处理权限不足的情况？
Agent会收到权限不足的反馈，可以尝试替代方案或请求用户授权。不要让Agent失败，而是引导它找到安全路径。
Q: 沙箱会降低性能吗？
会有轻微影响（约5-10%），但安全收益远大于性能损失。对于高频调用场景，可以考虑进程隔离而非Docker。