首页
/ OmX（oh-my-codex）Discord 集成实战：Webhook 与 Bot Token 的选型、配置与回复监听

OmX（oh-my-codex）Discord 集成实战：Webhook 与 Bot Token 的选型、配置与回复监听

2026-09-09 11:13:42作者：昌雅子Ethen
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

导读：本指南围绕 OmX（oh-my-codex）的 Discord 通知体系展开，完整说明两条彼此独立的 Discord 通知通道——入站 Webhook URL 与 Discord Bot Token——的适用场景、创建步骤、最小权限与配置文件写法。读完本文，你将掌握在 .omx-config.json 或环境变量中配置 Webhook 单向通知、Bot 双向回复监听（status 会话状态查询）以及混合模式（Hybrid）的具体方法，并能依据仓库源码理解每条配置项背后的生效逻辑与常见故障根因。

两个 Discord 概念，两条独立的 OMX 配置通道

Discord 本身提供两种截然不同的集成身份，OMX 为它们分别设计了独立的配置键，互不混用：

  • Incoming Webhook URL：一个 HTTPS 端点，只负责向单个频道推送出站通知。它不需要以 Discord Bot 用户身份登录，配置简单、作用域限定在频道内。
  • Bot Token：Discord Developer Portal 中某个应用/机器人持有的密钥。通过它，OMX 可以调用 Discord Bot API 完成"以 Bot 身份发送"以及需要读取频道消息、做消息关联的**回复/状态（reply/status）**工作流。

从类型定义可以确认这两条通道在 OMX 中是完全独立的第一方平台：NotificationPlatform 将 discord（Webhook）与 discord-bot（Bot）并列，并分别定义了 DiscordNotificationConfig（webhookUrl） 与 DiscordBotNotificationConfig（botToken + channelId） 两种结构。

无论使用哪种凭据，都必须保持私密：不要在公开 issue、日志、截图或共享配置中粘贴 Webhook URL 或 Bot Token。

我应该用哪种凭据？

OMX 模式 / 目标 需要的 Discord 凭据 OMX 配置平台键 常用环境变量
仅 Webhook 出站通知 一个 Incoming Webhook URL notifications.discord OMX_DISCORD_WEBHOOK_URL
仅 Bot 出站通知 Bot Token + 目标频道 ID notifications["discord-bot"] OMX_DISCORD_NOTIFIER_BOT_TOKEN、OMX_DISCORD_NOTIFIER_CHANNEL
回复监听 / 对被跟踪 OMX 通知的 status 回复 Bot Token + 目标频道 ID + 被授权的 Discord 用户 ID，并开启回复 notifications["discord-bot"] 加 notifications.reply OMX_DISCORD_NOTIFIER_BOT_TOKEN、OMX_DISCORD_NOTIFIER_CHANNEL、OMX_REPLY_ENABLED、OMX_REPLY_DISCORD_USER_IDS
Webhook + Bot 混合（Hybrid） 一个 Webhook URL、一个 Bot Token、一个目标频道 ID 同时配置 notifications.discord 与 notifications["discord-bot"] 以上 Webhook 与 Bot 的环境变量全部设置

简单选型原则：只需要 OMX 单向推送通知，用 Webhook 就够了；需要 Discord API 能力（Bot 身份投递、回复关联、reply/status 监听）时，再上 Bot 模式。

从源码看，两条通道的开关逻辑是并列的：buildConfigFromEnv 中 Bot 通道要求 OMX_DISCORD_NOTIFIER_BOT_TOKEN 与 OMX_DISCORD_NOTIFIER_CHANNEL 同时存在才会启用，而 Webhook 通道只要 OMX_DISCORD_WEBHOOK_URL 存在即启用（src/notifications/config.ts）；事件派发时 getEnabledPlatforms 会同时检查 discord 与 discord-bot（src/notifications/config.ts）。

为什么混合模式只需要一个 Webhook？

