OmX 集成 OpenClaw 通知网关Hook Prompt 调优指南简洁 上下文感知【免费下载链接】oh-my-codexOmX - Oh My codeX: Your codex is not alone. Add hooks, agent teams, HUDs, and so much more.项目地址: https://gitcode.com/GitHub_Trending/oh/oh-my-codex本文基于 OmXoh-my-codex仓库中的 docs/openclaw-integration.vi.md越南语本地化文档及其英文主文档 docs/openclaw-integration.md 展开围绕 OpenClaw 通知网关中最关键的质量杠杆——hookinstruction模板进行深入讲解。读者读完本文后将掌握如何在~/.codex/.omx-config.json中精确定位 5 个 hook 事件的指令模板、按事件选用上下文 token、配置minimal/session/verbose三级详细程度策略并能用一条jq命令一键注入结构化提示模板同时理解底层 src/openclaw/ 源码如何读取、插值并安全分发这些指令。一、OpenClaw 通知网关在 OmX 中的定位OmX 的项目定位是“你的 codex 并不孤单”Your codex is not alone它通过 hooks、Agent 团队、HUD 等机制增强 Codex CLI 的体验。其中OpenClaw 通知网关把 OmX 的会话生命周期事件会话开始、空闲、提问、停止、结束转发给外部服务如 clawdbot 或自定义 Webhook从而把 Codex 的每一次操作实时同步到团队协作频道。从源码结构看OpenClaw 集成模块位于 src/openclaw/核心由三部分组成文件职责src/openclaw/types.ts定义配置与载荷类型OpenClawConfig、OpenClawGatewayConfig、OpenClawHookEvent、OpenClawPayload等src/openclaw/config.ts读取并解析notifications.openclaw配置支持显式 schema 与通用别名归一化src/openclaw/dispatcher.ts指令模板插值、HTTP/命令网关分发、超时钳制与 shell 注入防护两条受支持的配置路径英文主文档明确指出集成存在两条受支持的 setup 路径显式 OpenClaw schemanotifications.openclaw——运行时原生形态本文越南语文档的 prompt 调优正是针对该形态下的hooks子结构通用别名custom_webhook_command/custom_cli_command——面向 OpenClaw 或其他服务的灵活设置。两条路径最终都会被 OMX 归一化为内部 OpenClaw 网关映射“These aliases are normalized by OMX into internal OpenClaw gateway mappings”对应实现位于 src/openclaw/config.ts 的normalizeFromCustomAliases函数。激活门Activation Gates在开始调优 prompt 之前必须先确认激活环境变量已设置英文主文档的 Activation gates 章节# 优先在 shell 配置中导出 token 环境变量避免在 JSON 中硬编码密钥 export HOOKS_TOKENyour-openclaw-hooks-token # OpenClaw 分发管线的必需开关 export OMX_OPENCLAW1 # 使用命令网关command gateway时额外必需 export OMX_OPENCLAW_COMMAND1 # 命令网关超时毫秒的可选全局默认值 # 优先级网关级 timeout 环境变量覆盖 5000 默认值 export OMX_OPENCLAW_COMMAND_TIMEOUT_MS120000其中OMX_OPENCLAW1是总激活门OMX_OPENCLAW_COMMAND1是命令网关的独立安全开关。源码 src/openclaw/config.ts 中getOpenClawConfig()的第一步就是校验process.env.OMX_OPENCLAW ! 1并直接返回null而 src/openclaw/dispatcher.ts 的wakeCommandGateway则会单独校验OMX_OPENCLAW_COMMAND未设置时返回“Command gateway disabled”错误——这与文档中的诊断项“Command gateway disabled: set both OMX_OPENCLAW1 and OMX_OPENCLAW_COMMAND1”完全对应。二、Prompt 调优核心五个 hook 的 instruction 编辑位置对于 OpenClaw 集成而言最重要的质量杠杆quality lever是 hook 的instruction模板。越南语文档直接给出了 5 个编辑位置全部位于配置文件的notifications.openclaw.hooks之下notifications.openclaw.hooks[session-start].instructionnotifications.openclaw.hooks[session-idle].instructionnotifications.openclaw.hooks[ask-user-question].instructionnotifications.openclaw.hooks[stop].instructionnotifications.openclaw.hooks[session-end].instruction这 5 个事件与源码 src/openclaw/types.ts 中定义的OpenClawHookEvent联合类型一一对应export type OpenClawHookEvent | session-start | session-end | session-idle | ask-user-question | stop;需要注意的是pre-tool-use、post-tool-use、keyword-detector属于 OMC 专有事件Codex CLI 并不支持因此被有意排除在类型定义之外见 src/openclaw/types.ts 的注释。每个 hook 映射的instruction是发送给 OpenClaw 网关的指令文本模板由OpenClawHookMapping类型约束src/openclaw/types.tsexport interface OpenClawHookMapping { /** 网关名称gateways 对象中的键 */ gateway: string; /** 含 {{variable}} 占位符的指令模板 */ instruction: string; /** 该 hook 事件映射是否激活 */ enabled: boolean; }三、推荐上下文 token让通知“认识”会话instruction模板支持{{变量}}占位符插值。越南语文档给出了两类 token 建议始终包含Always include{{sessionId}}—— 跨日志的会话追踪标识{{tmuxSession}}—— 直接定位 tmux 会话以便后续操作按事件按需包含Include when relevant{{projectName}}—— 项目名称{{question}}—— 仅ask-user-question事件{{reason}}—— 仅session-end事件从源码 src/openclaw/dispatcher.ts 的注释与interpolateInstruction实现看实际支持的变量全集还包括{{projectPath}}、{{prompt}}、{{contextSummary}}、{{timestamp}}、{{event}}、{{instruction}}命令网关专用、{{replyChannel}}、{{replyTarget}}、{{replyThread}}。未解析成功的变量会被替换为空字符串“Unresolved variables are replaced with empty string”插值由正则/\{\{(\w)\}\}/g完成。变量来源在 src/openclaw/index.ts 中集中构建projectName由projectPath经basename()推导tmuxSession在上下文中缺失时会调用getCurrentTmuxSession()自动探测replyChannel/replyTarget/replyThread则来自外部注入的OPENCLAW_REPLY_CHANNEL、OPENCLAW_REPLY_TARGET、OPENCLAW_REPLY_THREAD环境变量。需要强调模板上下文经过白名单过滤buildWhitelistedContext只允许枚举字段进入网关载荷防止敏感数据意外泄露。四、详细程度策略Verbosity越南语文档用三档定义了通知的叙事密度建议默认使用session级别说明适用场景minimal非常简短的通知高信噪比、低叙事只想被轻量打扰时session简洁的操作上下文推荐默认日常开发协作verbose更丰富的状态 / 动作 / 风险表述需要快速可扫读的详细信息时该策略体现在配置顶层notifications.verbosity字段中jq更新命令里的.notifications.verbosity verbose即是对应示例。五、结构化指令格式[event|exec]前缀对于生产部署英文主文档推荐使用 clawdbot Agent 能高效解析的结构化格式[event|exec] project{{projectName}} session{{sessionId}} tmux{{tmuxSession}} 필드1: 값 필드2: 값其中[event|exec]前缀表明这是一个需要 Agent 采取行动的可执行 hookexecutable hook而不是纯消息转发。模板中的韩文字段名요약摘要、우선순위优先级、주의사항注意事项、성과成果、검증验证、다음后续为以韩语为主要工作语言的开发团队提供了一致的结构约定——这也是越南语文档保留韩语字段名模板的原因结构化字段名在跨语言本地化中保持一致便于 Agent 稳定解析。六、实战一条 jq 命令注入完整提示模板越南语文档提供了可直接复制运行的快速更新命令。它一次性把 5 个 hook 的instruction全部改写为“verbose 结构化”风格并将verbosity设为verboseCONFIG_FILE$HOME/.codex/.omx-config.json jq .notifications.verbosity verbose | .notifications.openclaw.hooks[session-start].instruction [session-start|exec]\nproject{{projectName}} session{{sessionId}} tmux{{tmuxSession}}\n요약: 시작 맥락 1문장\n우선순위: 지금 할 일 1~2개\n주의사항: 리스크/의존성(없으면 없음) | .notifications.openclaw.hooks[session-idle].instruction [session-idle|exec]\nsession{{sessionId}} tmux{{tmuxSession}}\n요약: idle 원인 1문장\n복구계획: 즉시 조치 1~2개\n의사결정: 사용자 입력 필요 여부 | .notifications.openclaw.hooks[ask-user-question].instruction [ask-user-question|exec]\nsession{{sessionId}} tmux{{tmuxSession}} question{{question}}\n핵심질문: 필요한 답변 1문장\n영향: 미응답 시 영향 1문장\n권장응답: 가장 빠른 답변 형태 | .notifications.openclaw.hooks[stop].instruction [session-stop|exec]\nsession{{sessionId}} tmux{{tmuxSession}}\n요약: 중단 사유\n현재상태: 저장/미완료 항목\n재개: 첫 액션 1개 | .notifications.openclaw.hooks[session-end].instruction [session-end|exec]\nproject{{projectName}} session{{sessionId}} tmux{{tmuxSession}} reason{{reason}}\n성과: 완료 결과 1~2문장\n검증: 확인/테스트 결과\n다음: 후속 액션 1~2개 $CONFIG_FILE $CONFIG_FILE.tmp mv $CONFIG_FILE.tmp $CONFIG_FILE命令要点解析通过 $CONFIG_FILE.tmp mv ...实现原子写入避免 jq 直接覆盖导致文件损坏5 个instruction各对应一个生命周期事件字段名session-start、session-idle、ask-user-question、stop、session-end必须与VALID_HOOK_EVENTSsrc/openclaw/config.ts完全一致否则事件不会被解析为有效映射\n在 JSON 字符串中转义为换行渲染出的实际指令是多行结构化文本。七、源码级原理配置如何被读取与解析notifications.openclaw配置的完整 JSON 结构executive-summary verbose profile 示例如下这也是越南语文档所针对的显式 schema 的完整形态{ notifications: { verbosity: verbose, openclaw: { hooks: { session-start: { enabled: true, gateway: local, instruction: [session-start|exec]\nproject{{projectName}} session{{sessionId}} tmux{{tmuxSession}}\n요약: 시작 맥락 1문장\n우선순위: 지금 할 일 1~2개\n주의사항: 리스크/의존성(없으면 없음) }, session-idle: { enabled: true, gateway: local, instruction: [session-idle|exec]\nsession{{sessionId}} tmux{{tmuxSession}}\n요약: idle 원인 1문장\n복구계획: 즉시 조치 1~2개\n의사결정: 사용자 입력 필요 여부 }, ask-user-question: { enabled: true, gateway: local, instruction: [ask-user-question|exec]\nsession{{sessionId}} tmux{{tmuxSession}} question{{question}}\n핵심질문: 필요한 답변 1문장\n영향: 미응답 시 영향 1문장\n권장응답: 가장 빠른 답변 형태 }, stop: { enabled: true, gateway: local, instruction: [session-stop|exec]\nsession{{sessionId}} tmux{{tmuxSession}}\n요약: 중단 사유\n현재상태: 저장/미완료 항목\n재개: 첫 액션 1개 }, session-end: { enabled: true, gateway: local, instruction: [session-end|exec]\nproject{{projectName}} session{{sessionId}} tmux{{tmuxSession}} reason{{reason}}\n성과: 완료 결과 1~2문장\n검증: 확인/테스트 결과\n다음: 후속 액션 1~2개 } } } } }读取顺序与优先级契约源码 src/openclaw/config.ts 中getOpenClawConfig()的读取顺序是OMX_OPENCLAW_CONFIG环境变量指向的独立文件若设置~/.codex/.omx-config.json中的notifications.openclaw键主路径默认路径由codexHome()推导见 src/openclaw/config.tsnotifications.custom_cli_command/notifications.custom_webhook_command别名归一化结果。配置在首次读取后被缓存进程生命周期内环境变量不会变化。关键细节是规范优先级契约Canonical precedence contract当显式 OpenClaw 配置与通用别名同时存在时notifications.openclaw胜出两个别名被忽略同时 OMX 输出一条警告“notifications.openclaw is set; ignoring custom_cli_command/custom_webhook_command aliases”。inspectOpenClawConfig返回的warnings数组也记录了同样的信息src/openclaw/config.ts这保证了行为确定且向后兼容。通用别名归一化若使用别名形态src/openclaw/config.ts 的normalizeFromCustomAliases会把它们合成为内部 OpenClaw 配置custom_cli_command映射为type: command的网关默认网关名custom-cli默认事件为session-end、ask-user-question默认指令为OMX event {{event}} for {{projectPath}}custom_webhook_command映射为type: http的网关默认网关名custom-webhookmethod仅允许POST或PUT事件的enabled ! false且字段类型合法才算启用parseEvents会过滤掉不在VALID_HOOK_EVENTS中的事件。八、源码级原理指令插值与安全分发wakeOpenClaw是 notify hook 调用的主入口src/openclaw/index.ts调用链为getOpenClawConfig()→resolveGateway(config, event)→ 按网关类型分发到wakeGatewayHTTP或wakeCommandGateway命令。src/notifications/index.ts 中可以看到它在通知流程中的实际触发方式。分发层有三个值得关注的安全与健壮性设计1. 命令注入防护命令网关模板中的{{变量}}在插值前会逐个经过shellEscapeArg单引号包裹 内部引号转义处理src/openclaw/dispatcher.ts。测试 src/openclaw/tests/dispatcher.test.ts 验证了含单引号的输入its fine会被正确转义为it\s fine。无 shell 元字符的命令走直接 argv 执行只有检测到[|;$()]等元字符时才回退到sh -c。2. 网关 URL 校验HTTP 网关要求 HTTPS仅localhost、127.0.0.1、::1允许 HTTP用于本地开发。validateGatewayUrl的测试覆盖了非法 URL、空串、非本地 HTTP 拒绝等场景src/openclaw/tests/dispatcher.test.ts。3. 超时优先级与钳制命令超时的解析顺序为网关级timeoutOMX_OPENCLAW_COMMAND_TIMEOUT_MS 5000ms 默认值并在运行时钳制到[100ms, 300000ms]安全区间src/openclaw/dispatcher.ts。测试验证了未设置时用 5000、网关超时覆盖环境变量、无效环境变量回退默认值、超界值被钳制src/openclaw/tests/dispatcher.test.ts。对于clawdbot agent工作流文档建议使用1200002 分钟避免过早超时。另外所有 OpenClaw 分发失败都被吞掉swallowed而不会阻塞 hook 会话——这是“fire-and-forget”设计的核心保证唯一例外是调用方可以await等待ask-user-question的投递结果以便下游回复路由保持挂载。九、进阶场景Clawdbot Agent 命令工作流推荐开发使用当你想让 OmX hook 事件触发Agent turn而非纯消息/Webhook 转发时使用命令网关形态。完整配置示例Option C要点如下{ notifications: { enabled: true, verbosity: verbose, events: { session-start: { enabled: true }, session-idle: { enabled: true }, ask-user-question: { enabled: true }, session-stop: { enabled: true }, session-end: { enabled: true } }, openclaw: { enabled: true, gateways: { local: { type: command, command: (clawdbot agent --session-id omx-hooks --message {{instruction}} --thinking minimal --deliver --reply-channel discord --reply-to channel:1468539002985644084 --timeout 120 --json /tmp/omx-openclaw-agent.jsonl 21 || true), timeout: 120000 } }, hooks: { session-start: { enabled: true, gateway: local, instruction: [session-start|exec]\nproject{{projectName}} session{{sessionId}} tmux{{tmuxSession}}\n요약: 시작 맥락 1문장\n우선순위: 지금 할 일 1~2개\n주의사항: 리스크/의존성(없으면 없음) } } } } }开发/生产要点来自英文主文档Shell 安全模板变量如{{instruction}}会被插值进命令字符串模板应保持简单避免在用户派生内容中出现 shell 元字符排查问题时先临时去掉输出重定向再观察命令输出命令末尾加|| true防止 OMX hook 失败阻塞会话使用.jsonl扩展名 追加实现结构化日志聚合使用--reply-to channel:CHANNEL_ID格式优先于频道别名确保 Discord 投递可靠。韩语优先的 tmux 跟进操作#omc-dev 场景强制 hook 指令输出韩语所有 hook instruction 用韩语编写并显式要求 Agent 以韩语回复优先使用--reply-to channel:CHANNEL_ID而非#omc-dev频道别名别名在 bot 未缓存频道时可能失败。追踪发出 hook 的 tmux 会话每个 hook 消息都包含{{sessionId}}和{{tmuxSession}}{{tmuxSession}}存在时作为主要跟进目标缺失时从sessionId与当前项目路径推导。快速检查命令tmux ls | grep ^omx- || true tmux list-panes -a -F #{session_name}\t#{pane_id}\t#{pane_current_path} | grep $(basename $PWD) || trueSOUL.md #omc-dev 跟进 runbookhook 提示有待办或挂起操作时读取SOUL.md与近期#omc-dev上下文用韩语跟进并引用sessionIdtmuxSession若需行动则给出具体下一步需要回复 / 需要重试 / 需要检查会话投递异常时检查日志并去掉吞输出后重试。十、验证与故障排查A) 唤醒冒烟测试/hooks/wakecurl -sS -X POST http://127.0.0.1:18789/hooks/wake \ -H Authorization: Bearer ${HOOKS_TOKEN} \ -H Content-Type: application/json \ -d {text:OMX wake smoke test,mode:now}预期通过信号响应 JSON 包含ok:true。B) 投递验证/hooks/agentcurl -sS -o /tmp/omx-openclaw-agent-check.json -w HTTP %{http_code}\n \ -X POST http://127.0.0.1:18789/hooks/agent \ -H Authorization: Bearer ${HOOKS_TOKEN} \ -H Content-Type: application/json \ -d {message:OMX delivery verification,instruction:OMX delivery verification,event:session-end,sessionId:manual-check}预期通过信号HTTP 2xx 已接受的响应体。预检检查Preflight# token 是否存在 test -n $HOOKS_TOKEN echo token ok || echo token missing # 网关可达性 curl -sS -o /dev/null -w HTTP %{http_code}\n http://127.0.0.1:18789 || echo gateway unreachable # 激活门检查 test $OMX_OPENCLAW 1 echo OMX_OPENCLAW1 || echo missing OMX_OPENCLAW1 test $OMX_OPENCLAW_COMMAND 1 echo OMX_OPENCLAW_COMMAND1 || echo missing OMX_OPENCLAW_COMMAND1Pass/Fail 诊断速查表现象处置401/403bearer token 无效或缺失404路径错误确认/hooks/agent与/hooks/wake5xx网关运行时问题检查日志超时 / 连接拒绝主机、端口、防火墙问题Command gateway disabled同时设置OMX_OPENCLAW1与OMX_OPENCLAW_COMMAND1命令被SIGTERM杀死调大gateways.name.timeoutclawdbot agent 建议120000或设置OMX_OPENCLAW_COMMAND_TIMEOUT_MShook 失败阻塞会话命令末尾加|| true避免 OMX 等待 clawdbot 失败缺少日志使用.jsonl扩展名 追加持久化结构化日志Discord 投递失败改用--reply-to channel:CHANNEL_ID格式而非频道别名日志排查实用命令# 查看结构化 JSONL 日志 tail -n 120 /tmp/omx-openclaw-agent.jsonl | jq -s .[] | {timestamp: (.timestamp // .time), status: (.status // .error // ok)} # 搜索日志中的错误 rg error|failed|timeout /tmp/omx-openclaw-agent.jsonl | tail -20 # 用生产测试过的参数手动重试 clawdbot agent --session-id omx-hooks \ --message OMX hook retry 점검: session{{sessionId}} tmux{{tmuxSession}} \ --thinking minimal --deliver --reply-channel discord --reply-to channel:1468539002985644084 \ --timeout 120 --json十一、总结OpenClaw 通知网关的 Prompt 调优本质上是在回答三个问题向谁发哪个 hook 事件、发什么instruction 模板与上下文 token、以什么姿态发verbosity 级别。越南语文档给出的 5 个编辑位置、两类 token 与三档 verbosity 构成了日常调优的最小操作面而一条jq命令即可完成生产级模板的一次性注入。底层源码 src/openclaw/config.ts 与 src/openclaw/dispatcher.ts 则为这套操作面提供了确定性的解析契约显式配置优先于别名、安全的插值分发shell 转义、URL 白名单、超时钳制以及故障吞没机制配套测试 src/openclaw/tests/ 覆盖了这些行为的边界情况。按文中的验证与诊断步骤完成冒烟测试后即可把 Codex 会话状态稳定地同步到团队协作链路。【免费下载链接】oh-my-codexOmX - Oh My codeX: Your codex is not alone. Add hooks, agent teams, HUDs, and so much more.项目地址: https://gitcode.com/GitHub_Trending/oh/oh-my-codex创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考