——
OpenClaw 新增 before_agent_run 钩子：5 个关键功能实现用户输入拦截
OpenClaw 最新合并的 PR #75035 为 AI Agent 工作流引入了革命性的控制能力——通过 before_agent_run 插件钩子，开发者现在可以在 Agent 执行前拦截、审查甚至阻断用户输入。这一功能对于构建安全的企业级 AI 应用至关重要。
本文将深入解析该功能的 5 个核心实现细节，帮助你快速上手这一强大的生命周期控制机制。
—
什么是 before_agent_run 钩子？
在 OpenClaw 的插件架构中，生命周期钩子（Lifecycle Hooks）允许开发者在关键节点插入自定义逻辑。before_agent_run 是最新引入的钩子，它在 AI Agent 开始处理用户输入之前触发，支持两种决策模式：
| 决策类型 | 行为 | 适用场景 |
|———|——|———|
| PASS | 允许输入继续传递到 Agent | 常规对话流程 |
| BLOCK | 拦截输入，阻止 Agent 执行 | 安全审查、内容过滤、权限控制 |
// 插件配置示例：before_agent_run 钩子
{
"hooks": {
"before_agent_run": {
"enabled": true,
"decision": "pass", // 或 "block"
"redact_blocked": true, // 阻断时是否脱敏存储
"diagnostics": true // 启用诊断日志
}
}
}
—
5 个关键功能详解
1. 灵活的 Pass/Block 决策机制
before_agent_run 钩子最核心的能力是运行时决策。插件可以根据业务规则动态判断：
// 自定义插件实现示例
class ContentFilterPlugin {
async before_agent_run(context) {
const { userInput, session } = context;
// 自定义审查逻辑
const riskScore = await this.analyzeRisk(userInput);
if (riskScore > 0.8) {
return {
decision: "block",
reason: "HIGH_RISK_CONTENT",
redactedContent: this.redactSensitive(userInput)
};
}
return { decision: "pass" };
}
}
2. 阻断内容的脱敏持久化
安全与隐私并重——当输入被阻断时，系统支持脱敏存储（Redacted Persistence）：
- 原始敏感内容不会进入数据库
- 保留审计所需的元数据（时间戳、阻断原因、会话 ID）
- 符合 GDPR、CCPA 等数据合规要求
查看阻断记录（脱敏视图）
openclaw logs --filter "event:blocked_turn" --redacted
3. 增强的诊断与可观测性
PR #75035 同步更新了诊断系统，开发者可以：
- 通过 Gateway 日志追踪完整的决策链路
- 在 WebChat 界面实时查看阻断事件
- 导出结构化日志用于安全审计
启用详细诊断模式
export OPENCLAW_DIAGNOSTICS=before_agent_run,gateway,session
openclaw gateway --verbose
4. 运行时上下文隔离
关键安全修复：阻断决策的运行时上下文不会泄露到模型提示（Model Prompt）中。这防止了潜在的提示注入攻击，确保 AI 无法通过上下文推断出被拦截的内容。
5. 全面的测试覆盖
该功能包含 4 个维度的测试保障：
| 测试类型 | 覆盖范围 |
|———|———|
| Runner 测试 | 端到端工作流验证 |
| Gateway 测试 | API 网关集成场景 |
| Session 测试 | 会话状态管理 |
| Plugin 测试 | 自定义插件兼容性 |
—
配置最佳实践
基础配置模板
openclaw.config.yaml
plugins:
- name: content_filter
hook: before_agent_run
priority: 100 # 执行优先级，数值越小越早执行
rules:
- type: keyword_blocklist
keywords: ["password", "secret_key", "api_token"]
action: block
redact: true
- type: rate_limit
max_requests_per_minute: 60
action: block
message: "请求过于频繁，请稍后再试"
多插件链式执行
// 多个 before_agent_run 插件按优先级链式执行
const pluginChain = [
{ name: "auth_check", priority: 10 }, // 先验证身份
{ name: "content_filter", priority: 20 }, // 再过滤内容
{ name: "cost_control", priority: 30 } // 最后检查成本
];
—
常见问题 FAQ
Q1: before_agent_run 钩子和现有的 before_turn 有什么区别？
before_turn 在每次对话轮次开始时触发，而 before_agent_run 专门针对 AI Agent 的执行环节。如果你的应用使用多 Agent 架构，before_agent_run 可以精确控制特定 Agent 的准入，而不影响其他组件。
Q2: 阻断后的用户体验如何设计？
建议配置友好的错误提示，并引导用户修正输入：
{
decision: "block",
userMessage: "您的输入包含敏感信息，请移除后再试。",
suggestedAction: "REMOVE_SENSITIVE_DATA",
helpLink: "https://docs.openclaw.com/security/best-practices"
}
Q3: 是否支持异步审查（如调用外部 API）？
是的，before_agent_run 支持异步决策。但需注意设置超时控制，避免阻塞用户请求：
{
"hooks": {
"before_agent_run": {
"async_timeout_ms": 500, // 最大等待 500ms
"fallback_decision": "pass" // 超时时的默认行为
}
}
}
Q4: 如何迁移现有的内容过滤逻辑？
OpenClaw 提供迁移向导：
openclaw migrate --from before_turn --to before_agent_run --dry-run
Q5: 企业版是否有额外的安全功能？
企业版支持基于策略的访问控制（PBAC）和与 SIEM 系统的原生集成，可自动同步阻断事件到 Splunk、Datadog 等平台。
—
总结与下一步
before_agent_run 钩子的引入标志着 OpenClaw 在企业级 AI 安全领域的重要进步。通过本文介绍的 5 个核心功能，你可以：
1. ✅ 实现精细化的输入审查
2. ✅ 满足数据合规要求
3. ✅ 提升系统的可观测性
4. ✅ 防范提示注入攻击
5. ✅ 构建可靠的测试体系
推荐下一步行动：
- 阅读 OpenClaw 插件开发指南 创建你的第一个审查插件
- 查看 Gateway 配置参考 优化部署参数
- 加入 OpenClaw 社区 Discord 与开发者交流
—
相关阅读
—
参考来源