一个 Webhook 本身就是一个完整的、面向单频道的出站投递端点。Bot 是另一个 Discord 身份，它凭 Bot Token 直接调用 Discord API 发送 Bot 消息，并不需要自备 Webhook。因此混合模式下 OMX 只需要：

  1. 一个 Webhook URL，供 Webhook 发送器使用；
  2. 一个 Bot Token + 频道 ID，供 Bot 发送器/监听器使用。

只有当你有意创建第二个 Webhook 身份、投递到另一个频道或需要独立轮换凭据时，才需要创建第二个 Webhook——仅仅因为同时配置了 Bot 模式并不要求第二个 Webhook。

创建 Incoming Webhook URL

  1. 在 Discord 中打开 OMX 要投递的服务器与频道；
  2. 进入服务器设置或频道设置 → Integrations（集成） → Webhooks；
  3. 选择 New Webhook（新建 Webhook），选定目标频道、命名，然后复制 Webhook URL；
  4. 将其保存为 OMX_DISCORD_WEBHOOK_URL，或写入 .omx-config.json 的 notifications.discord.webhookUrl。

Webhook URL 是频道作用域的。如果消息出现在错误的频道，请从目标频道的集成设置中重新创建/复制 Webhook。

创建 Discord Bot Token

  1. 打开 Discord Developer Portal，创建或选择一个应用（Application）；
  2. 为该应用添加一个 Bot；
  3. 在 Bot 页面重置/复制 Bot Token，保存为 OMX_DISCORD_NOTIFIER_BOT_TOKEN，或写入 notifications["discord-bot"].botToken；
  4. 通过 Developer Portal 的 OAuth2 URL 生成器把 Bot 邀请进你的服务器：勾选 bot scope，并且只授予 OMX 需要的权限；
  5. 复制目标频道 ID，保存为 OMX_DISCORD_NOTIFIER_CHANNEL，或写入 notifications["discord-bot"].channelId。在 Discord 中复制 ID 通常需要先开启开发者模式（Developer Mode）。

⚠️ 仅有 Bot Token 是不够的：Bot 还必须被邀请进服务器，并且能够看到/投递到目标频道。

最小 Bot 权限与 Intents

针对出站 Bot 通知，在目标频道授予 Bot：

  • View Channel（查看频道）
  • Send Messages（发送消息）

针对回复/状态工作流，再追加：

  • Read Message History（读取消息历史）
  • Add Reactions（添加表情回应）——如果你希望"✅ 确认已注入"的表情回应能够成功

基础的出站发送不需要特权 Gateway Intents。如果开启的 Bot/回复监听工作流需要读取消息内容，且你的 Discord 应用设置要求，请在 Developer Portal 中为该 Bot 启用 Message Content Intent（消息内容意图）。除非工作流确实需要，否则保持特权 Intents 关闭。

源码侧可以印证"表情回应确认"这条路径：回复成功注入后，pollDiscordOnce 会向 https://discord.com/api/v10/channels/{channel}/messages/{msg.id}/reactions/✅/@me 发起 PUT，失败仅记录 WARN 日志而不影响主流程（src/notifications/reply-listener.ts）。

配置示例：环境变量与 .omx-config.json

推荐将密钥放在环境变量中。下面的 JSON 展示 .omx-config.json 支持的完整形态，但你可以把机密字段从文件中省略，改用环境变量提供。配置文件位于 codex home 目录下的 .omx-config.json（源码通过 join(codexHome(), ".omx-config.json") 定位，见 src/notifications/config.ts）。

仅 Webhook 出站通知

export OMX_DISCORD_WEBHOOK_URL='https://discord.com/api/webhooks/.../...'

{
  "notifications": {
    "enabled": true,
    "discord": {
      "enabled": true,
      "webhookUrl": "https://discord.com/api/webhooks/.../..."
    }
  }
}

仅 Bot 出站通知

export OMX_DISCORD_NOTIFIER_BOT_TOKEN='your-bot-token'
export OMX_DISCORD_NOTIFIER_CHANNEL='123456789012345678'

{
  "notifications": {
    "enabled": true,
    "discord-bot": {
      "enabled": true,
      "botToken": "your-bot-token",
      "channelId": "123456789012345678"
    }
  }
}

