如何配置 CodeWhale Hooks 生命周期钩子：session_start 与 pre/post 三类事件实战指南

如何配置 CodeWhale Hooks 生命周期钩子session_start 与 pre/post 三类事件实战指南【免费下载链接】CodeWhaleOpen-source coding agent for your terminal, built in Rust and on a journey of continuous community improvement. Issues and PRs welcome.项目地址: https://gitcode.com/GitHub_Trending/de/CodeWhaleCodeWhale是一个用 Rust 编写的开源终端编码智能体Coding Agent。它的Hooks生命周期钩子机制可以让你在会话启动session_start、工具调用前后pre/post等 11 个关键时刻自动运行自己的 shell 命令——发通知、拦截危险操作、注入临时凭证全部由你掌控 一、什么是 Hooks 生命周期钩子把 Hooks 理解成事件订阅器当 CodeWhale 的交互式 TUI 到达某个生命周期节点时它会自动执行你在配置文件里注册的一条 shell 命令。每条钩子就是一个普通进程通过环境变量接收上下文如DEEPSEEK_SESSION_ID、DEEPSEEK_WORKSPACE、DEEPSEEK_MODEL部分事件还会通过stdin 传入 JSON 负载其中 3 类事件甚至能反向改变CodeWhale 的下一步行为注意Hooks 是 TUI 运行时功能——codewhale exec无头模式和 CLI 子命令不会触发钩子。权威参考文档见 docs/HOOKS.md事件枚举定义在 crates/tui/src/hooks/config.rs。二、快速上手5 分钟配置第一个 session_start 钩子打开或新建~/.codewhale/config.toml加入下面这段即可——当 TUI 引擎就绪、首次界面渲染前session_start钩子会触发一次[hooks] enabled true [[hooks.hooks]] name announce event session_start command echo CodeWhale 会话已启动配置完成后在 TUI 中输入/hooks命令即可查看全部已注册的钩子、全局开关状态以及加载时被拒绝的条目/hooks events则列出全部 11 个事件名非常适合初学者探索命令实现见 crates/tui/src/commands/groups/core/hooks.rs。三、三类事件全景11 个事件按能不能改变行为分CodeWhale 共提供 11 个钩子事件按干预能力可归为三类1️⃣ 观察型Observer——只看不改如session_start、session_end、tool_call_after、turn_end、on_error、subagent_spawn、subagent_complete、mode_change等。它们的结果会被忽略stdout 直接丢弃非零退出码只记录警告。这类钩子适合打日志、发通知、推送告警——不能改变 CodeWhale 的后续行为但可以产生任意外部副作用它毕竟是以你的身份运行的命令。2️⃣ Pre 类——行动前拦截/改写tool_call_beforepre 工具调用在每次工具执行前触发可输出 JSON 裁决——allow/deny/ask还能用updatedInput改写工具入参、用additionalContext追加给模型的上下文message_submitpre 消息提交在消息进入历史和模型之前可替换或拦截你发送的文本退出码2表示阻断3️⃣ Post / 环境注入类tool_call_afterpost 工具调用工具结果落定后触发适合审计与统计shell_env在每次exec_shell前同步运行把 stdout 按KEYVALUE解析成环境变量注入——注入临时凭证、按技能调整 PATH 的神器 四、实战pre/post 钩子的三个高频用法用法 1危险命令守门员pre[[hooks.hooks]] name gate event tool_call_before command ~/.codewhale/hooks/gate.sh condition { type tool_name, name exec_shell } continue_on_error falsegate.sh检查$DEEPSEEK_TOOL_ARGS中的命令想拦截就输出{decision:deny,reason:原因}。注意continue_on_error false的语义守门人没给出裁决就不算放行——超时或异常退出会直接拒绝该工具调用。用法 2工具调用审计post[[hooks.hooks]] event tool_call_after command echo $DEEPSEEK_TOOL_NAME $DEEPSEEK_TOOL_EXIT_CODE ~/audit.log通过DEEPSEEK_TOOL_CALL_ID可以把同一次调用的 before/after/error 记录精确关联起来。用法 3临时凭证注入[[hooks.hooks]] name aws-creds event shell_env command aws-vault export my-profile --formatenv condition { type tool_category, category shell }解析后的键名而非值会写入~/.codewhale/audit.log方便事后对账。五、配置要点与避坑清单 ⚠️要点说明超时是覆盖不是默认[hooks].default_timeout_secs一旦设置会覆盖所有钩子自己的timeout_secs设为0会被直接拒绝加载background 钩子不能裁决后台钩子提交后不被等待永远无法 allow/deny/改写只适合观察条件不支持的钩子会被拒绝加载期即拒/hooks list中显示rejected:而不是静默失效项目级钩子需信任仓库可自带.codewhale/hooks.toml但仅在用户配置中信任工作区后生效多个钩子按配置顺序执行后一个钩子能看到前一个的输出updatedInput以最后一个为准完整字段示例可参考 config.example.toml 中被注释的[hooks]段落执行器核心逻辑在 crates/tui/src/hooks/executor.rs设计背景见 docs/rfcs/1364-hooks-lifecycle.md。六、安全须知钩子是来自你自己配置的可执行命令——请把~/.codewhale/config.toml当作可执行代码对待钩子进程继承 CodeWhale 的完整环境但本地exec_shell只拿到净化白名单 你的shell_env注入值所有负载工具参数、结果、错误信息都有字节上限钩子输入输出不可能无限复制对话内容写在最后Hooks 是 CodeWhale 从能用走向合你心意的关键开关session_start打个招呼、tool_call_before守住边界、tool_call_after留好审计痕迹——三层防线全在你的一条 TOML 配置里。更多细节欢迎通读 docs/HOOKS.md它是逐事件契约的权威出处。【免费下载链接】CodeWhaleOpen-source coding agent for your terminal, built in Rust and on a journey of continuous community improvement. Issues and PRs welcome.项目地址: https://gitcode.com/GitHub_Trending/de/CodeWhale创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考