AI导哈

WhatsApp消息中继插件

一个将Codex与WhatsApp本地账户连接的插件，实现双向消息同步和多项目管理功能。

  • by abuiles
  • JavaScript
  • 本地部署
  • 46 星标
  • 更新于
在 GitHub 查看 abuiles/codex-whatsapp-relay

使用说明

Codex WhatsApp中继

将Codex放入您的WhatsApp。

WhatsApp Relay是一个Codex插件，它将本地WhatsApp帐户链接到Codex，让Codex读取和发送WhatsApp消息，并且可以选择让您从允许的直接聊天中控制Codex。

有用的部分是心理模型：扫描一次二维码，让中继保持WhatsApp会话，并继续通过手机与Codex通话。在引擎盖下，它使用 codex app-server，因此电话控制的聊天映射到本地Codex线程，这些线程可以在Codex和WhatsApp消息中稍后恢复。

控制器桥现在具有项目意识。一次聊天可以保持 api 忙碌，切换到 web，向另一个仓库发出一次性提示，但仍然要求一次性 /btw 在不偏离主线的前提下提出次要问题。

你能做什么

  • 只需扫描一次二维码，即可将您的本地WhatsApp帐户链接到Codex
  • 读取聊天记录、检查缓存消息、同步历史记录，并从Codex发送WhatsApp回复
  • 将允许的WhatsApp聊天视为轻量级的Codex客户端
  • 在一次聊天中保持多个项目的活动状态，并在不丢失会话状态的情况下在它们之间切换
  • 在保持当前项目的同时，用一次性提示定位另一个项目
  • 在一个项目内的已保存Codex会话之间跳转
  • 批准、拒绝、停止或降低WhatsApp的权限
  • 用语音笔记与Codex交谈，并获得当地语音笔记的回复
  • 稍后在终端中继续相同的工作 codex resume

在Codex中安装

将此提示粘贴到Codex中：

Install the WhatsApp Relay plugin globally for my user account.

Use this repository as the source:
https://github.com/abuiles/codex-whatsapp-relay

Install the current release tag:
v0.4.3

Do all of the following:

1. Clone the repo into ~/.codex/plugins/whatsapp-relay if it does not exist yet.
2. If it already exists, fetch tags and check out v0.4.3 without deleting unrelated user files.
3. Run npm install inside ~/.codex/plugins/whatsapp-relay.
4. Create or update ~/.agents/plugins/marketplace.json so it contains a personal marketplace entry for this plugin.
5. Keep any existing marketplace entries that are already there.
6. Make sure the plugin entry uses:
   - name: whatsapp-relay
   - source.source: local
   - source.path: ./.codex/plugins/whatsapp-relay/plugins/whatsapp-relay
   - policy.installation: AVAILABLE
   - policy.authentication: ON_USE
   - category: Productivity
7. Do not create a repo-local marketplace entry.
8. After writing the marketplace file, tell me to restart Codex.
9. After restart, tell me to open /plugins and install WhatsApp Relay.

Do not push or publish anything. Only set up the local personal marketplace install.

安装后

  1. 重新启动Codex。
  2. 打开 /plugins.
  3. 安装 WhatsApp Relay.
  4. 让Codex在WhatsApp上给你打电话。

如果WhatsApp尚未链接，Codex应首先运行身份验证流程，等待您扫描二维码，验证会话，然后发送ping。如果你想控制手机，请让Codex启用它。如果你在手机上使用相同的WhatsApp帐户， Message yourself 可以用作控制表面。

运作原理

                +----------------------+
                |   Codex app-server   |
                |   native threads     |
                +----------+-----------+
                           ^
                           |
Your phone <-> WhatsApp Relay daemon <-> WhatsApp session
  1. 通过扫描Codex输出中显示的QR链接本地WhatsApp会话。
  2. Codex可以通过MCP工具检查聊天记录、读取缓存消息、同步历史记录和发送回复。
  3. 如果启用电话控制，允许的直接聊天将持续 codex app-server WhatsApp的帖子。

多项目心理模型

One WhatsApp chat
      |
      +--> current project  -> sticky default lane
      |        Example: /project alpha-app
      |
      +--> /in other-project ... -> one-shot lane
      |        Does the work there, then leaves you where you were
      |
      +--> /btw ... -> disposable side thread
               Never changes the current project or project session

You are in project-a
      |
      +--> project-b is still running in the background
      |
      +--> project-b finishes
               |
               +--> relay posts a completion message
                    and reminds you that you are still in project-a

试试看

  • “链接我的WhatsApp帐户并验证身份验证状态。”
  • “显示我未读的WhatsApp聊天记录。”
  • “给爱丽丝发一条WhatsApp消息，说我10分钟后到。”
  • “允许我的号码并启动WhatsApp Relay，这样我就可以从WhatsApp控制Codex。”
  • “在代码目录中的alpha应用程序中启动新会话。”
  • “/项目alpha应用程序”
  • “/在alpha应用程序中运行失败的测试并解释错误”
  • “/btw GPT-5.4推理模式发生了什么变化？”