Hybrid：Webhook + Bot 且带回复/状态监听

export OMX_DISCORD_WEBHOOK_URL='https://discord.com/api/webhooks/.../...'
export OMX_DISCORD_NOTIFIER_BOT_TOKEN='your-bot-token'
export OMX_DISCORD_NOTIFIER_CHANNEL='123456789012345678'
export OMX_REPLY_ENABLED='true'
export OMX_REPLY_DISCORD_USER_IDS='111111111111111111,222222222222222222'

{
  "notifications": {
    "enabled": true,
    "discord": {
      "enabled": true,
      "webhookUrl": "https://discord.com/api/webhooks/.../..."
    },
    "discord-bot": {
      "enabled": true,
      "botToken": "your-bot-token",
      "channelId": "123456789012345678"
    },
    "reply": {
      "enabled": true,
      "authorizedDiscordUserIds": ["111111111111111111", "222222222222222222"]
    }
  }
}

Webhook 与 Bot 发送均可选配共享 @ 提及：

export OMX_DISCORD_MENTION='<@123456789012345678>'
# 或角色提及，例如 '<@&123456789012345678>'

提及格式在源码中有严格的校验正则：<@!?\d{17,20}>（用户）或 <@&\d{17,20}>（角色），不合法时会被静默丢弃（validateMention）；解析后会被映射为 Discord allowed_mentions 中的 users 或 roles 字段（parseMentionAllowedMentions）。

回复监听（Reply Listener）与 status 状态查询的工作原理

回复监听是 Bot 模式独有的能力：它以后台守护进程（daemon）形式运行，周期性轮询 Discord 频道中回复（message_reference）了已跟踪 OMX 通知的消息，校验发送者身份后，将回复文本经 tmux 注入回正在运行的 Codex CLI 会话。仓库内的实现要点：

  • 守护进程与状态文件：PID、状态与配置分别写入 ~/.omx/state/ 下的 reply-listener.pid、reply-listener-state.json、reply-listener-config.json，所有文件以 0600 权限写入（src/notifications/reply-listener.ts）；启动时为 detached 子进程，并使用白名单裁剪环境变量，避免把不必要的敏感环境泄露给守护进程（src/notifications/reply-listener.ts）。
  • 身份与授权双重校验：只有 authorizedDiscordUserIds 中列出的 Discord 用户 ID（正则 ^\d{17,20}$ 过滤，见 parseDiscordUserIds）的回复才会被处理；注入前还会用 analyzePaneContent 验证目标 tmux pane 确实在运行 Codex CLI（置信度低于 0.4 时拒绝注入并清理过期映射，见 injectReply）。
  • 输入消毒：sanitizeReplyInput 会剔除控制字符与双向文本控制符（bidi override）、把换行折叠为空格，并转义反引号、$()、${} 等 shell 敏感序列后再注入（src/notifications/reply-listener.ts）。
  • 限流与确认：守护进程按分钟限流（默认 10 条/分钟，见 RateLimiter，src/notifications/reply-listener.ts）；注入成功后给回复消息加 ✅ 反应，并以"回复该消息"的形式回发一段截断的最近终端输出摘要（captureReplyAcknowledgementSummary，src/notifications/reply-listener.ts）。
  • status 命令：被授权的操作者在已跟踪通知下精确回复 status 一词（大小写不敏感，见 isDiscordStatusCommand），Bot 会回发有界的只读会话摘要（会话状态、子代理摘要、技能激活状态等，组装逻辑见 src/notifications/session-status.ts）；若该消息没有关联到任何已跟踪会话，则回复 No tracked OMX session is associated with this message.（src/notifications/reply-listener.ts）。

回复监听的调优参数

回复子系统的可调参数集中在 notifications.reply 与对应环境变量中，源码在 getReplyConfig 中完成读取与归一化（越界值会被钳制到合法区间）：

