Operit AI 中文文档 下载 App

Hook Runner：在 Agent 调工具时插入拦截与审计

Hook Runner 是什么

Hook Runner 是 v1.12 起引入的底层机制——在 Agent 调用工具的前后插入拦截器。可以做：

这是把桌面 Agent harness 的「sidecar 拦截器」思维带进 Android App 的设计——桌面 Agent 圈还在补这个，Operit 已经做了。

工作原理

Agent 决定调用工具 Foo(params)
  ↓
  Hook Runner 拦截（Foo 是已注册 Hook 的目标）
  ↓
  Before-Hook 执行（可以检查 / 改写 params）
  ↓
  如果 Before-Hook 返回「放行」 → 继续调用 Foo
  如果 Before-Hook 返回「拦截」 → 终止调用，返回错误
  ↓
  Foo 正常执行
  ↓
  After-Hook 执行（可以检查返回值 / 追加后处理）

可用 Hook 点

Hook 点触发时机用途
before_tool_callAgent 调用工具前权限检查、参数改写、弹出确认
after_tool_call工具执行后审计日志、后处理结果
before_llm_request发送给模型前系统提示词注入、请求改写
after_llm_response模型返回后审计、结果校验、安全过滤
before_workflow_step工作流每步执行前步骤级的条件判断和确认
after_workflow_step工作流每步执行后步骤级的日志和告警

常见使用场景

场景一：危险操作弹窗确认

Hook 点：before_tool_call
目标工具：pkg-install / pkg-uninstall
逻辑：弹出对话框「Operit 即将安装/卸载应用，确认？」
      用户点确认 → 放行
      用户点取消 → 拦截

场景二：文件访问路径限制

Hook 点：before_tool_call
目标工具：file-read / file-write
逻辑：检查路径是否在允许范围内
      如果不在 /sdcard 或 ~/workspace 下 → 改写路径到安全目录

场景三：审计所有工具调用

Hook 点：after_tool_call
目标工具：所有
逻辑：把工具名、参数、返回值、时间戳写入审计日志
      定期整理成报告发给用户

场景四：模型请求安全过滤

Hook 点：before_llm_request
目标：所有模型请求
逻辑：扫描请求中的敏感词 / 隐私信息
      发现后标记或拦截

配置 Hook

内置 Hook（开箱即用）

Operit v1.12+ 自带一些 Hook 规则，在设置里可以直接开关：

自定义 Hook（高级）

自定义 Hook 需要写简单的 Python 脚本，放到 Operit 的 hooks/ 目录：

# hooks/block-dangerous-path.py
def before_tool_call(tool_name, params):
    # 拦截访问 /data/system 等敏感路径的文件操作
    if tool_name in ['file-read', 'file-write']:
        path = params.get('path', '')
        if path.startswith('/data/system'):
            return {'action': 'block', 'reason': '敏感路径访问被 Hook 拦截'}
    return {'action': 'allow'}

def after_tool_call(tool_name, result):
    # 记录审计日志
    with open('/sdcard/operit-audit.log', 'a') as f:
        f.write(f"[{tool_name}] -> {result}\n")

保存后重启 Operit，Hook Runner 自动加载这个 Hook。

和计划模式（Plan-mode）的配合

Plan-mode 是 v1.12 引入的另一个设计——让 Agent 在执行前先输出行动计划。Hook Runner 可以拦截这个计划，让用户审核：

Agent → 输出计划：[Step 1: 读微信文件, Step 2: 转存网盘]
  ↓
Hook Runner 拦截计划 → 弹窗展示给用户
  ↓
用户点「同意」→ 计划放行
用户点「修改」→ 让 Agent 调整计划

两者配合 = Agent 显式「先想后做」+ 用户审核权限——大大降低误操作风险。

安全提示

Hook Runner 本身也能被第三方 Skill / MCP 添加 Hook：