首页
/ OmX OpenClaw 通知网关集成指南：从 prompt 模板调优到 clawdbot 生产级命令网关配置

OmX OpenClaw 通知网关集成指南：从 prompt 模板调优到 clawdbot 生产级命令网关配置

2026-09-09 13:15:04作者：谭伦延
oh-my-codex
OmX - 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

本文以 docs/openclaw-integration.ko.md 的 "Prompt tuning guide (concise + context-aware)" 章节为骨架，结合 OmX（Oh My codeX）仓库中 src/openclaw/ 的源码实现与测试用例展开。更完整的网关/钩子/验证全景文档见 English guide。

导读：OmX 通过 notifications.openclaw 配置，把会话生命周期事件（session-start / session-idle / ask-user-question / stop / session-end）以指令（instruction）模板的形式投递给 OpenClaw 网关，从而驱动 clawdbot 等 agent 主动跟进开发任务。本文聚焦"简洁 + 上下文感知"的 prompt 调优：如何改写 5 个 hook 的 instruction 模板、如何选用上下文 token 与 verbosity 级别、如何落地 clawdbot agent 命令网关的生产配置，并深入 src/openclaw/ 源码，讲清激活门、模板插值、shell 安全与超时优先级等底层原理。读完你就能直接在 ~/.codex/.omx-config.json 中复刻一套可运行、可排障的 OpenClaw 集成配置。

一、为什么 prompt 模板是 OpenClaw 集成的质量杠杆

对于 OpenClaw 集成而言，最关键的调优点就是 hook 的 instruction 模板。它不是简单的一句话转发文本，而是会被投递给远端 agent（如 clawdbot）并驱动其行动的指令。指令越简洁、上下文越明确，agent 的响应越精准、越少发散。

在 OmX 的配置模型中，模板统一挂载在以下 5 个键下（这也是韩国语/中文等多语言团队最常改动的区域）：

  • 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

这 5 个事件在源码中被枚举为合法的 hook 事件集合，见 src/openclaw/config.ts 与 src/openclaw/types.ts：

const VALID_HOOK_EVENTS: OpenClawHookEvent[] = [
  "session-start",
  "session-end",
  "session-idle",
  "ask-user-question",
  "stop",
];

从源码结构看，pre-tool-use、post-tool-use、keyword-detector 等 OMC 专属事件被刻意排除（src/openclaw/types.ts 的注释说明了原因：Codex CLI 原生不支持这些事件）。

二、推荐上下文 token：让每条通知自带可追踪坐标

为了让远端 agent 能精准定位会话、定向操作 tmux，模板中应注入以下 token（由 OmX 在投递前完成插值）：

Token 时机 用途
{{sessionId}} 始终包含 跨日志追踪，关联 OMX 会话
{{tmuxSession}} 始终包含 直接定位并跟进 tmux 会话
{{projectName}} 相关时包含 标明项目（目录 basename）
{{question}} ask-user-question 时 携带待回答的问题文本
{{reason}} session-end 时 携带结束原因

除上述外，src/openclaw/dispatcher.ts 的注释还列出了 {{projectPath}}、{{prompt}}、{{contextSummary}}、{{timestamp}}、{{event}}、{{instruction}}、{{replyChannel}} / {{replyTarget}} / {{replyThread}} 等变量。插值实现 interpolateInstruction 用正则 /\{\{(\w+)\}\}/g 匹配占位符，未解析的变量会被替换为空字符串（src/openclaw/dispatcher.ts），因此漏传的 token 不会导致投递失败，但会丢失上下文——这正是文档强调"始终包含 sessionId / tmuxSession"的原因。

结构化指令格式（[event|exec] 前缀）

生产环境建议使用 clawdbot 易于解析的结构化格式：

[event|exec]
project={{projectName}} session={{sessionId}} tmux={{tmuxSession}}
필드1: 값
필드2: 값
  • [event|exec] 前缀表明这是一个需要 agent 采取行动的可执行 hook；
  • 后续字段名可使用团队主要语言（韩文团队常用 요약、우선순위、주의사항、성과、검증、다음）提供统一结构，便于 agent 稳定提取字段。

三、verbosity 策略：三种档位怎么选