参数 环境变量 默认值 取值范围（源码钳制） 说明
轮询间隔 OMX_REPLY_POLL_INTERVAL_MS 3000 ms 500 – 60000 ms 守护进程每次轮询的间隔
每分钟限流 OMX_REPLY_RATE_LIMIT 10 条/分钟 ≥ 1 每分钟最多处理的回复数
单条回复最大长度 notifications.reply.maxMessageLength 500 字符 1 – 4000 注入前截断长度
注入前缀 OMX_REPLY_INCLUDE_PREFIX true（[reply:discord] ） false 关闭 注入文本前的可视化前缀
授权用户 OMX_REPLY_DISCORD_USER_IDS 空 逗号分隔的 Discord 用户 ID Discord 回复监听的硬性门槛，为空则 Discord 回复直接禁用

对应常量可在 reply-listener.ts 与 config.ts 中核对。

事件、Verbosity 与配置文件位置

Discord 通知只是 OMX 通知子系统的一部分。通知会挂在会话生命周期事件上，类型定义为 session-start、session-stop、session-end、session-idle、ask-user-question（src/notifications/types.ts）。每条事件还可做平台级覆盖（events.<event>.discord / events.<event>["discord-bot"]），未覆盖时继承顶层平台配置（getEffectiveNotificationPlatformConfig）。

Verbosity（通知冗余度） 决定哪些事件值得推送，默认 session（含 start/idle/stop/end 与 tmux tail 片段），优先级为环境变量 OMX_NOTIFY_VERBOSITY > 配置字段 notifications.verbosity > 默认值 session（src/notifications/config.ts）。四档说明：

  • minimal：仅 start/stop/end，无 idle、无 tmux tail；
  • session（推荐）：start/idle/stop/end + tmux tail；
  • agent：在 session 之上加入每次 agent 调用事件（含 ask-user-question）；
  • verbose：全部文本/工具调用输出。

配置文件与旧格式兼容：主配置从 codex home 下的 .omx-config.json 读取（configFile）；同时保留对旧 stopHookCallbacks 格式的自动迁移（migrateStopHookCallbacks）。环境变量配置与文件配置会做合并：文件里缺失的机密字段由环境变量补齐，mention 统一经校验后回填（mergeEnvIntoFileConfig）。还支持通过 notifications.profiles + notifications.defaultProfile（或 OMX_NOTIFY_PROFILE）定义多套命名配置并在运行时切换（resolveProfileConfig）。

常见故障排查（Common Failure Modes）

  • 无效的 Bot Token：在 Developer Portal 重新生成 Token，并更新 OMX_DISCORD_NOTIFIER_BOT_TOKEN / notifications["discord-bot"].botToken。
  • Bot Token 在别处能用、OMX 里却不行：确认 OMX_DISCORD_NOTIFIER_CHANNEL / channelId 是数字形式的频道 ID，而不是频道名或 Webhook ID。
  • Bot 不在服务器里：用 bot 这个 OAuth2 scope 把应用 Bot 邀请进服务器。
  • 频道权限缺失：授予 View Channel 与 Send Messages；回复/状态工作流还需 Read Message History。
  • Webhook 被删除或从错误的频道复制：从目标频道的 Integrations/Webhooks 页面重新创建/复制 Incoming Webhook，并更新 OMX_DISCORD_WEBHOOK_URL / notifications.discord.webhookUrl。
  • 混合模式下出现重复消息：notifications.discord 与 notifications["discord-bot"] 同时启用，两条通道都会发送。若只需要一条 Discord 消息路径，请关闭其中一个。
  • 回复监听提示 Discord 被禁用或没有授权用户：设置 OMX_REPLY_ENABLED=true，并把 OMX_REPLY_DISCORD_USER_IDS 或 notifications.reply.authorizedDiscordUserIds 配成允许回复的 Discord 用户 ID。源码中，当启用 Discord Bot 但授权列表为空时，会输出明确的警告：[notifications] Discord reply listening disabled: authorizedDiscordUserIds is empty（src/notifications/config.ts）。

