Clawthority：为AI代理构建代码级安全护栏的插件式策略引擎

1. 项目概述为AI代理装上“安全护栏”如果你正在使用或开发AI代理尤其是那些能够调用外部工具比如读写文件、执行命令、发送邮件的智能体那么一个核心的焦虑点一定是我如何确保它不会做出危险操作无论是无意中删除了生产环境的数据库还是未经授权向外部发送了敏感信息这些风险都让AI代理的落地变得如履薄冰。传统的做法是“技能式安全”也就是在给模型的提示词里苦口婆心地叮嘱“请先检查权限”、“请确认操作安全”。但我们都清楚这完全依赖于模型自身的“自觉性”和推理能力一旦模型被诱导、分心或出现幻觉这道防线就形同虚设。Clawthority 正是为了解决这个根本性问题而生的。它不是一个“技能”而是一个插件一个运行在AI代理与外部工具调用路径之间的策略执行引擎。你可以把它想象成一道坚不可摧的“安检门”。当你的AI代理想要执行任何操作时这个请求不会直接抵达工具而是必须先经过Clawthority的审查。Clawthority会根据你预先定义好的策略规则做出“允许”、“拒绝”或“需要人工审批”的决策。最关键的是这个决策过程完全独立于AI模型的推理循环之外由代码强制执行从根本上杜绝了因模型自身问题导致的安全绕过。简单来说Clawthority将安全控制的主动权从不可预测的AI模型手中夺回到了可预测、可审计的代码层面。它为OpenClaw生态提供了一个开箱即用的、语义化的授权运行时让开发者能够清晰地定义“我的代理能做什么”并在边界上强制执行同时为关键操作保留“人在回路”的最终裁决权。2. 核心设计理念从“请求遵守”到“强制拦截”要理解Clawthority的价值我们必须先厘清两种截然不同的安全范式。2.1 技能安全 vs. 插件安全在Clawthority出现之前主流的安全思路是“技能安全”。它的工作模式是这样的你在给AI代理的提示词系统指令或上下文中加入一系列安全规则例如“未经用户明确确认不得删除任何文件”。模型在思考如何完成任务时会“看到”这些规则并理论上遵守它们。技能安全的致命缺陷依赖模型自觉性安全与否完全取决于模型当前的理解和“心情”。一次糟糕的推理或一个精心设计的提示词注入攻击就可能让它忽略所有规则。无强制力模型是决策者也是执行者。它可以选择不遵守规则而系统没有任何代码层面的机制去阻止它。可观测性差你只能看到模型最终决定调用什么工具但无法清晰地追溯它做出这个决定时是否考虑了安全规则以及是如何考虑的。Clawthority代表的“插件安全”则采用了完全不同的架构独立执行层它作为一个独立的代码模块物理上位于AI代理如OpenClaw运行时和所有工具之间。所有工具调用请求必须流经它。代码强制拦截它的决策引擎基于Cedar策略语言根据预定义的策略进行评估。如果策略说“不”那么调用请求在代码层面就会被直接拦截根本不会发送给工具执行。不可绕过因为它运行在模型的“下游”模型本身无法绕过这个检查点。无论模型怎么想、怎么被诱导危险调用都无法触及真实系统。用一个简单的类比技能安全像是在银行柜台贴一张告示“请勿抢劫”依赖劫匪的良知而插件安全则是在柜台前安装了一道防弹玻璃和一道安检门无论劫匪怎么想他都无法直接接触到柜员和现金。2.2 语义化授权与能力系统Clawthority的另一个精妙设计在于其“语义化”特性。传统的基于工具名称字符串匹配或正则表达式的授权规则非常脆弱。工具改个名字、加个别名或者参数格式稍有变化规则就可能失效。Clawthority引入了一个“动作注册表”。所有工具调用在进入策略引擎前会先被“归一化”为一个标准的动作类。例如无论是叫delete_file、rm还是unlink的工具只要其行为是删除文件都会被归类到filesystem.delete这个动作类。你编写的所有安全策略都是针对这些标准的动作类而非具体的工具名称。这使得策略更加健壮和可维护。更进一步Clawthority实现了一个加密能力系统专门用于“人在回路”场景。当高风险操作需要人工审批时系统会生成一个审批令牌。这个令牌并非一个简单的“已批准”标志而是与本次操作的具体内容进行密码学绑定。它包含了动作类、目标资源和请求负载的SHA-256哈希值。这意味着防篡改如果代理在获得批准后试图偷偷修改请求参数例如把收款人从“A”改成“B”哈希值就会对不上令牌立即失效操作会被拒绝。精准授权批准的是“向userexample.com发送内容为X的邮件”而不是笼统的“允许发送邮件”。一次性或会话性令牌可以设计为一次性使用用完即废也可以在一个会话期内对同类操作有效在安全与便利间取得平衡。这套组合拳——代码级强制拦截、语义化策略、加密能力绑定——共同构成了Clawthority坚实的安全基础。3. 安装、配置与快速上手理论讲得再多不如动手一试。Clawthority作为OpenClaw的插件安装和集成过程非常顺畅。3.1 环境准备与插件安装首先确保你的环境满足基本要求Node.js版本 18并且已经安装并配置好了OpenClaw。Clawthority本身是一个TypeScript项目构建后作为插件运行。安装步骤非常简单直接克隆到OpenClaw的插件目录即可# 克隆仓库到OpenClaw的插件目录 git clone https://github.com/OpenAuthority/clawthority ~/.openclaw/plugins/clawthority # 进入插件目录安装依赖并构建 cd ~/.openclaw/plugins/clawthority npm install npm run build构建完成后你会在dist/目录下看到编译后的JavaScript代码。接下来需要在OpenClaw的主配置文件中注册这个插件。编辑~/.openclaw/config.json文件如果不存在则创建添加插件路径{ plugins: [clawthority] }注意这里的clawthority是一个标识符OpenClaw会在其插件目录即你刚才克隆的~/.openclaw/plugins/下寻找同名的目录。确保目录名称一致。3.2 理解两种运行模式开放与封闭Clawthority提供了两种开箱即用的安全基线通过环境变量CLAWTHORITY_MODE控制。理解这两种模式的区别对正确使用至关重要。开放模式这是默认模式。其核心思想是“默认允许关键禁止”。策略所有未被明确禁止的动作类默认都是允许的。安全网同时它内置了一个“关键禁止”列表无条件地拦截最高风险的操作例如shell.exec执行任意命令、payment.initiate发起支付、credential.write写入凭证等。适用场景非常适合快速启动和开发测试。你可以先让代理跑起来大部分文件读取、信息查询等低风险操作不受阻碍同时又被保护在关键危险操作的“安全围栏”内。当你发现代理试图进行危险操作被拦截时再逐步细化你的策略。封闭模式其核心思想是“默认拒绝明确允许”。策略所有动作类除非在策略规则中被明确标记为permit否则一律拒绝。安全网同样包含关键禁止列表但在此模式下这个列表更像是“即使你想允许我也绝不允许”的终极底线。适用场景适用于生产环境或对安全有极高要求的场景。你需要像配置防火墙一样仔细规划并显式地列出代理被允许做的每一件事。这提供了最强的安全保证但前期配置工作量较大。通过设置环境变量来切换模式# 切换到封闭模式 export CLAWTHORITY_MODEclosed # 随后启动你的OpenClaw代理 openclaw run your-agent模式在插件激活时读取更改后需要重启OpenClaw才能生效。3.3 编写你的第一条策略规则Clawthority的策略规则存储在data/rules.json文件中支持热重载约300毫秒生效。规则文件是一个JSON数组每条规则定义了一个决策。规则的核心结构如下{ effect: permit, // 或 forbid action_class: filesystem.read, resource: optional_resource_identifier, match: optional_string_pattern, priority: 50 // 数字越高优先级越高 }让我们从几个实际例子开始示例1允许读取文件但禁止删除[ { effect: permit, action_class: filesystem.read }, { effect: forbid, action_class: filesystem.delete, priority: 90 // 赋予较高优先级确保不会被低优先级的permit规则覆盖 } ]在开放模式下第一条规则是冗余的因为默认允许但显式声明可以让策略更清晰。第二条规则则明确禁止了删除操作。示例2禁止代理调用某个特定的自定义工具假设你有一个名为send_alert_to_slack的工具你希望完全禁止代理使用它无论它被归类为什么动作类。[ { effect: forbid, resource: tool, match: send_alert_to_slack } ]这里使用了resource和match字段进行更细粒度的匹配。resource: “tool”表示匹配工具资源match值支持通配符。示例3在封闭模式下构建白名单在封闭模式下你必须为所有需要的操作开绿灯。[ { effect: permit, action_class: filesystem.read }, { effect: permit, action_class: web.get }, { effect: permit, action_class: llm.complete } // 注意没有出现在此列表中的动作类将被默认拒绝。 ]编写完规则后保存data/rules.json文件。你会在OpenClaw的日志中看到类似[clawthority] │ Policy reloaded from disk的提示表示新规则已生效。现在当你运行代理时任何被禁止的操作都会在日志中被清晰标记并拦截[clawthority] │ DECISION: ✕ BLOCKED (cedar/forbid priority100 ruleaction:shell.exec) — Shell execution is unconditionally forbidden同时这次决策的完整详情包括动作类、目标、决策原因、时间戳等会被以结构化的JSON格式追加到data/audit.jsonl文件中供后续审计和分析。4. 深入核心动作注册表与策略评估流程要熟练运用Clawthority必须深入理解其内部的两个核心机制动作注册表如何对工具调用进行“翻译”以及两阶段的策略评估管道如何工作。4.1 动作注册表从工具名到语义动作动作注册表是Clawthority的“翻译官”。它的任务是将千变万化的工具调用请求映射到一组有限且定义明确的标准动作类上。这是实现语义化授权的基石。一个工具调用进入Clawthority时携带的是原始信息比如工具名delete_file和参数{“path”: “/tmp/test.txt”}。动作注册表会执行以下归一化流程名称匹配首先在注册表中查找delete_file这个工具名对应的标准动作类。注册表预定义了大量常见工具及其别名。参数分析在某些情况下还会分析参数内容。例如一个名为write_file的工具如果其path参数是一个URL如http://example.com/upload它可能会被重新分类为web.post动作因为其语义更接近HTTP POST请求而非本地文件写入。风险升级对于shell.exec或某些写入操作如果参数中包含Shell元字符如;、|、或可疑模式其风险等级可能会被从high提升到critical触发更严格的检查。回退处理如果工具名在注册表中完全找不到它会被归类到unknown_sensitive_action。这是一个非常重要的安全特性在开放和封闭两种模式下未知动作默认都是被关键禁止的。这迫使开发者必须显式地为新工具注册别名或审查其安全性避免了“未知即放行”的隐患。下表列出了部分核心动作类及其含义动作类风险等级默认HITL典型工具别名示例说明filesystem.read低无read_file,cat,view读取文件内容通常风险较低。filesystem.write中每次请求write_file,edit,append修改或创建文件。可能覆盖重要数据。filesystem.delete高每次请求delete_file,rm,unlink删除文件可能导致数据丢失。shell.exec高每次请求exec,bash,run_command执行任意Shell命令权限极高。communication.external.send高每次请求send_email,post_to_slack向外部系统发送信息可能泄露数据。web.post中每次请求http_post,axios.post发起HTTP POST请求可能修改远程状态。payment.initiate关键每次请求stripe_charge,transfer_funds涉及资金交易风险最高。credential.write关键每次请求set_api_key,store_password写入新的凭证或密钥。unknown_sensitive_action关键每次请求(所有未知工具)未知工具的兜底分类强制安全处理。实操心得在开发自定义工具时花点时间查阅完整的动作注册表文档为你工具的功能选择最贴切的动作类别名。这能确保你的安全策略精准生效。如果工具行为复杂考虑将其拆分为多个更细粒度的工具分别对应清晰的动作类。4.2 两阶段评估管道从能力检查到策略引擎当一个工具调用被归一化为ExecutionEnvelope执行信封包含动作类、目标、负载哈希等后它将进入一个两阶段的评估管道。这个管道是串行的任何一阶段拒绝整个调用即被拒绝。阶段一能力门禁这是第一道也是最快的一道检查。它主要处理与预先批准的权限相关的情况。低风险绕过对于标记为极低风险如llm.complete的动作可能直接允许以降低开销。验证能力令牌如果本次调用关联了一个有效的“人在回路”批准令牌Capability Token本阶段会校验其有效性令牌是否匹配核对令牌绑定的(action_class, target, payload_hash)是否与当前请求完全一致。令牌是否在有效期内检查TTL生存时间。令牌类型是单次使用approve_once还是会话级session单次令牌在使用后即被消耗。快速拒绝如果请求来自不可信源且涉及高风险动作可能在此阶段就直接拒绝无需进入更复杂的策略引擎。阶段二约束执行引擎如果请求通过了能力门禁或者本就不需要/没有能力令牌则进入核心的策略评估阶段。路径保护检查针对文件系统操作检查目标路径是否在保护列表内如~/.ssh/,/etc/,*.env等。尝试访问这些路径的操作会被直接拒绝。可信域检查针对外部通信操作如communication.external.send检查目标地址如邮箱、URL是否在可信域白名单内。策略引擎评估调用底层的Cedar策略引擎根据data/rules.json中定义的规则对当前请求的action_class和resource等进行最终评估得出permit或forbid的结论。规则按优先级排序高优先级规则覆盖低优先级规则。人在回路触发在整个管道中如果某个动作类被配置为需要人工审批hitl: per_request且当前请求没有有效的能力令牌那么管道会在此处暂停。系统会通过配置的通道如Telegram Bot向预设的审批人发送审批请求包含操作详情和一次性批准链接。同时向代理返回一个deny决策原因字段为pending_hitl_approval。审批人点击链接批准后系统会生成一个与该次请求绑定的能力令牌。代理需要重新发起完全相同的请求这通常需要代理工作流具备重试或等待逻辑这次请求携带了有效令牌从而通过阶段一的能力门禁最终被允许执行。这个两阶段管道确保了安全检查既高效阶段一快速处理已知安全状态又全面阶段二进行深度策略分析同时无缝集成了人工监督。5. 高级配置与“人在回路”集成Clawthority的强大之处在于其灵活且强大的配置能力尤其是与外部通信工具集成的“人在回路”功能为高风险操作提供了最终的安全阀。5.1 多层级配置管理Clawthority的配置来自三个层面优先级和热重载能力各不相同配置层面位置热重载说明环境变量系统环境变量否需重启控制核心行为模式、功能开关和通信密钥。例如CLAWTHORITY_MODE,TELEGRAM_BOT_TOKEN,SLACK_BOT_TOKEN。策略规则data/rules.json是 (~300ms)定义具体的允许/禁止规则。这是最常修改的部分支持动态更新。HITL策略hitl-policy.yaml是 (~300ms)定义哪些动作类需要人工审批以及审批的详细参数如TTL。典型环境变量配置示例# 设置运行模式为封闭模式 export CLAWTHORITY_MODEclosed # 设置Telegram Bot Token用于发送审批通知 export TELEGRAM_BOT_TOKENyour_bot_token_here export TELEGRAM_CHAT_IDyour_personal_chat_id_here # 启用调试日志了解更多内部决策过程 export CLAWTHORITY_LOG_LEVELdebughitl-policy.yaml配置示例# 定义哪些动作类需要人工介入以及如何介入 policies: - action_class: filesystem.delete hitl: mode: per_request # 每次请求都需要审批 ttl_seconds: 120 # 批准令牌有效期为120秒 consume: approve_once # 令牌使用一次后即失效 channels: [telegram] # 通过Telegram通知 - action_class: communication.external.send hitl: mode: per_request ttl_seconds: 300 consume: session # 令牌在本会话内对同类操作有效 channels: [slack] # 通过Slack通知 - action_class: shell.exec hitl: mode: per_request ttl_seconds: 60 # 执行命令的审批有效期更短 consume: approve_once channels: [telegram, “slack] # 多通道通知确保触达5.2 搭建Telegram审批机器人“人在回路”功能极大地提升了安全性而Telegram是设置起来最快捷的通道之一。创建Bot在Telegram中搜索BotFather发送/newbot指令按提示创建新机器人最终你会获得一个Bot Token形如1234567890:ABCdefGhIJKlmNoPQRsTUVwxyZ。获取Chat ID与你刚创建的Bot发起对话发送任意消息如/start。然后在浏览器中访问以下URL将YOUR_BOT_TOKEN替换为你的Tokenhttps://api.telegram.org/botYOUR_BOT_TOKEN/getUpdates在返回的JSON中找到message.chat.id字段这个数字就是你的Chat ID。配置Clawthority将获取到的Token和Chat ID设置为环境变量。export TELEGRAM_BOT_TOKEN1234567890:ABCdefGhIJKlmNoPQRsTUVwxyZ export TELEGRAM_CHAT_ID987654321测试配置完成后重启OpenClaw。当代理触发一个需要审批的操作如尝试删除文件时你的Telegram就会收到一条格式清晰的消息️ Clawthority 需要您的审批 Action: filesystem.delete Target: /tmp/important_log.txt Summary: 删除文件 /tmp/important_log.txt Expires: 2023-10-27T10:30:00Z Approve: https://your-approval-endpoint/approve/01HJP6... Deny: https://your-approval-endpoint/deny/01HJP6...点击Approve链接即可批准该次操作。链接指向Clawthority内置的HTTP审批端点默认运行在本地。注意事项生产环境中审批链接应当通过反向代理如Nginx配置HTTPS并设置适当的访问控制避免被未授权访问。hitl-policy.yaml中的ttl_seconds不宜设置过长通常60-300秒是合理范围以平衡安全与操作便利性。5.3 审计日志分析与故障排查所有决策无论是允许、拒绝还是等待审批都会被详细记录到data/audit.jsonl文件。这是一份按行分隔的JSON日志是安全审计和问题排查的黄金数据。一条典型的拒绝日志{ timestamp: 2023-10-27T10:15:00.123Z, decision: deny, stage: cedar/forbid, action_class: shell.exec, target: rm -rf /, rule: action:shell.exec, priority: 100, mode: open, deny_reason: Shell execution is unconditionally forbidden, latency_ms: 5, context_hash: a1b2c3d4... }关键字段解读stage: 标识决策发生在哪个阶段如capability_gate,cedar/permit,cedar/forbid帮助定位问题。rule: 触发此次决策的具体规则标识符。priority: 规则的优先级。mode: 决策时的运行模式open或closed。deny_reason: 人类可读的拒绝原因非常直观。常见问题排查思路代理所有操作都被拒绝检查模式首先确认CLAWTHORITY_MODE环境变量。如果在closed模式下你必须显式添加permit规则。检查规则文件确认data/rules.json格式正确没有语法错误。可以尝试暂时移除所有自定义规则看是否恢复默认开放行为。查看审计日志日志中的deny_reason和rule字段会明确指出被哪条规则拦截。“人在回路”通知未收到检查Token和Chat ID确认TELEGRAM_BOT_TOKEN和TELEGRAM_CHAT_ID环境变量设置正确且Bot已启动并与用户对话。检查网络确认运行Clawthority的服务器可以访问Telegram API。检查HITL策略确认hitl-policy.yaml中为对应动作类正确配置了channels。自定义工具被归类为unknown_sensitive_action并被禁止这是预期行为是安全特性。你需要为你的工具在Clawthority的代码中注册动作别名或者编写一条针对该工具名称的显式规则。临时方案在data/rules.json中添加一条针对该工具名的permit规则需谨慎评估风险。长期方案向Clawthority项目提交Pull Request为你的工具添加标准的动作类映射。Clawthority的设计哲学是“默认安全”因此在遇到配置问题时行为往往会偏向于“拒绝”而非“允许”。耐心查看审计日志理解每条决策背后的规则是驾驭这套系统的关键。随着你对动作类和规则引擎越来越熟悉你将能构建出既安全又高效的AI代理授权策略。