电话命令

一旦控制器桥运行，允许的直接聊天可以发送：

  • 纯文本以继续当前项目的食典会议
  • 在当地转录后，继续进行当前项目的食品法典委员会会议

项目控制：

  • /projects 列出已配置的项目，并显示哪个项目处于活动状态或忙碌状态
  • /project 检查此聊天的活动项目
  • /project <number|alias|project hint|path hint> 切换到另一个项目，让Codex解析针对已存在项目的自然项目提示，并在本地解析路径时自动添加仓库
  • 自然文本 start new session in alpha app inside code directory 跳到回购并在那里重新开始
  • /new 或 /n 在活动项目中启动新会话
  • /in <project> <prompt> 在不切换的情况下将一次性提示发送到另一个项目
  • /btw <prompt> 问一个一次性的附带问题，然后回到你当前的项目

会话控制：

  • /sessions 或 /ls [project] 列出项目的最新Codex线程
  • /1, /2, ...跳转到最近列出的会话之一
  • /session <number|thread-id-prefix> 切换当前项目的会话
  • /session <project> <number|thread-id-prefix> 或 /c <...> 直接切换另一个项目的会话
  • /status 或 /st [project] 在运行处于活动状态时检查活动项目会话或其他项目的会话，包括实时运行状态和最新进度预览

如果在同一项目或 /btw 作用域已经繁忙，中继现在将其排队，确认已排队，并在当前任务完成后自动运行它，除非您明确停止活动运行。停止一个作用域也会清除该作用域的排队跟进，这样陈旧的提示就不会挥之不去。

权限和批准：

  • /permissions 或 /p [project] 检查当前权限级别
  • /ro, /ww，或 /dfa 快速切换活动项目的权限级别
  • /permissions ro|ww|dfa 或 /permissions <project> read-only|workspace-write|danger-full-access 更改项目的沙盒级别
  • /approve 或 /a [project|btw] [session], /deny 或 /d [project|btw]，以及 /cancel 或 /q [project|btw] 回答待审批提示
  • /stop 或 /x [project|btw] 取消飞行中的Codex运行
  • /help 或 /h 查看命令帮助

语音回复：

  • /voice status 检查此聊天是否启用了口头回复
  • /voice on 或 /voice on 2x 启用本地口语答复
  • /voice off 返回纯文本回复
  • reply in voice at 1x ... 或 reply in voice at 2x ... 在不更改聊天默认设置的情况下进行一次性口头回答

danger-full-access 在网桥禁用该项目会话的沙盒之前，需要通过WhatsApp发送回明确的确认码。对于当前正在进行的项目，桥接器现在会要求您以简短的回复进行确认，例如 /dfa 123456；对于另一个项目，它使用 /dfa <project> 123456. 语音笔记在本地转录 mlx-community/parakeet-tdt-0.6b-v3 通过 uvx 和 ffmpeg。在对其采取行动之前，桥接器会将转录回复过来，并且会拒绝非常短的低置信度转录，因此您可以重试，而不是向Codex发送垃圾。 合并、发布、重定基础、重定向和删除等高影响力的回购操作有意不直接通过语音执行；桥接器要求您将这些作为文本重新发送，这样听错的数字就不会改变错误的分支或PR。 当通过启用语音回复时 /voice on 或者一枪 reply in voice at 2x ... 提示，该桥还合成了本地出站WhatsApp语音提示。 如果口头回复包含您需要点击或复制的内容，例如预览URL、链接、斜线命令或确认码，桥接器现在会发送一个带有这些可操作位的简短文本。

每次聊天的项目切换都很棘手。一次性 /in 提示不会更改活动项目，以及 /btw 总是使用新鲜的一次性线。

通过WhatsApp跨项目工作

聊天总是有一个当前项目。正常的文本和语音提示会出现在那里。除此之外，您还可以将一次性工作发送到另一个项目，在项目内保存的会话之间跳转，并在不失去位置的情况下回复审批。

实际模型为：

  • 使用 /project <alias> 当您想将默认车道移动到另一个项目时。
  • 使用 /project 或 /projects 要查看编号的快捷方式，请执行以下操作 /project 2 无需键入别名即可快速跳转。
  • 使用 /project <natural hint> 当您希望Codex在已有的项目中进行选择时，例如 /project blood project.
  • 使用 /in <alias> <prompt> 当你想在其他地方发送一个提示而不切换时。
  • 使用 /btw <prompt> 用于不应涉及任何项目会议的一次性附带问题。
  • 使用 /ls [project] 和 /session [project] <number> 当您想将此聊天切换到同一项目中另一个已保存的Codex线程时。