进一步深入

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 通知系统配置完全指南：Discord、Telegram、Slack、Webhook 与 OpenClaw 多平台接入2 oh-my-codex v0.8.1 发布解读：Team CLI 互操作、统一通知配置与 OpenClaw 超时安全边界3 OmX OpenClaw 集成指南：通过 HTTP 网关与 Clawdbot Agent 命令网关打通 Codex Hook 通知链路4 OmX OpenClaw 集成指南：hook instruction 提示词调优与上下文感知通知实战5 OmX 集成 OpenClaw 通知网关：Hook Prompt 调优指南（简洁 + 上下文感知）6 OmX OpenClaw 集成提示词调优指南：基于 hook instruction 模板的上下文感知通知管线7 OmX OpenClaw 通知网关集成指南：从 prompt 模板调优到 clawdbot 生产级命令网关配置8 OmX OpenClaw 整合提示詞調校指南：情境感知通知模板、環境變數門控與分發原理9 omx (oh-my-codex) OpenClaw 集成指南：Hook instruction 提示词模板调优与网关分发实战10 OmX OpenClaw 集成指南：Hook 提示词模板调优与上下文感知通知配置实战
热门项目推荐
相关项目推荐

热门内容推荐

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

最新内容推荐

Budibase 开源低代码平台实战指南：数据源集成、自动化工作流与自托管部署全解析Mongoose Models 完全指南：从 Schema 编译、CRUD 操作到 Change Streams 与视图niri 快速上手：从安装、启动到默认热键与源码构建的完整指南在 NixOS 上使用 NixOS 模块部署 PostgREST：从最小配置到生产实践MongoDB resmoke 测试套件（Test Suites）配置完全指南：从 YAML 结构到源码原理TradingAgents-CN 实战修复：market_quotes 集合 code 字段为 null 导致的 MongoDB 唯一索引冲突（E11000）Actual Budget 25.5.0 版本深度解析：全新 CLI 工具、交易合并与报表导出实战指南Gopeed 开发协作指南：分支工作流、离线调试与 Flutter 国际化实战agentmemory MCP 工具全景：54 个 memory_* 工具的索引、参数速查与选型实战Composio Python SDK 集成测试全指南：从环境搭建到 MCP 功能验证

项目优选

收起
kernelkernel
deepin linux kernel
C
33
18
docsdocs
暂无描述
Markdown
900
5.83 K
ops-transformerops-transformer
本项目是CANN提供的transformer类大模型算子库，实现网络在NPU上加速计算。
C++
1.14 K
2.75 K
pytorchpytorch
作为 Ascend for PyTorch 社区的核心组件，TorchNPU 是昇腾专为 PyTorch 打造的深度学习适配插件，使 PyTorch 框架能够直接调用昇腾 NPU，为开发者提供昇腾 AI 处理器的超强算力。
Python
860
1.35 K
ops-nnops-nn
本项目是CANN提供的神经网络类计算算子库，实现网络在NPU上加速计算。
C++
927
1.85 K
jiuwenswarmjiuwenswarm
JiuwenSwarm 是一款基于openJiuwen开发的智能AI Agent，它能够将大语言模型的强大能力，通过你日常使用的各类通讯应用，直接延伸至你的指尖。
Python
3.84 K
1.02 K
kernelkernel
openEuler内核是openEuler操作系统的核心，既是系统性能与稳定性的基石，也是连接处理器、设备与服务的桥梁。
C
533
603
ops-mathops-math
本项目是CANN提供的数学类基础计算算子库，实现网络在NPU上加速计算。
C++
1.37 K
1.46 K
AscendNPU-IRAscendNPU-IR
AscendNPU-IR是基于MLIR（Multi-Level Intermediate Representation）构建的，面向昇腾亲和算子编译时使用的中间表示，提供昇腾完备表达能力，通过编译优化提升昇腾AI处理器计算效率，支持通过生态框架使能昇腾AI处理器与深度调优
C++
548
397
cann-learning-hubcann-learning-hub
CANN 学习中心仓，支持在线互动运行、边学边练，提供教程、示例与优化方案，一站式助力昇腾开发者快速上手。
Jupyter Notebook
1.04 K
525