---
title: "Windows 钩子用 commandWindows，别指望 PATH 上的 bash"
summary: "跨平台钩子保留 command，Windows 另写 command_windows。系统 PATH 上的 bash 经常是 WSL 垫片，跑 Windows 路径会直接 Failed。"
category: hooks
level: advanced
surfaces: [cli, app]
tags: ["hooks", "Windows", "commandWindows"]
canonical: /tips/hooks-command-windows/
---

# Windows 钩子用 commandWindows，别指望 PATH 上的 bash

跨平台钩子保留 command，Windows 另写 command_windows。系统 PATH 上的 bash 经常是 WSL 垫片，跑 Windows 路径会直接 Failed。

钩子的 `command` 保持 Unix 可移植写法。Windows 运行时只看可选覆盖：

```toml
[[hooks.PreToolUse]]
matcher = "^Bash$"

[[hooks.PreToolUse.hooks]]
type = "command"
command = "python3 /enterprise/hooks/pre_tool_use_policy.py"
command_windows = "py -3 C:\\enterprise\\hooks\\pre_tool_use_policy.py"
timeout = 30
statusMessage = "Checking Bash command"
```

TOML 里 `command_windows` 和 `commandWindows` 都能写；`hooks.json` 用 camelCase。信任哈希按当前系统选中的那条命令计算。

企业托管钩子还要分目录：Unix 用 `managed_dir`，Windows 用 `windows_managed_dir`，脚本本身不会随 Codex 分发。命令写成托管目录下的绝对路径。

原生 Windows 上 `bash` 常解析到 `%LOCALAPPDATA%\Microsoft\WindowsApps\bash.exe`（WSL 垫片），它执行不了 `C:\...` 这种脚本路径，市场插件钩子会全部显示 Failed。不要依赖 PATH 里的 `bash`：改用 Git Bash 的绝对路径，或直接 `commandWindows` 调 `py` / `pwsh`。命令钩子可设 `async = true` 放到后台；`SessionEnd` 仍强制同步，后台钩子不能拦操作。

仓库钩子不要写相对路径 `.codex/hooks/...`。从子目录启动时 cwd 会变，用 `git rev-parse --show-toplevel` 锚定到仓库根。

## 来源

- [OpenAI · Hooks](https://developers.openai.com/codex/hooks)
- [openai/codex #38295](https://github.com/openai/codex/issues/38295)