快速记忆法：

/project  -> move my main lane
/in       -> send one thing elsewhere
/session  -> switch threads inside one project
/btw      -> ask a side question and come right back

示例：

  • 开始做一些长时间的事情 project-b，然后切换到 project-a:
    • /project project-b
    • run the full test suite and tell me what is failing
    • /project project-a
    • keep working on the login bug
  • 将一次性工作发送至 project-b 同时保持专注 project-a:
    • /project project-a
    • /in project-b run pwd and tell me which branch you are on
  • 在不干扰任何项目的情况下提出一个附带问题：
    • /btw what changed in GPT-5.4 reasoning modes?

一个项目内的会话切换

每个项目都有自己的会话历史记录。这意味着您可以返回同一项目的旧线程，而不会影响其他项目。

示例：

  • 列出当前项目的最近会话：
    • /ls
  • 列出另一个项目的最近会话：
    • /ls alpha-app
  • 将当前项目切换到列出的第二个会话：
    • /session 2
  • 直接切换另一个项目：
    • /session alpha-app 2
  • 按线程id前缀连接：
    • /session alpha-app 019d36f3

网桥在每次聊天中为每个项目保留一个活动会话指针。你可以随时切换指针。

重要限制：网桥一次只允许每个项目别名运行一次飞行中的Codex。如果你想在同一个仓库系列上进行真正的并行工作，请将单独的工作树用作单独的项目，并在WhatsApp的这些项目别名之间切换。

repo root
  |
  +-- worktree-a  -> project-a
  +-- worktree-b  -> project-b
  +-- worktree-c  -> project-c

One repo family, several WhatsApp-manageable projects

后台完成、批准和权限

如果 project-b 在您工作时完成 project-a，桥接器将完成发布回聊天中，并告诉您仍在 project-a。它不会自动切换您。

这同样适用于批准和失败：

  • 例如，无需切换项目即可回复批准 /a project-b 或 /d project-b
  • 失败会指出哪个项目失败，并提醒您哪个项目仍处于活动状态
  • 权限更改可以通过以下方式快速完成 /ro, /ww，或 /dfa 对于活动项目，或明确表示 /p project-b ww

这使得WhatsApp的流量可以预测： /project 改变你的主车道， /in 向另一条车道发送一个提示， /session 保存项目指向的线程的更改，以及后台事件永远不会窃取焦点。

语音模式项目控制

语音注释现在可以通过Codex意图分类步骤驱动相同的项目控制。这意味着该桥不依赖于硬编码的短语表来处理项目和会话。相反，在桥接器对转录的笔记进行操作之前，使用轻量级的专用Codex模型而不是您的主要工作会话设置，将转录的笔记分类为桥接命令或正常提示。

分类器应该理解的意图示例：

  • projects
  • project alpha app
  • list sessions for alpha app
  • session alpha app 2
  • status for alpha app
  • start new session in alpha app
  • workspace write
  • read only
  • danger full access

实用规则：如果你想用声音来处理项目，就要明确意图。说 project ..., sessions ..., session ..., status ...，或 start new session in ... 因此，Codex可以清晰地将转录本映射到桥接动作中。

语音模式心智模型：

voice note
   |
   +--> local transcription
   |
   +--> intent classification
          |
          +--> bridge command
          |      project / session / permissions / status
          |
          +--> normal prompt
                 send it to the current project session

它的作用

  • 将WhatsApp与Codex输出中显示的QR链接
  • 让Codex检查最近的聊天和消息
  • 允许Codex发送WhatsApp消息
  • 可以按需同步旧历史记录
  • 可以通过WhatsApp公开Codex的允许电话号码
  • 可以在现有的Codex线程之间切换电话聊天
  • 可以在一次聊天中同时保持多个项目运行处于活动状态
  • 可以根据聊天切换活动项目，并从本地目录提示中自动发现repos
  • 可以向另一个项目发送一次性提示，而无需切换主线程
  • 可以处理一次性物品 /btw 主项目线程之外的问题
  • 可以在以下位置运行每次电话聊天 read-only, workspace-write，或 danger-full-access
  • 可以在本地转录WhatsApp语音笔记，并将其输入活动的Codex会话
  • 可以使用macOS合成本地WhatsApp语音备忘回复 say 或 ResembleAI/chatterbox-turbo

安全注意事项

  • workspace-write 是默认的网桥权限级别。它将聊天保持在工作区内，并在运行保护操作之前将批准提示转发回WhatsApp。
  • danger-full-access 每次聊天都需要简短的确认码回复，例如 /dfa 123456.使用 /new 或 /permissions workspace-write 下降下来。
  • 一次只能有一个控制器桥拥有实时WhatsApp会话。现在开始第二次结账会拒绝，而不是默默地替换当前的网桥。
  • 授权材料 plugins/whatsapp-relay/data/auth* 是本地运行时状态，不应提交。
  • 键入斜线命令仍然是更改会话或权限的最可靠方式。语音笔记最适合自然提示和简短的口头命令，如 help, status, stop，以及 new session.