级别 行为 适用场景
minimal 极短通知，高信噪比 只想收到"发生了什么"的轻量提醒
session 简洁的操作上下文 推荐默认，覆盖 start/idle/stop/end 及 tmux tail
verbose 扩展到状态 + 动作 + 风险 需要 agent 输出更丰富叙事时

在 src/notifications/types.ts 中，verbosity 实际枚举为 "verbose" | "agent" | "session" | "minimal"，其中 session 是默认档位（同文件 L135 注释说明默认值为 "session"），并注明：

  • verbose：包含全部文本/工具调用输出；
  • session：start/idle/stop/end + tmux tail 片段（默认）；
  • minimal：仅 start/stop/end，不含 idle 与 tmux tail。

生产级的 executive-summary verbose 档位完整配置如下（可直接放入 notifications 块）：

{
  "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개"
        }
      }
    }
  }
}

注意：模板中的 \n 在 JSON 中就是真实换行；每个字段只要求 1～2 句，约束 agent 输出密度，避免长篇大论淹没关键信息。

四、生产配置最佳实践：clawdbot 命令网关

当目标是触发 agent 轮次（而非普通消息/Webhook 转发）时，使用 type: "command" 的命令网关，让 clawdbot agent 真正"跑一轮"。文档推荐的配置如下：

{
  "notifications": {
    "openclaw": {
      "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
        }
      }
    }
  }
}

关键设置说明（务必逐条理解）：

  • || true：clawdbot 失败时不让 OMX 会话被阻塞——hook 投递失败不应拖垮开发主流程；
  • >>/tmp/omx-openclaw-agent.jsonl：以 append 模式写结构化 JSONL 日志，便于长期聚合与分析（不要用 > 覆盖，否则历史丢失）；
  • --reply-to 'channel:CHANNEL_ID'：用频道 ID 而非频道别名（如 #omc-dev），确保 Discord 投递稳定——别名在 bot 未缓存频道时可能失败；
  • timeout: 120000：2 分钟超时，给 clawdbot agent 完成一轮思考 + 投递留足时间。

命令网关超时优先级（重要）

命令网关超时的解析优先级在源码 src/openclaw/dispatcher.ts 中实现：

gateways.<name>.timeout > OMX_OPENCLAW_COMMAND_TIMEOUT_MS > 默认 5000ms

并且运行时会 clamp 到安全区间 [100ms, 300000ms]（MIN_COMMAND_TIMEOUT_MS = 100，MAX_COMMAND_TIMEOUT_MS = 300_000，见 src/openclaw/dispatcher.ts），防止接近 0 的误配置和失控的长驻进程。对于 clawdbot agent 工作流，务必使用 120000（2 分钟），否则可能被默认 5 秒超时提前杀死。

启用所需的环境变量（激活门）

在 shell profile 中导出（避免把密钥写死在 JSON 里）：

# 优先用环境变量导出 token（不要在 JSON 中硬编码密钥）
export HOOKS_TOKEN="your-openclaw-hooks-token"

# OpenClaw 投递管道必需
export OMX_OPENCLAW=1

# 命令网关额外必需
export OMX_OPENCLAW_COMMAND=1

# 可选的命令网关全局默认超时（毫秒）
# 优先级：gateway timeout > env 覆盖 > 5000 默认
export OMX_OPENCLAW_COMMAND_TIMEOUT_MS=120000

源码层面，getOpenClawConfig() 的第一道闸就是 process.env.OMX_OPENCLAW !== "1" 时直接返回 null（src/openclaw/config.ts）；wakeCommandGateway() 在 OMX_OPENCLAW_COMMAND !== "1" 时返回失败结果 "Command gateway disabled"（src/openclaw/dispatcher.ts）。两道独立闸门的设计意图很明确：HTTP 投递与命令执行的安全边界是分开的。

五、查看与排障：JSONL 日志命令

# 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

六、快速更新模板：一条 jq 命令完成 5 个 hook 改写

不想手写整段 JSON？用下面这条 jq 命令一次性更新 $HOME/.codex/.omx-config.json（注意 shell 中 \n 需写作 \\n）：

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 失败时破坏原配置。

