企业官网建设流程全解析

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 Gates）

OpenClaw 分派管道受环境变量门控保护，避免未配置的用户误触发：

# 建议在 shell profile 中导出 token 环境变量（避免把密钥硬编码进 JSON）： export HOOKS_TOKEN="your-openclaw-hooks-token" # OpenClaw 分派管道的必需开关 export OMX_OPENCLAW=1 # 命令类网关（type: "command"）额外需要此开关 export OMX_OPENCLAW_COMMAND=1 # 可选：命令网关的全局默认超时（毫秒） # 优先级：gateway timeout > 环境变量覆盖 > 默认 5000ms export OMX_OPENCLAW_COMMAND_TIMEOUT_MS=120000

从源码看，这些门控并非纸面约定：

• src/openclaw/config.ts 中getOpenClawConfig()首先检查process.env.OMX_OPENCLAW !== "1"则直接返回null，即不开OMX_OPENCLAW=1时整个 OpenClaw 配置链直接短路；
• src/openclaw/dispatcher.ts 中wakeCommandGateway()单独校验OMX_OPENCLAW_COMMAND === "1"，否则返回"Command gateway disabled"错误。这解释了为什么命令网关需要两个开关同时打开。

超时优先级在 src/openclaw/dispatcher.ts 的resolveCommandTimeoutMs()中实现：gatewayConfig.timeout>OMX_OPENCLAW_COMMAND_TIMEOUT_MS> 默认5000，并且会被钳制在100ms（MIN_COMMAND_TIMEOUT_MS）到300000ms（MAX_COMMAND_TIMEOUT_MS）的安全区间内——所以即使把120000写成999999也只会被钳到 5 分钟。

三、instruction 模板在哪里编辑

五个 hook 事件各自对应一个 instruction 模板键，全部位于~/.codex/.omx-config.json的notifications块下：

• notifications.openclaw.hooks["session-start"].instruction
• notifications.openclaw.hooks["session-idle"].instruction
• notifications.openclaw.hooks["ask-user-question"].instruction
• notifications.openclaw.hooks["stop"].instruction
• notifications.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}}占位符。文档建议：

必须包含（Always）：

按事件相关性包含（Event-dependent）：

源码中实际支持的变量集合比文档列出的更完整。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）；
• 后续行以"字段名: 值"的形式给出可扫描的结构化摘要。示例模板中的韩文字段名（요약、우선순위、주의사항、성과、검증、다음）为以韩语为主语言的开发团队提供一致的结构约定，你可以按自己团队的语言习惯替换字段名，但建议保持"字段: 值"的扁平结构不变。

六、详细度策略（Verbosity）

notifications.verbosity控制通知的整体详细程度，文档给出的三档策略：

• minimal：极短信号（高信噪比，少叙述）
• session：推荐默认，紧凑的运维上下文
• verbose：更丰富的状态 + 行动 + 风险描述

从源码看，omx 实际支持四档：src/notifications/config.ts 定义VALID_VERBOSITY_LEVELS = ["verbose", "agent", "session", "minimal"]，秩序为minimal(0) < session(1) < agent(2) < verbose(3)，且默认值是session（DEFAULT_VERBOSITY）。verbosity 不只是"文案长短"，它还参与事件门控——EVENT_MIN_VERBOSITY表规定了各事件的最低详细度要求：

const EVENT_MIN_VERBOSITY: Record<NotificationEvent, 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-summary）verbose 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 配置和通用别名同时存在时，行为契约是：

1. notifications.openclaw胜出；
2. custom_webhook_command/custom_cli_command被忽略；
3. OMX 会打印告警以保持行为透明。

从源码看，该契约在 src/openclaw/config.ts 中有两处落地：getOpenClawConfig()在显式配置有效且别名也存在时console.warn提示 "notifications.openclaw is set; ignoring custom_cli_command/custom_webhook_command aliases"；inspectOpenClawConfig()则返回结构化的检查状态（configured/disabled/missing-config/invalid-config/not-configured），其中explicitOverridesAliases与warnings字段供 doctor 类诊断命令消费。配置读取还有第三个入口：OMX_OPENCLAW_CONFIG环境变量指向一个独立的配置文件（整个文件即OpenClawConfig，需满足enabled + gateways + hooks有效性校验），且读取结果在进程生命周期内被缓存（_cachedConfig），测试中可用resetOpenClawConfigCache()重置。

配置读取的完整优先级为：

1. OMX_OPENCLAW_CONFIG指向的独立文件（如设置）；
2. ~/.codex/.omx-config.json中的notifications.openclaw；
3. notifications.custom_cli_command/notifications.custom_webhook_command别名（归一化为内部 OpenClaw 运行时配置）。

十、三种网关配置路径

Option A：显式notifications.openclaw（HTTP 网关）

{ "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 的OpenClawHttpGatewayConfig）：url必填；headers可选自定义请求头；method默认POST（仅允许POST/PUT，别名归一化时其他值一律按 POST 处理）；timeout为每请求超时毫秒数，HTTP 网关默认 10000ms（DEFAULT_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_EVENTS）；instruction缺省为"OMX event {{event}} for {{projectPath}}"。

Option C：Clawdbot 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 2>&1 || 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 设为120000（2 分钟）：避免过早超时。

十一、开发指南：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")" || true

3) SOUL.md + #omc-dev 跟进 runbook：当 hook 提示存在活跃工作或待用户操作时——(1) 阅读SOUL.md与近期#omc-dev上下文；(2) 用韩语跟进并引用sessionId+tmuxSession；(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/wake）：

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"}'

通过信号：响应 JSON 包含"ok":true。

B) 投递验证（/hooks/agent）：

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"}'

通过信号：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_OPENCLAW=1" || echo "missing OMX_OPENCLAW=1" test "$OMX_OPENCLAW_COMMAND" = "1" && echo "OMX_OPENCLAW_COMMAND=1" || echo "missing OMX_OPENCLAW_COMMAND=1"

Pass/Fail 诊断表：

从源码结构看，"失败被吞掉"是设计目标而非缺陷：src/openclaw/index.ts 的模块注释明确写着 "All calls are non-blocking with timeouts. Failures are swallowed to avoid blocking hooks"，且wakeOpenClaw()的 catch 分支只在不启用调试日志（OMX_OPENCLAW_DEBUG=1）时静默返回null——排查投递问题时开OMX_OPENCLAW_DEBUG=1可在 stderr 看到每次 wake 的ok / error摘要。

十四、小结

• 调优主杠杆：notifications.openclaw.hooks[<event>].instruction，五事件各自独立；采用[event|exec]结构化格式 + 强制上下文 Token（{{sessionId}}/{{tmuxSession}}必带）；
• 详细度：verbosity四档（源码实现），默认session；ask-user-question需要agent及以上才会放行；
• 安全门控：OMX_OPENCLAW=1全局、OMX_OPENCLAW_COMMAND=1命令网关、超时钳制 100ms~300s、HTTP 强制 HTTPS（localhost 例外）、命令变量 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