语音备忘

语音笔记控制首先是本地的。桥接器下载WhatsApp音频，用 ffmpeg，运行Parakeet v3至 uvx，然后将成绩单转发到现有 codex app-server 会议。

您需要在运行桥接器的机器上提供以下本地工具：

  • ffmpeg
  • uvx

可选环境变量：

  • WHATSAPP_RELAY_STT_MODEL 覆盖默认值 mlx-community/parakeet-tdt-0.6b-v3
  • WHATSAPP_RELAY_STT_TIMEOUT_MS 延长或缩短转录超时时间

第一个音符可能会明显变慢，因为 uvx 可能需要安装 parakeet-mlx 并下载模型缓存。

语音回复

出站语音回复也是本地优先。

默认提供程序是Chatterbox。英文回复使用 Chatterbox-Turbo，并支持使用非英语回复 Chatterbox-Multilingual.

提供者选择由环境变量控制：

  • WHATSAPP_RELAY_TTS_PROVIDER=system 选择退出Chatterbox并使用macOS say 退路。
  • WHATSAPP_RELAY_TTS_PROVIDER=chatterbox-turbo 明确保持出站语音回复打开 ResembleAI/chatterbox-turbo.
  • WHATSAPP_RELAY_TTS_CHATTERBOX_PYTHON 重写用于Chatterbox的Python解释器。默认情况下，网桥会查找 plugins/whatsapp-relay/.venv-chatterbox/bin/python.
  • WHATSAPP_RELAY_TTS_CHATTERBOX_DEVICE=auto|mps|cpu 控制Chatterbox设备选择。 auto 是默认值。
  • WHATSAPP_RELAY_TTS_CHATTERBOX_AUDIO_PROMPT=/absolute/path/to/reference.wav 可选择使用本地参考剪辑为Chatterbox启用语音克隆。
  • WHATSAPP_RELAY_TTS_CHATTERBOX_ALLOW_NON_ENGLISH=0 将非英语回复选择回macOS回退，而不是多语言Chatterbox。
  • WHATSAPP_RELAY_TTS_TIMEOUT_MS 延长或减少任一提供商的出站TTS超时时间。

如果您希望控制器网桥在重新启动后继续使用Chatterbox，请将其持久化在网桥配置中。 whatsapp_start_controller_bridge 接受 ttsProvider 和 ttsChatterboxAllowNonEnglish，将它们存储在 plugins/whatsapp-relay/data/controller-config.json，并在以后启动守护进程时重用它们。

要在本地安装Chatterbox Turbo：

npm run whatsapp:install-chatterbox

安装程序创建 plugins/whatsapp-relay/.venv-chatterbox，更喜欢 python3.11 当解释器可以构建一个可工作的virtualenv时，可以追溯到 python3 否则，并安装 chatterbox-tts 所以桥可以直接呼叫它。它也钉住了 setuptools<81 因为目前对珀斯的依赖仍在进口 pkg_resources.

要吸烟测试哪个提供商处于活动状态：

npm run whatsapp:tts:smoke -- --text "Testing local voice replies."

要明确地对Chatterbox Turbo进行冒烟测试：

WHATSAPP_RELAY_TTS_PROVIDER=chatterbox-turbo \
npm run whatsapp:tts:smoke -- --provider chatterbox-turbo --text "Testing Chatterbox Turbo locally."

要在烟雾测试期间强制使用多语言路线，请传递语言提示：

WHATSAPP_RELAY_TTS_PROVIDER=chatterbox-turbo \
npm run whatsapp:tts:smoke -- --provider chatterbox-turbo --language-id es --text "Claro, te doy el resumen corto ahora."

Chatterbox路径比 say 因为Python进程和模型是为每个生成的回复本地加载的。它现在是首选提供商。英语使用Turbo，而支持的非英语回复通过多语言模型路由。如果您喜欢在任何地方都使用较轻的macOS语音路径，请设置 WHATSAPP_RELAY_TTS_PROVIDER=system。如果您只希望macOS回退到非英语回复，请设置 WHATSAPP_RELAY_TTS_CHATTERBOX_ALLOW_NON_ENGLISH=0在珀斯本地隐式水印不可用的机器上，助手会回退到珀斯的虚拟水印，因此本地合成仍然有效。

CLI回退

如果您需要在Codex之外进行测试：

npm run whatsapp:auth
npm run whatsapp:controller
npm run whatsapp:status

相关 MCP