跳到主要内容

使用 Hooks

Hooks 是 Copilot Shell 的拦截机制，可以在工具调用前后、代理处理前后 执行自定义脚本，实现安全防护、自动化审批、上下文注入等功能。

快速开始​

列出所有已注册的 Hooks：

/hooks list

Hook 事件​

Copilot Shell 支持以下 hook 事件：

事件触发时机典型用途
SessionStart会话开始（启动/恢复/清除）初始化环境、加载上下文
SessionEnd会话结束（退出/清除）清理资源、保存状态
UserPromptSubmit用户提交提示后、规划前注入上下文、验证输入、阻止本轮
Stop代理即将停止时审查输出、强制重试
BeforeModel发送 LLM 请求前切换模型、修改参数、模拟响应
AfterModel收到 LLM 响应后过滤响应、记录日志
BeforeToolSelectionLLM 选择工具前过滤可用工具集
PreToolUse工具执行前拦截危险命令、修改参数、安全审查
PostToolUse工具执行后处理结果、日志记录、隐藏敏感输出
PostToolUseFailure工具执行失败后错误恢复、沙箱绕过
PreCompact上下文压缩前保存状态、通知用户
Notification系统通知发生时转发桌面提醒
PermissionRequest权限对话框显示时自动批准或拒绝权限

管理 Hooks​

查看已注册 hooks​

/hooks list

显示所有 hooks 的名称、来源、状态（启用/禁用）。

启用或禁用特定 hook​

通过配置文件禁用：

{
  "hooksConfig": {
    "disabled": ["sandbox-guard"]
  }
}

全局关闭 hooks 系统​

{
  "hooksConfig": {
    "enabled": false
  }
}

Hook 配置格式​

在 settings.json 中配置自定义 hook：

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "run_shell_command",
        "sequential": true,
        "hooks": [
          {
            "type": "command",
            "command": "/path/to/my-hook.sh",
            "name": "my-hook",
            "timeout": 10000
          }
        ]
      }
    ]
  }
}

配置字段​

每个事件下是一个匹配组数组，每个匹配组包含：

字段类型说明
matcherstring匹配的工具名（正则），空或 "*" 为匹配所有
sequentialboolean是否串行执行（默认并行）
hooksarray该匹配组下的 hook 列表

每个 hook 对象的字段：

字段类型说明
typestring执行引擎，目前仅支持 "command"
commandstringHook 脚本路径或命令
namestringHook 名称（用于日志和管理命令）
timeoutnumber超时时间（毫秒），默认 60000

Hook 的来源优先级​

当多个来源定义了同一事件的 hooks 时，执行优先级为：

  1. User — 用户设置中定义的 hooks
  2. Extension — 扩展注入的 hooks
  3. Remote — 远程加载的 hooks

Hook 输入输出​

Hook 脚本通过 stdin 接收 JSON 输入，通过 stdout 返回 JSON 输出。

PreToolUse 输入示例​

{
  "hook_event_name": "PreToolUse",
  "tool_name": "run_shell_command",
  "tool_input": {
    "command": "rm -rf /tmp/test"
  },
  "session_id": "abc123",
  "cwd": "/home/user/project",
  "timestamp": "2025-01-01T00:00:00Z"
}

PreToolUse 输出示例​

阻止执行：

{
  "decision": "deny",
  "reason": "危险命令已被拦截"
}

允许执行并修改参数：

{
  "hookSpecificOutput": {
    "tool_input": {
      "command": "linux-sandbox -- rm -rf /tmp/test"
    }
  }
}

相关文档​