HTTP Hooks 与云端差异

配置 HTTP 和 prompt Hooks，并区分本地 CLI 与临时云端执行环境。

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

HTTP Hook 把事件 JSON 作为 POST 发送到指定服务，适合由已有服务处理审计或校验。发送内容来自实际事件，可能包含提示、参数或工具结果，应只配置能接收这些数据的服务。

HTTP 配置

{
  "version": 1,
  "hooks": {
    "postToolUse": [
      {
        "type": "http",
        "url": "https://hooks.example.com/copilot",
        "headers": { "X-Source": "copilot-cli" },
        "timeoutSec": 30
      }
    ]
  }
}

替换示例 URL 为自己的服务。type 和 url 必填；headers 可选，默认超时 30 秒。allowedEnvVars 是允许在请求头中展开的环境变量名称数组，配置后 URL 必须使用 HTTPS。

默认只允许 HTTPS。仅当 COPILOT_HOOK_ALLOW_LOCALHOST=1 时，localhost、127.*、[::1] 可以使用非 TLS HTTP；preToolUse 和 permissionRequest 的 HTTP Hook 因能授予权限，仍必须 HTTPS。

HTTP preToolUse 请求失败、超时或非 2xx 会回到通常权限流程，不会像 command 非零退出那样拒绝工具。参见Hook 权限决策。

Prompt Hook

type: "prompt" 配合 prompt 文本，只支持 sessionStart，可自动提交自然语言或斜杠命令。CLI 中仅新交互会话触发，恢复会话和 -p 非交互模式不触发。

云端作业也是非交互模式，官方要求确认环境行为后再依赖 prompt 类型，不能把它当成保证执行的云端启动脚本。

云端运行环境

云端智能体 Hooks 在每次任务的临时 Linux 沙箱中运行，仅从克隆仓库的 .github/hooks/*.json 发现配置。

项目	云端行为
命令平台	使用 bash，command 可作后备，忽略 powershell
工作目录	克隆仓库时 /workspace，否则 /root
文件寿命	作业结束后丢弃，需要保留时发送到获准的外部服务
网络	受云端防火墙控制，外部 Hook 服务需管理员允许
HOME	/root，个人路径仍写进临时沙箱
交互	没有用户弹窗或通知，工具预批准

官方参考列出的环境变量为 GITHUB_COPILOT_API_TOKEN、GITHUB_COPILOT_GIT_TOKEN 和 COPILOT_AGENT_PROMPT，不设置 GITHUB_TOKEN。不要把本地登录环境或 CI workflow 环境直接照搬。

云端事件限制

notification 不触发；permissionRequest 不触发或不起作用；preToolUse 的 ask 变成 deny。preCompact 只有 auto；userPromptSubmitted 至多处理初始提示一次；sessionStart 每个作业一次，不是 resume。

agentStop 的 block 会多执行一轮，但仍计入作业超时。云端不加载个人 settings、插件和管理员 Policy Hooks；单个 hooks 文件内 disableAllHooks 可生效，仓库 settings.json 中同名开关不适用。