omx (oh-my-codex) OpenClaw 集成指南Hook instruction 提示词模板调优与网关分发实战【免费下载链接】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本文基于 oh-my-codex 仓库中的 OpenClaw 集成文档德语版 docs/openclaw-integration.de.md 与英文版 docs/openclaw-integration.md整理而成。核心主题是如何为 omx 的 OpenClaw 通知网关编写精炼且上下文感知的 hook instruction 提示词模板——包括模板存放位置、推荐上下文 Token、结构化指令格式、详细度verbosity策略和 jq 快速更新命令同时结合 src/openclaw/ 源码讲清激活门控、配置优先级、模板插值与命令网关超时机制的底层实现。读完后你可以独立完成 OpenClaw 网关HTTP / CLI 命令 / clawdbot agent的配置、验证与故障排查。一、这套机制解决什么问题omx 在 Codex 会话的关键生命周期节点会话开始、空闲、提问、停止、结束会触发 hook 事件。OpenClaw 集成让这些事件不再只停留在终端通知层面而是可以分发给外部网关推送到 HTTP 服务、执行本地 CLI 命令或者驱动 clawdbot agent 产生真正的agent 回合比如在 Discord#omc-dev频道主动跟进。文档指出OpenClaw 集成中最重要的质量杠杆是 hook 的instruction提示词模板——网关收到的不是原始事件数据而是经过模板插值后的指令文本接收方尤其是 agent 类接收方需要能够高效解析它。因此调好 instruction是整个集成效果的第一决定因素。二、激活门控Activation GatesOpenClaw 分派管道受环境变量门控保护避免未配置的用户误触发# 建议在 shell profile 中导出 token 环境变量避免把密钥硬编码进 JSON export HOOKS_TOKENyour-openclaw-hooks-token # OpenClaw 分派管道的必需开关 export OMX_OPENCLAW1 # 命令类网关type: command额外需要此开关 export OMX_OPENCLAW_COMMAND1 # 可选命令网关的全局默认超时毫秒 # 优先级gateway timeout 环境变量覆盖 默认 5000ms export OMX_OPENCLAW_COMMAND_TIMEOUT_MS120000从源码看这些门控并非纸面约定src/openclaw/config.ts 中getOpenClawConfig()首先检查process.env.OMX_OPENCLAW ! 1则直接返回null即不开OMX_OPENCLAW1时整个 OpenClaw 配置链直接短路src/openclaw/dispatcher.ts 中wakeCommandGateway()单独校验OMX_OPENCLAW_COMMAND 1否则返回Command gateway disabled错误。这解释了为什么命令网关需要两个开关同时打开。超时优先级在 src/openclaw/dispatcher.ts 的resolveCommandTimeoutMs()中实现gatewayConfig.timeoutOMX_OPENCLAW_COMMAND_TIMEOUT_MS 默认5000并且会被钳制在100msMIN_COMMAND_TIMEOUT_MS到300000msMAX_COMMAND_TIMEOUT_MS的安全区间内——所以即使把120000写成999999也只会被钳到 5 分钟。三、instruction 模板在哪里编辑五个 hook 事件各自对应一个 instruction 模板键全部位于~/.codex/.omx-config.json的notifications块下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事件枚举在 src/openclaw/types.ts 中定义export type OpenClawHookEvent | session-start | session-end | session-idle | ask-user-question | stop;注释里特别说明pre-tool-use、post-tool-use和keyword-detector是 OMC 专属事件Codex CLI 不支持因此被有意排除在 OpenClaw 之外。配置读取时src/openclaw/config.ts 的VALID_HOOK_EVENTS白名单与这五个事件严格一致别名归一化Option B时遇到未知事件名会被静默过滤。四、推荐上下文 Token模板变量instruction 模板支持{{variable}}占位符。文档建议必须包含AlwaysToken用途{{sessionId}}跨日志追踪cross-log traceability{{tmuxSession}}直接定位 tmux 会话做后续跟进按事件相关性包含Event-dependentToken适用事件{{projectName}}会话起止类事件{{question}}ask-user-question{{reason}}session-end源码中实际支持的变量集合比文档列出的更完整。src/openclaw/dispatcher.ts 中interpolateInstruction()的文档注释列出了全量支持列表{{projectName}}项目目录 basename、{{projectPath}}完整路径、{{sessionId}}、{{prompt}}、{{contextSummary}}session-end 事件、{{question}}、{{timestamp}}ISO 时间戳、{{event}}事件名、{{instruction}}已插值的指令专供命令网关使用、{{replyChannel}}/{{replyTarget}}/{{replyThread}}分别来自OPENCLAW_REPLY_CHANNEL/OPENCLAW_REPLY_TARGET/OPENCLAW_REPLY_THREAD环境变量。无法解析的变量会被替换为空字符串variables[key] ?? 不会残留{{...}}字面量。变量注入逻辑在 src/openclaw/index.ts 的wakeOpenClaw()中它先按白名单构建上下文buildWhitelistedContext()只保留显式枚举的字段防止敏感数据意外泄漏进网关 payload若上下文未提供tmuxSession则自动通过getCurrentTmuxSession()探测当前 tmux 会话最后先把 instruction 插值一次、把结果再作为{{instruction}}变量供命令网关二次插值。五、结构化指令格式面向生产环境文档要求使用 clawdbot agent 可高效解析的结构化格式[event|exec] project{{projectName}} session{{sessionId}} tmux{{tmuxSession}} 필드1: 값 필드2: 값[event|exec]前缀表明这是一条可执行 hook需要 agent 采取行动而非普通转发消息第一行事件头携带核心路由信息事件名 执行标记第二行是扁平的键值元数据project / session / tmux后续行以字段名: 值的形式给出可扫描的结构化摘要。示例模板中的韩文字段名요약、우선순위、주의사항、성과、검증、다음为以韩语为主语言的开发团队提供一致的结构约定你可以按自己团队的语言习惯替换字段名但建议保持字段: 值的扁平结构不变。六、详细度策略Verbositynotifications.verbosity控制通知的整体详细程度文档给出的三档策略minimal极短信号高信噪比少叙述session推荐默认紧凑的运维上下文verbose更丰富的状态 行动 风险描述从源码看omx 实际支持四档src/notifications/config.ts 定义VALID_VERBOSITY_LEVELS [verbose, agent, session, minimal]秩序为minimal(0) session(1) agent(2) verbose(3)且默认值是sessionDEFAULT_VERBOSITY。verbosity 不只是文案长短它还参与事件门控——EVENT_MIN_VERBOSITY表规定了各事件的最低详细度要求const EVENT_MIN_VERBOSITY: RecordNotificationEvent, VerbosityLevel { session-start: minimal, session-stop: minimal, session-end: minimal, session-idle: session, ask-user-question: agent, };也就是说把 verbosity 设为minimal时session-idle和ask-user-question事件会直接被isEventAllowedByVerbosity()拒绝根本不会触发 OpenClaw 网关调用只有agent及以上等级时ask-user-question才放行。此外shouldIncludeTmuxTail()规定 tmux 尾部输出只在session及以上等级附带。生效优先级为环境变量OMX_NOTIFY_VERBOSITY 配置文件notifications.verbosity 默认session见 src/notifications/config.ts 的getVerbosity()。七、执行摘要型 verbose 配置示例想要详细但可快速扫读的通知时使用执行摘要Executive-summaryverbose profile{ 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개 } } } } }每条 instruction 都遵循同一模式[事件|exec]头 → 元数据行 → 三个字段: 一句话约束行把接收方 agent 的输出长度和结构提前锁定防止下游产生冗长回复。八、jq 快速更新命令不手工编辑 JSON 时可以用下面这条 jq 命令一次性把verbosity提升为verbose并写入上述五个 instruction 模板CONFIG_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 中途失败留下损坏的半截 JSON。九、配置来源与优先级契约Canonical Precedence Contract当显式 OpenClaw 配置和通用别名同时存在时行为契约是notifications.openclaw胜出custom_webhook_command/custom_cli_command被忽略OMX 会打印告警以保持行为透明。从源码看该契约在 src/openclaw/config.ts 中有两处落地getOpenClawConfig()在显式配置有效且别名也存在时console.warn提示 notifications.openclaw is set; ignoring custom_cli_command/custom_webhook_command aliasesinspectOpenClawConfig()则返回结构化的检查状态configured/disabled/missing-config/invalid-config/not-configured其中explicitOverridesAliases与warnings字段供 doctor 类诊断命令消费。配置读取还有第三个入口OMX_OPENCLAW_CONFIG环境变量指向一个独立的配置文件整个文件即OpenClawConfig需满足enabled gateways hooks有效性校验且读取结果在进程生命周期内被缓存_cachedConfig测试中可用resetOpenClawConfigCache()重置。配置读取的完整优先级为OMX_OPENCLAW_CONFIG指向的独立文件如设置~/.codex/.omx-config.json中的notifications.openclawnotifications.custom_cli_command/notifications.custom_webhook_command别名归一化为内部 OpenClaw 运行时配置。十、三种网关配置路径Option A显式notifications.openclawHTTP 网关{ notifications: { enabled: true, openclaw: { enabled: true, gateways: { local: { type: http, url: http://127.0.0.1:18789/hooks/agent, headers: { Authorization: Bearer ${HOOKS_TOKEN} } } }, hooks: { session-end: { enabled: true, gateway: local, instruction: OMX task completed for {{projectPath}} }, ask-user-question: { enabled: true, gateway: local, instruction: OMX needs input: {{question}} } } } } }HTTP 网关参数见 src/openclaw/types.ts 的OpenClawHttpGatewayConfigurl必填headers可选自定义请求头method默认POST仅允许POST/PUT别名归一化时其他值一律按 POST 处理timeout为每请求超时毫秒数HTTP 网关默认 10000msDEFAULT_HTTP_TIMEOUT_MS注意与命令网关的 5000ms 默认值不同。URL 会被validateGatewayUrl()校验必须 HTTPS仅 localhost / 127.0.0.1 / ::1 例外允许 HTTP便于本地开发——上面的http://127.0.0.1:18789因此合法。Option B通用别名custom_webhook_command/custom_cli_command{ notifications: { enabled: true, custom_webhook_command: { enabled: true, url: http://127.0.0.1:18789/hooks/agent, method: POST, headers: { Authorization: Bearer ${HOOKS_TOKEN} }, events: [session-end, ask-user-question], instruction: OMX event {{event}} for {{projectPath}} }, custom_cli_command: { enabled: true, command: ~/.local/bin/my-notifier --event {{event}} --text {{instruction}}, events: [session-end], instruction: OMX event {{event}} for {{projectPath}} } } }这些别名会被 OMX 归一化成内部的 OpenClaw 网关映射。从 src/openclaw/config.ts 的normalizeFromCustomAliases()看custom_cli_command生成名为custom-cli可被gateway字段改名的type: command网关custom_webhook_command生成custom-webhook的type: http网关events缺省或非法时回退到默认事件集[session-end, ask-user-question]DEFAULT_ALIAS_EVENTSinstruction缺省为OMX event {{event}} for {{projectPath}}。Option CClawdbot agent-command 工作流开发场景推荐当希望 OMX hook 事件触发真正的 agent 回合而非普通 webhook 转发时使用例如#omc-dev频道{ 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주의사항: 리스크/의존성(없으면 없음) }, 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개 } } } } }文档给出的 Shell 安全与生产最佳实践均有源码对应模板变量会插入命令字符串保持模板简单用户派生内容避免 shell 元字符。从源码看src/openclaw/dispatcher.ts 的wakeCommandGateway()会对每个{{variable}}的值先做shellEscapeArg()单引号包裹 内嵌引号转义再插值插值后的命令若含 shell 元字符[|;$()]则走sh -c否则直接 argv 执行POSIX 下命令在独立进程组中运行超时或父进程 SIGTERM 时清理整棵进程树1 秒宽限后 SIGKILL命令末尾加|| true防止 clawdbot 失败阻塞 OMX 会话。这与 src/openclaw/index.ts 中wakeOpenClaw()永不向 hook 抛错catch 后返回null的防御性设计互为补充结构化日志用.jsonl扩展名 追加写便于日志聚合与事后排查Discord 投递优先--reply-to channel:CHANNEL_ID比频道别名更可靠机器人未缓存频道时#omc-dev形式的别名可能失败clawdbot agent 工作流把 timeout 设为1200002 分钟避免过早超时。十一、开发指南OpenClaw Clawdbot Agent韩语跟进模式当#omc-dev需要把 OpenClaw 通知当作真实的 clawdbot agent 回合并带主动跟进行为时文档给出三步法。1) 在 hook instruction 中强制韩语输出所有 instruction 用韩语编写并在模板中显式要求韩语回复优先使用--reply-to channel:CHANNEL_ID格式而非频道别名。示例指令风格OMX 훅{{event}} 프로젝트{{projectName}} 세션{{sessionId}}. 반드시 한국어로 응답하세요. OMX tmux 세션: {{tmuxSession}}. SOUL.md 및 #omc-dev 맥락을 참고해 필요한 후속 액션이 있으면 즉시 안내하세요.2) 追踪哪个 OMX tmux 会话发出了 hook每条 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) || true3) SOUL.md #omc-dev 跟进 runbook当 hook 提示存在活跃工作或待用户操作时——(1) 阅读SOUL.md与近期#omc-dev上下文(2) 用韩语跟进并引用sessionIdtmuxSession(3) 需要行动时给出具体下一步需回复 / 需重试 / 需检查会话(4) 投递异常时检查日志并在不吞输出的前提下重试。排查命令# 查看结构化 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十二、验证必须执行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 已接受accepted响应体。十三、预检清单与故障诊断预检命令# 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网关运行时问题查日志超时 / 连接被拒主机 / 端口 / 防火墙问题命令网关未生效需同时设置OMX_OPENCLAW1与OMX_OPENCLAW_COMMAND1命令被 SIGTERM 杀死调大gateways.name.timeoutclawdbot agent 建议120000或设置OMX_OPENCLAW_COMMAND_TIMEOUT_MShook 失败阻塞会话确保命令以|| true结尾日志缺失使用.jsonl扩展名 追加做持久结构化日志Discord 投递失败用--reply-to channel:CHANNEL_ID替代频道别名从源码结构看失败被吞掉是设计目标而非缺陷src/openclaw/index.ts 的模块注释明确写着 All calls are non-blocking with timeouts. Failures are swallowed to avoid blocking hooks且wakeOpenClaw()的 catch 分支只在不启用调试日志OMX_OPENCLAW_DEBUG1时静默返回null——排查投递问题时开OMX_OPENCLAW_DEBUG1可在 stderr 看到每次 wake 的ok / error摘要。十四、小结调优主杠杆notifications.openclaw.hooks[event].instruction五事件各自独立采用[event|exec]结构化格式 强制上下文 Token{{sessionId}}/{{tmuxSession}}必带详细度verbosity四档源码实现默认sessionask-user-question需要agent及以上才会放行安全门控OMX_OPENCLAW1全局、OMX_OPENCLAW_COMMAND1命令网关、超时钳制 100ms~300s、HTTP 强制 HTTPSlocalhost 例外、命令变量 shell 转义 进程树清理优先级notifications.openclaw 通用别名同时存在时告警OMX_OPENCLAW_CONFIG可指向独立配置文件验证闭环/hooks/wake冒烟 /hooks/agent投递验证 预检命令 诊断表覆盖了从认证、路径、超时到 Discord 投递的常见故障面。相关源码与文档入口src/openclaw/config.ts、src/openclaw/dispatcher.ts、src/openclaw/types.ts、src/openclaw/index.ts、src/notifications/config.ts、英文版完整指南 docs/openclaw-integration.md、德语版 docs/openclaw-integration.de.md。【免费下载链接】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），仅供参考