WSL内配置Claude Code与Codex CLI向Windows发送通知

背景

在 Windows 环境下进行开发时，许多开发者倾向于使用 Windows Subsystem for Linux (WSL) 来运行 Linux 原生的开发工具链，以获得更接近原生 Linux 的开发体验。然而，WSL 与宿主机 Windows 系统之间的交互往往存在隔阂，尤其是当 WSL 中的进程需要向 Windows 桌面发送通知或触发 GUI 操作时，配置相对繁琐。

本文分享了一种在 WSL 环境中运行 AI 编程助手（如 Anthropic 的 Claude Code 和 OpenAI 的 Codex CLI）时，利用 Hooks（钩子）机制触发 Windows 原生桌面通知的解决方案。通过配置特定的 Hook 命令，开发者可以在 WSL 中的任务完成或需要权限确认时，直接在 Windows 桌面上收到系统级通知，从而提升多任务处理效率和开发体验。

核心内容

该方案的核心在于利用 Claude Code 和 Codex CLI 提供的 Hooks 功能，在特定事件触发时执行外部命令。由于 WSL 进程运行在 Linux 子系统内，而通知功能需要调用 Windows 原生的 API 或工具，因此解决方案采用了 PowerShell (pwsh) 作为桥梁，通过 BurntToast 模块生成 Windows 10/11 风格的 toast 通知。

1. 技术原理

• Hooks 机制：Claude Code 和 Codex CLI 均支持配置 Hooks，允许用户在特定生命周期事件（如任务停止、权限请求）发生时执行自定义命令。
• 跨系统调用：在 WSL 中，可以通过 wsl.exe 或直接调用 Windows 可执行文件（如 pwsh.exe）来执行 Windows 命令。
• 通知生成：使用 PowerShell 的 BurntToast 模块。这是一个流行的 PowerShell 模块，专门用于生成 Windows 10 和 Windows 11 的原生 Toast 通知，支持自定义标题、正文和声音。

2. Codex CLI 配置详解

Codex CLI 使用 config.toml 作为配置文件。配置示例如下：

[features]
hooks = true

[[hooks.Stop]]
[[hooks.Stop.hooks]]
type = "command"
command = '''pwsh.exe -NoProfile -ExecutionPolicy Bypass -Command "Import-Module BurntToast; New-BurntToastNotification -Text 'Codex', '任务完成' -Sound Reminder"'''
timeout = 30
statusMessage = "Codex 完成通知"

[[hooks.PermissionRequest]]
[[hooks.PermissionRequest.hooks]]
type = "command"
command = '''pwsh.exe -NoProfile -ExecutionPolicy Bypass -Command "Import-Module BurntToast; New-BurntToastNotification -Text 'Codex', '需要确认以继续' -Sound Reminder"'''
timeout = 30
statusMessage = "Codex 权限确认"

• [features] hooks = true：启用 Hooks 功能。
• [[hooks.Stop]]：定义任务停止时的钩子。当 Codex 任务正常结束或中断时触发。
• [[hooks.PermissionRequest]]：定义权限请求时的钩子。当 Codex 需要用户确认执行某些操作（如文件写入、命令执行）时触发。
• command：执行的命令。
  • pwsh.exe：调用 PowerShell 7。
  • -NoProfile -ExecutionPolicy Bypass：确保命令在不加载用户配置文件且绕过执行策略限制的情况下运行，提高兼容性和速度。
  • Import-Module BurntToast：加载 BurntToast 模块。
  • New-BurntToastNotification：生成通知。-Text 'Codex', '任务完成' 设置通知的标题为 "Codex"，正文为 "任务完成"。-Sound Reminder 播放提醒声音。
• timeout：命令执行的超时时间（秒）。
• statusMessage：在 CLI 界面中显示的状态消息。

3. Claude Code 配置详解

Claude Code 使用 setting.json 作为配置文件。配置示例如下：

{
  "hooks": {
    "Stop": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "pwsh.exe -NoProfile -ExecutionPolicy Bypass -Command \"Import-Module BurntToast; New-BurntToastNotification -Text 'Claude Code', '任务完成' -Sound Reminder\"",
            "timeout": 30000
          }
        ]
      }
    ],
    "PermissionRequest": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "pwsh.exe -NoProfile -ExecutionPolicy Bypass -Command \"Import-Module BurntToast; New-BurntToastNotification -Text 'Claude Code', '需要确认以继续' -Sound Reminder\"",
            "timeout": 30000
          }
        ]
      }
    ]
  }
}

• 结构差异：与 Codex 的 TOML 格式不同，Claude Code 使用 JSON 格式。
• matcher：在 Claude Code 中，matcher 字段用于匹配特定的事件或条件。此处设为空字符串 ""，表示匹配所有对应的事件类型（Stop 或 PermissionRequest）。
• timeout：单位为毫秒（30000 毫秒 = 30 秒），与 Codex 的秒单位不同，需注意区分。
• 命令转义：JSON 字符串中的双引号需要转义 \"，而 TOML 中使用三重单引号 ''' 包裹命令，避免了复杂的转义问题。

关键要点

• 跨系统通知桥接：该方案成功解决了 WSL 中 Linux 进程向 Windows 桌面发送通知的问题，核心在于调用 Windows 原生的 PowerShell 和 BurntToast 模块。
• 事件驱动：通过配置 Stop（任务完成）和 PermissionRequest（权限请求）两个关键事件，实现了开发流程中的关键节点提醒，避免了开发者需要持续盯着终端窗口的疲劳。
• 配置差异注意：
  • Codex 使用 config.toml，timeout 单位为秒。
  • Claude Code 使用 setting.json，timeout 单位为毫秒，且需要处理 JSON 字符串中的引号转义。
• 依赖项：Windows 主机必须安装 PowerShell 7（pwsh）以及 BurntToast PowerShell 模块。如果未安装 BurntToast，命令将失败，通知不会弹出。
• 安全性：使用 -ExecutionPolicy Bypass 是为了确保命令能在各种 PowerShell 配置下运行，但需注意这可能会绕过某些安全限制。在受控的开发环境中通常是可接受的。

意义与影响

这一配置方案体现了现代开发工具链对“开发者体验”（DX）的精细化追求。

1. 提升多任务效率：AI 编程助手通常需要较长时间运行或等待用户确认。通过桌面通知，开发者可以在处理其他任务（如查阅文档、沟通协作）时，无需频繁切换窗口即可获知 AI 的状态变化，显著减少了上下文切换的成本。
2. WSL 与 Windows 生态融合：它展示了 WSL 不仅仅是一个 Linux 模拟器，而是可以与 Windows 原生工具深度集成的开发环境。这种“Linux 内核 + Windows 原生工具链”的模式，使得开发者能够兼顾 Linux 开发环境的优势（如包管理、命令行工具）和 Windows 的用户体验（如通知、GUI 应用）。
3. 可扩展性：该模式具有高度的可扩展性。开发者可以自定义 Hook 命令，例如在任务完成时自动运行测试脚本、发送 Slack/Teams 消息、或触发 CI/CD 流程，从而构建更自动化的开发工作流。
4. 标准化趋势：随着 Claude Code、Codex CLI 等