配置 Hooks

设置项目、个人和策略 Hooks，选择 Shell 或直接执行，并核对加载、禁用与沙箱行为。

This page has not been translated into English yet. The original Chinese version is shown below.

Hooks 在会话和工具事件发生时执行外部命令，适合固定校验、审计和通知。先实现一个范围小、输出可预测的 Hook，再扩展到更多事件。

配置位置

CLI 合并管理员策略、用户、项目和插件来源；同一事件在多个来源中定义时，各来源的条目都会运行，并非高优先级覆盖后只剩一个。

来源	位置
仓库文件	仓库根 .github/hooks/*.json
用户文件	~/.copilot/hooks/*.json，或 $COPILOT_HOME/hooks/
仓库内联	.github/copilot/settings.json 或 settings.local.json 的 hooks
跨工具仓库内联	.claude/settings.json 或 settings.local.json
用户内联	~/.copilot/settings.json 的 hooks
插件	插件声明的 hooks.json 或 hooks/hooks.json

Windows 的默认个人位置为 %USERPROFILE%\.copilot\hooks\。Hook 配置在 CLI 启动时加载，修改后重启。

最小配置

下面在主智能体完成一轮回复时发出终端提示音，保存到个人 hooks 目录中的 JSON 文件：

{
  "version": 1,
  "hooks": {
    "agentStop": [
      {
        "type": "command",
        "bash": "printf '\\a' >&2",
        "powershell": "[System.Media.SystemSounds]::Asterisk.Play()",
        "timeoutSec": 5
      }
    ]
  }
}

这是按官方配置格式组织的通知示例。是否能听到声音取决于终端与系统声音设置；需要图形消息框时可参考官方 macOS / Windows 通知示例。Windows 官方教程使用 PowerShell 7+，可用 pwsh --version 检查。

命令字段

bash 用于 Unix，powershell 用于 Windows。command 是跨平台后备字段，显式平台字段优先。CLI 还支持 exec 配合字符串数组 args 直接启动可执行文件；它不能与三个 Shell 字段混用，也不会解释管道、重定向或 glob。

cwd 指定相对仓库根或绝对工作目录；env 设置环境变量。默认超时 30 秒，可用 timeoutSec 修改；timeout 是秒单位别名，两者同时存在时 timeoutSec 优先。省略 type 默认 command。

沙箱与管理员策略

启用本地沙箱时，仓库、用户和插件命令 Hooks 在沙箱中运行，权限与智能体 Shell 相同。Hook 还可读取自身来源目录；插件 Hook 可写 $COPILOT_PLUGIN_DATA。设置 cwd、TMPDIR 或 PATH 不会增加路径授权，额外访问须配置 sandbox.userPolicy。

管理员策略 Hooks 始终在宿主机执行，不受会话沙箱包裹，也不应调用工作区中的脚本。策略位置为 POSIX 的 /etc/github-copilot/policy.d/*.json，或 Windows 的 C:\ProgramData\GitHub\Copilot\policy.d\*.json；POSIX 文件必须 root 拥有且组和其他用户不可写。Windows 还支持 HKLM 下 GitHub Copilot 策略注册表。

禁用与排障

单个 hooks JSON 顶层 disableAllHooks: true 只禁用该文件。仓库 settings.json 顶层同名设置禁用该仓库会话的普通来源 Hooks，管理员策略 Hooks 继续执行。

JSON、version 或事件列表结构错误会拒绝整个文件；目录加载的某个条目无效时只跳过该条目，其他有效条目保留。settings.json 内联 hooks 更严格，条目校验错误会拒绝整个 hooks 字段。

脚本未执行时检查位置、JSON、可执行权限、shebang 与实际工作目录。详细的事件、输出和错误行为见Hook 事件与权限决策。