七、源码级原理：OmX 的 OpenClaw 投递链路

从 src/openclaw/index.ts 的 wakeOpenClaw() 入口，可以看到完整链路：

  1. 读配置：getOpenClawConfig() 依次尝试 OMX_OPENCLAW_CONFIG 独立文件 → notifications.openclaw → custom_cli_command / custom_webhook_command 别名归一化（src/openclaw/config.ts），首次读取后缓存；
  2. 解析映射：resolveGateway() 按事件查 hooks 映射，校验网关存在性与类型必填字段（src/openclaw/config.ts）；
  3. 构造上下文：仅白名单字段会被带入模板（src/openclaw/index.ts），防止敏感数据泄漏到网关 payload——这一点在 src/openclaw/types.ts 中通过显式枚举字段、无索引签名的方式在类型层面强制保证；
  4. 模板插值：interpolateInstruction() 展开 {{var}}，未解析变量置空；若未显式提供 tmuxSession，会自动探测当前 tmux 会话（getCurrentTmuxSession()）；
  5. 投递：HTTP 网关走 wakeGateway()（校验 URL 必须 HTTPS，仅 localhost/127.0.0.1/::1 允许 HTTP，见 src/openclaw/dispatcher.ts）；命令网关走 wakeCommandGateway()。

Shell 安全设计（值得单独强调）

