OmX OpenClaw 集成指南Hook 提示词模板调优与上下文感知通知配置实战【免费下载链接】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项目中 OpenClaw 通知集成的核心质量杠杆——hookinstruction提示词模板调优。该指南原本作为 openclaw-integration.ja.mdPrompt tuning guide (concise context-aware) 的日文本地化版本发布本文在其基础上结合 OmX 源码src/openclaw与完整集成文档docs/openclaw-integration.md进行深度展开。读者读完将掌握如何在~/.codex/.omx-config.json中精确定位五个 hook 模板编辑点、如何设计结构化 instruction 让 clawdbot 类 Agent 高效解析、如何用一条 jq 命令一键更新全部模板以及底层模板插值、命令转义与超时钳制的实现原理。一、OpenClaw 集成是什么激活开关先行在动手调优提示词之前需要先理解 OpenClaw 通知管线如何被激活。OmX 将 OpenClaw 作为通知网关gateway在session-start、session-idle、ask-user-question、stop、session-end等 hook 事件发生时把经过模板插值的 instruction 文本推送给 OpenClawHTTP 或本地命令两种网关形态。该能力受环境变量严格门控# 推荐在 shell profile 中导出 token 环境变量避免在 JSON 中硬编码密钥 export HOOKS_TOKENyour-openclaw-hooks-token # OpenClaw 分发管线必需 export OMX_OPENCLAW1 # 命令网关command gateway额外必需 export OMX_OPENCLAW_COMMAND1 # 命令网关超时毫秒的可选全局默认值 # 优先级网关级 timeout 环境变量覆盖 5000ms 默认值 export OMX_OPENCLAW_COMMAND_TIMEOUT_MS120000从源码看OMX_OPENCLAW ! 1时配置读取直接返回 null见 src/openclaw/config.ts 的激活门命令网关还额外要求OMX_OPENCLAW_COMMAND1否则wakeCommandGateway会返回 Command gateway disabled见 src/openclaw/dispatcher.ts。这是两条独立的开关务必同时确认。对应测试可参考 src/openclaw/tests/config.test.ts。二、提示词模板的五个编辑位置OpenClaw 集成中最重要的质量杠杆是 hook 的instruction模板位于以下五个键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这五个事件与源码中OpenClawHookEvent联合类型一一对应见 src/openclaw/types.ts。每个事件映射OpenClawHookMapping由gateway、instruction、enabled三个字段构成src/openclaw/types.ts其中enabled: false或映射缺失都会导致事件被resolveGateway静默跳过src/openclaw/config.ts。在通知分发侧notifyLifecycle会把 OmX 的NotificationEvent映射为 OpenClaw hook 事件session-stop映射为stop见 src/notifications/index.ts随后构造白名单化上下文并调用wakeOpenClawsrc/notifications/index.ts。注意其中ask-user-question走前台 hook 路径并await等待投递完成以保证后续回答路由仍附着于当前会话其余事件则 fire-and-forget避免拖慢通知返回。三、推荐上下文 TokenTraceability 与 Follow-up 的基础模板中可以嵌入上下文 token插值由interpolateInstruction完成src/openclaw/dispatcher.ts未解析的变量会被替换为空字符串。推荐用法常时包含Always includeToken用途{{sessionId}}跨日志cross-log的可追溯标识{{tmuxSession}}直接定位 tmux 会话便于 follow-up 操作事件相关Include when relevantToken适用事件{{projectName}}通用由projectPath的 basename 派生{{question}}ask-user-question{{reason}}session-end完整的模板变量集合源码注释中列举还包括{{projectPath}}、{{prompt}}、{{contextSummary}}、{{timestamp}}、{{event}}、{{instruction}}供命令网关二次插值以及{{replyChannel}}、{{replyTarget}}、{{replyThread}}来自OPENCLAW_REPLY_CHANNEL/OPENCLAW_REPLY_TARGET/OPENCLAW_REPLY_THREAD环境变量用于回程路由。变量在 src/openclaw/index.ts 中统一构建tmuxSession若未显式传入会自动探测当前 tmux 会话src/openclaw/index.ts。一个值得注意的安全设计上下文对象经过buildWhitelistedContext显式枚举过滤src/openclaw/index.ts只保留已知字段防止敏感数据意外泄漏到网关 payload。四、结构化 instruction 格式让 Agent 高效解析对于生产部署推荐使用 clawdbot 类 Agent 能够高效解析的结构化格式[event|exec] project{{projectName}} session{{sessionId}} tmux{{tmuxSession}} 필드1: 값 필드2: 값其中[event|exec]前缀表示这是一个可执行 hook需要 Agent 采取行动第一行携带项目、会话、tmux 三层上下文标识后续字段以필드: 값韩语 字段: 值形式组织例如요약摘要、우선순위优先级、주의사항注意事项、성과成果、검증验证、다음下一步。以韩语为主要工作语言的开发团队使用这些固定韩语字段名可以保证跨会话、跨 Agent 的结构一致性。五个事件的推荐模板骨架来自 openclaw-integration.md 的 executive-summary profile[session-start|exec] project{{projectName}} session{{sessionId}} tmux{{tmuxSession}} 요약: 시작 맥락 1문장 우선순위: 지금 할 일 1~2개 주의사항: 리스크/의존성(없으면 없음) [session-idle|exec] session{{sessionId}} tmux{{tmuxSession}} 요약: idle 원인 1문장 복구계획: 즉시 조치 1~2개 의사결정: 사용자 입력 필요 여부 [ask-user-question|exec] session{{sessionId}} tmux{{tmuxSession}} question{{question}} 핵심질문: 필요한 답변 1문장 영향: 미응답 시 영향 1문장 권장응답: 가장 빠른 답변 형태 [session-stop|exec] session{{sessionId}} tmux{{tmuxSession}} 요약: 중단 사유 현재상태: 저장/미완료 항목 재개: 첫 액션 1개 [session-end|exec] project{{projectName}} session{{sessionId}} tmux{{tmuxSession}} reason{{reason}} 성과: 완료 결과 1~2문장 검증: 확인/테스트 결과 다음: 후속 액션 1~2개Dev 场景强制韩语输出的 follow-up 模式当#omc-dev频道需要 OpenClaw 通知以真实 clawdbot agent turn形式出现并主动 follow-up 时所有 hook instruction 用韩语编写并在模板中显式要求韩语输出例如OMX 훅{{event}} 프로젝트{{projectName}} 세션{{sessionId}}. 반드시 한국어로 응답하세요. OMX tmux 세션: {{tmuxSession}}. SOUL.md 및 #omc-dev 맥락을 참고해 필요한 후속 액션이 있으면 즉시 안내하세요.每条 hook 消息都包含{{sessionId}}与{{tmuxSession}}tmux 会话存在时以它作为首选 follow-up 目标缺失时再从sessionId与当前项目路径推导候选会话。快速排查命令tmux ls | grep ^omx- || true tmux list-panes -a -F #{session_name}\t#{pane_id}\t#{pane_current_path} | grep $(basename $PWD) || truefollow-up runbookhook 提示存在待办或待用户操作时——读取SOUL.md与近期#omc-dev上下文用韩语 follow-up 并引用sessionIdtmuxSession需要行动时给出具体下一步需要回复 / 需要重试 / 需要检查会话投递异常时检查日志并去掉输出吞掉重试。五、详细度verbosity策略notifications.verbosity控制通知文本的整体详略OpenClaw 场景下三个档位档位语义适用场景minimal极短通知高信号、低叙述仅提示事件发生session简洁的运维上下文推荐默认日常开发通知verbose状态 行动 风险完整展开需要快速浏览但信息完整的管理简报调优时建议将verbosity与结构化 instruction 配合使用verbose提供更丰富的现场信息而结构化模板保证这些信息可被 Agent 快速解析。六、快速更新命令一条 jq 覆盖五个模板下面是官方推荐的 jq 一键更新命令。它会同时把verbosity设为verbose并为五个 hook 事件写入结构化韩语模板来自 openclaw-integration.ja.md 原文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说明先写临时文件再mv原子替换避免 jq 写坏原文件配置读取路径默认是~/.codex/.omx-config.jsoncodexHome()推导见 src/openclaw/config.ts也可用OMX_OPENCLAW_CONFIG指向独立配置文件配置首次读取后会被缓存进程生命周期内环境变量不变调试时注意重启相关进程或调用resetOpenClawConfigCache。七、两种网关形态与配置示例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 网关的关键约束URL 必须是 HTTPSlocalhost、127.0.0.1、::1除外否则validateGatewayUrl直接拒绝src/openclaw/dispatcher.ts对应测试见 src/openclaw/tests/dispatcher.test.ts。HTTP 网关默认超时 10 秒可通过gateway.timeout覆盖。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}} } } }这些别名由normalizeFromCustomAliases归一化为内部 OpenClaw 网关映射src/openclaw/config.tswebhook 别名归一化为custom-webhookHTTP 网关CLI 别名归一化为custom-cli命令网关events缺省时默认取session-end与ask-user-questionsrc/openclaw/config.ts。Option CClawdbot agent-command 工作流开发环境推荐当希望 hook 事件触发agent turn而非普通消息/webhook 转发时使用命令网关{ notifications: { enabled: true, verbosity: verbose, 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개 } } } } }命令网关的生产最佳实践完整文档见 docs/openclaw-integration.md命令末尾追加|| true防止 clawdbot 失败阻塞 OmX hook使用.jsonl扩展名 追加实现结构化日志聚合Discord 投递优先使用--reply-to channel:CHANNEL_ID格式channel alias 在机器人未缓存频道时可能失败命令网关超时优先级gateways.name.timeoutOMX_OPENCLAW_COMMAND_TIMEOUT_MS 默认 5000msclawdbot agent 工作流建议 120000ms2 分钟。Shell 安全提醒模板变量如{{instruction}}会被插值进命令字符串。命令网关对每个变量做单引号包裹式 shell 转义shellEscapeArgsrc/openclaw/dispatcher.ts且优先走直接 argv 执行仅当命令含 shell 元字符|;$()等时才回退到sh -csrc/openclaw/dispatcher.ts。尽管如此仍应保持模板简单并避免在用户派生的内容中出现 shell 元字符。八、优先级契约显式配置胜出当显式notifications.openclaw与通用别名同时存在时行为是确定性的backward compatiblenotifications.openclaw胜出custom_webhook_command/custom_cli_command被忽略OMX 会输出一条警告以提示。源码中的判定逻辑在 src/openclaw/config.tsnotifications.openclaw有效时直接返回并console.warn忽略别名。inspectOpenClawConfig还提供explicitOverridesAliases、configSource等诊断字段用于排查当前配置实际来源env-override / notifications.openclaw / custom-aliases对应测试见 src/openclaw/tests/config.test.ts。九、底层实现模板插值、超时钳制与进程树清理调优提示词时理解底层机制有助于预判行为模板插值interpolateInstruction用正则\{\{(\w)\}\}替换变量未解析变量替换为空串src/openclaw/dispatcher.ts。这意味着拼写错误的 token 不会报错而是静默消失——这是调优时最常见的字段莫名缺失根因。超时钳制resolveCommandTimeoutMs按网关级 环境变量 5000ms 默认解析并钳制在 100ms300000ms5 分钟安全区间内src/openclaw/dispatcher.ts防止近零超时或失控长进程。测试覆盖见 src/openclaw/tests/dispatcher.test.ts。进程树清理命令网关通过runProcessTreeWithTimeout以进程组方式运行超时或父进程退出时会清理 shell 包装器及其子孙进程避免 bash 进程泄漏测试用例专门验证孙进程被回收见 src/openclaw/tests/dispatcher.test.ts。失败吞没所有 OpenClaw 调用失败都被捕获吞掉绝不阻塞 hook 主流程src/openclaw/index.ts。调试时可设OMX_OPENCLAW_DEBUG1查看逐事件分发日志。十、验证与排障模板改完后务必做投递验证完整验证章节见 docs/openclaw-integration.md# 前置检查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_COMMAND1 # Wake 冒烟测试/hooks/wake期望 JSON 含 ok:true curl -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} # 投递验证/hooks/agent期望 HTTP 2xx curl -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}常见故障诊断速查现象处置401/403bearer token 无效或缺失404路径错误核对/hooks/agent与/hooks/wake5xx网关运行时问题检查日志超时 / connection refusedhost/port/firewall 问题命令网关被禁用同时设置OMX_OPENCLAW1与OMX_OPENCLAW_COMMAND1命令被SIGTERM杀掉增大gateways.name.timeoutclawdbot agent 建议 120000或设OMX_OPENCLAW_COMMAND_TIMEOUT_MShook 失败阻塞会话命令末尾追加|| true日志缺失使用.jsonl扩展名 追加持久化结构化日志Discord 投递失败改用--reply-to channel:CHANNEL_ID而非 channel alias日志排查示例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延伸阅读完整集成指南gateway / hooks / 验证流程全量版docs/openclaw-integration.md其他语言版本简体中文 · 繁體中文 · 한국어 · 日本語 · English · Español · DeutschOpenClaw 模块源码src/openclaw/types.ts配置类型与 payload 结构· src/openclaw/config.ts配置读取与别名归一化· src/openclaw/dispatcher.tsHTTP/命令网关分发· src/openclaw/index.tswakeOpenClaw公共入口通知分发上游src/notifications/index.tsnotifyLifecycle→wakeOpenClaw调用链测试用例src/openclaw/tests/config.test.ts · src/openclaw/tests/dispatcher.test.ts · src/openclaw/tests/index.test.ts【免费下载链接】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），仅供参考