命令网关把 {{instruction}} 等变量插值进命令字符串时，所有变量值会先经 shellEscapeArg() 单引号包裹转义（src/openclaw/dispatcher.ts），防止注入。执行方式按是否含 shell 元字符（/[\|&;><$()]/`）二选一：

  • 无元字符：直接用 argv 方式执行（execFile 语义），避免不必要的 shell 解释；
  • 有元字符：才回退到 sh -c，且经 src/runtime/process-tree.ts 以进程组方式运行，超时/父进程退出时能级联清理 shell 包装器与后代进程（SIGTERM 后 1 秒宽限再 SIGKILL）。

给配置者的实操提醒：文档与源码注释都强调——模板变量会被插值进命令串，请保持模板简单，避免在用户衍生内容中出现 shell 元字符。

八、验证与排障速查

生产接入后，先用最小烟测确认管道通畅：

# 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"

常见失败信号与对策：

现象 原因与对策
401/403 Bearer token 缺失/无效，检查 HOOKS_TOKEN
404 路径写错，核对 /hooks/agent 与 /hooks/wake
5xx 网关运行期故障，查 JSONL 日志
超时 / connection refused 主机/端口/防火墙问题
命令网关被禁用 同时设置 OMX_OPENCLAW=1 与 OMX_OPENCLAW_COMMAND=1
命令被 SIGTERM 杀死 提高 gateways.<name>.timeout（clawdbot 建议 120000）或设置 OMX_OPENCLAW_COMMAND_TIMEOUT_MS
hook 失败阻塞会话 命令末尾补 || true
日志缺失 用 .jsonl 扩展名 + >> 追加写入
Discord 投递失败 用 --reply-to 'channel:CHANNEL_ID' 替代频道别名

以上配置行为均有仓库测试佐证，例如 src/openclaw/tests/config.test.ts 覆盖了：未设置 OMX_OPENCLAW 时返回 null、OMX_OPENCLAW_CONFIG 独立文件加载、enabled: false / 非法 JSON 返回 null、resolveGateway 对未映射/禁用/缺 url 网关的判定，以及显式 notifications.openclaw 覆盖通用别名（explicitOverridesAliases）的归一化逻辑。

九、相关文档与源码入口

oh-my-codex
OmX - 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
登录后查看全文

相关内容推荐

1 OmX OpenClaw 集成指南：面向 Agent 的上下文感知 Prompt 调优实战2 OmX 集成 OpenClaw 通知网关：Hook Prompt 调优指南（简洁 + 上下文感知）3 OmX OpenClaw 集成指南：hook instruction 提示词调优与上下文感知通知实战4 OmX OpenClaw 集成提示词调优指南：基于 hook instruction 模板的上下文感知通知管线5 OmX OpenClaw 集成指南：通过 HTTP 网关与 Clawdbot Agent 命令网关打通 Codex Hook 通知链路6 OmX OpenClaw 集成提示调优指南：基于 hook 指令模板实现简洁、上下文感知的通知网关7 omx (oh-my-codex) OpenClaw 集成指南：Hook instruction 提示词模板调优与网关分发实战8 OmX OpenClaw 集成指南：Hook 提示词模板调优与上下文感知通知配置实战9 OmX (oh-my-codex) 集成 OpenClaw：简明且上下文感知的 Hook 指令（Prompt）调优指南10 OmX (oh-my-codex) OpenClaw 集成指南：hook instruction 模板的简洁化与上下文感知调优
热门项目推荐
相关项目推荐

热门内容推荐

1 编程实践项目探索指南：从零构建技术能力体系2 技术解构式学习：从0到1构建你的编程知识体系3 构建自己的技术世界：build-your-own-x项目的实践探索指南4 解锁编程技能的实践之旅：从零构建你的技术世界5 技术实践探索：从零开始构建核心系统的实践指南6 亲手锻造技术引擎：从0到1构建核心系统的实践指南

最新内容推荐

Reflex 图表坐标轴完全指南：使用 rx.recharts 的 XAxis、YAxis 与 ZAxis 打造精准可视化buzz 基准测试实战：user-mention 任务如何用事件级 `p` 标签守卫生成式 Agent 的通知契约使用 Haystack 与 Astra DB：AstraDocumentStore 与 AstraEmbeddingRetriever 完整实战指南openai-agents-python 语音输入全解析：AudioInput 与 StreamedAudioInput 的使用与底层原理self-llm 开源项目贡献实战：GitHub 提 Issue 与提交 PR 全流程指南Ente Photos Android APK 签名验证指南：核对官方证书指纹与 apksigner 使用详解无法访问 GitHub 的机器上 OpenVoice Silero VAD 模型下载失败怎么解决？ToolJet 移动端布局（Mobile Layout）完全指南：从布局切换到组件适配LeetCode-Go 题解：733. Flood Fill 洪水填充——标准 Flood Fill 算法的 DFS 实现与逐行剖析可口可乐损益表实战：用 Excel 公式与 AVERAGE 函数计算毛利（Data-Science-For-Beginners 第 6 课作业解析）

项目优选

收起
ops-transformerops-transformer
本项目是CANN提供的transformer类大模型算子库，实现网络在NPU上加速计算。
C++
1.16 K
2.78 K
kernelkernel
deepin linux kernel
C
34
18
docsdocs
暂无描述
Markdown
904
5.83 K
ops-nnops-nn
本项目是CANN提供的神经网络类计算算子库，实现网络在NPU上加速计算。
C++
932
1.86 K
pytorchpytorch
作为 Ascend for PyTorch 社区的核心组件，TorchNPU 是昇腾专为 PyTorch 打造的深度学习适配插件，使 PyTorch 框架能够直接调用昇腾 NPU，为开发者提供昇腾 AI 处理器的超强算力。
Python
862
1.36 K
jiuwenswarmjiuwenswarm
JiuwenSwarm 是一款基于openJiuwen开发的智能AI Agent，它能够将大语言模型的强大能力，通过你日常使用的各类通讯应用，直接延伸至你的指尖。
Python
3.95 K
1.03 K
ops-mathops-math
本项目是CANN提供的数学类基础计算算子库，实现网络在NPU上加速计算。
C++
1.38 K
1.47 K
kernelkernel
openEuler内核是openEuler操作系统的核心，既是系统性能与稳定性的基石，也是连接处理器、设备与服务的桥梁。
C
535
606
AscendNPU-IRAscendNPU-IR
AscendNPU-IR是基于MLIR（Multi-Level Intermediate Representation）构建的，面向昇腾亲和算子编译时使用的中间表示，提供昇腾完备表达能力，通过编译优化提升昇腾AI处理器计算效率，支持通过生态框架使能昇腾AI处理器与深度调优
C++
549
398
leetcodeleetcode
🔥LeetCode solutions in any programming language | 多种编程语言实现 LeetCode、《剑指 Offer（第 2 版）》、《程序员面试金典（第 6 版）》题解
Markdown
77
23