让你自己的键盘控制 ChatGPT

zmk-feature-codex-micro 是一个与具体键盘无关的 ZMK module。它把 Codex Micro 风格的六个 Agent 键和常用命令作为标准 ZMK behavior 提供出来。键盘仓库仍然只管理自己的矩阵、层和按键；协议、USB、蓝牙与会话状态由模块负责。

哪些键盘可以集成

模块不依赖 Ferris Sweep、Sweep Pro、墨水屏或特定矩阵。只要中央侧支持 ZMK USB device、拥有足够的 Flash 和 RAM，就可以绑定 &codex_key。分体键盘只在 central 一侧启用，peripheral 使用普通固件。

• 有屏幕：可以订阅模块状态事件，显示六个 Agent 的状态。
• 无屏幕：Agent 与命令按键完整可用，状态直接在 ChatGPT 中查看。
• USB：增加第二个 vendor-defined HID 接口，不替换普通键盘接口。
• 蓝牙：在当前 ZMK Bluetooth profile 上增加加密 HID-over-GATT 通道。

开始之前

• 准备一个可以正常构建的 ZMK config 仓库。
• 确认哪一半是 central；通常是通过 USB 连接电脑的半边。
• 为 ZMK 和本模块固定经过测试的 commit 或 release tag。
• 保留一份不启用 Codex 的已知可用固件，方便排查和回退。

第一步：把模块加入 west manifest

在键盘配置仓库的 config/west.yml 中加入 NXTKB remote 和模块项目：

manifest:
  remotes:
    - name: zmkfirmware
      url-base: https://github.com/zmkfirmware
    - name: nxtkb
      url-base: https://github.com/nxtkb
  projects:
    - name: zmk
      remote: zmkfirmware
      revision: <tested-zmk-commit>
      import: app/west.yml
    - name: zmk-feature-codex-micro
      remote: nxtkb
      revision: <release-tag-or-commit>
  self:
    path: config

不建议长期使用 main。固定 revision 可以确保未来 ZMK 或模块更新时，旧固件仍能被重复构建。

第二步：应用临时的官方 ZMK 补丁

Codex USB 接口需要 interrupt-OUT。Zephyr 当前的开关会同时给普通键盘 HID_0 和 Codex HID_1 创建 OUT endpoint，而官方 ZMK 的 HID_0 尚未注册接收回调。因此在上游合并等价修复前，需要应用模块附带的小补丁：

west update
west patch -sm zmk-feature-codex-micro apply

west update 和 west build 不会自动应用模块补丁，因此必须显式执行 west patch。模块也提供了可复用的 GitHub Actions workflow，会在编译前完成这一步。如果模块不在 west workspace 内，可以改用 git apply 应用 zephyr/patches/zmk/zmk-usb-hid-interrupt-out.patch。这不是 NXTKB ZMK fork，只是让官方 ZMK 主键盘接口安全读取或丢弃它自己的 OUT report。模块的 Codex 数据仍由 HID_1 独立处理。官方 ZMK 提供等价回调后，应停止应用此补丁。

第三步：选择 USB 或蓝牙传输

在 build.yaml 中给 central 构建增加 snippet。USB 模式：

include:
  - board: nice_nano//zmk
    shield: corne_left
    snippet: nxtkb-codex-micro-usb

同时启用 USB 与蓝牙：

include:
  - board: nice_nano//zmk
    shield: corne_left
    snippet: nxtkb-codex-micro-usb nxtkb-codex-micro-ble

右手 peripheral 不增加 snippet：

  - board: nice_nano//zmk
    shield: corne_right

第四步：在 keymap 中绑定按键

在 keymap 顶部引入模块提供的 behavior 和按键 ID：

#include <behaviors.dtsi>
#include <behaviors/codex_key.dtsi>
#include <dt-bindings/nxtkb/codex.h>

然后把动作放入任意层。下面展示核心绑定，实际层仍需要满足你键盘的完整按键数量：

codex_layer {
    bindings = <
        &codex_key CODEX_AGENT_0
        &codex_key CODEX_AGENT_1
        &codex_key CODEX_AGENT_2
        &codex_key CODEX_AGENT_3
        &codex_key CODEX_AGENT_4
        &codex_key CODEX_AGENT_5
        &codex_key CODEX_FAST
        &codex_key CODEX_APPROVE
        &codex_key CODEX_DECLINE
        &codex_key CODEX_SPLIT
        &codex_key CODEX_MIC
        &codex_key CODEX_SEND
    >;
};

可直接参考仓库中的 Corne 完整示例。它同时也是 CI 使用的非 NXTKB 键盘编译测试。

可选：显示 Agent 状态

显示并不是协议模块的依赖。屏幕或 LED 模块可以订阅 nxtkb_codex_state_changed，然后调用 nxtkb_codex_state_get()。快照提供六个槽位、当前选中槽位、标准化状态、选择标记和原始 RGB 值。

#include <nxtkb/codex/events.h>
#include <nxtkb/codex/state.h>

这样显示代码仍属于你的键盘或显示 module，Codex 核心不会依赖某块屏幕。

蓝牙首次升级后必须重新配对

主机会缓存键盘的 HID report map。第一次启用 BLE snippet 后，请在电脑中删除旧键盘，在键盘上清除对应 ZMK profile，再重新配对。只关闭再打开蓝牙通常不会更新缓存的功能描述。

Codex 动作会跟随 ZMK 当前选择的 USB 输出或蓝牙 profile。其他电脑保持连接并保存自己的 Agent 状态，不需要为了切换 Codex 而全部断开。

设备身份与 ChatGPT 发现限制

当前 ChatGPT 桌面应用没有公开第三方 Codex Micro 设备注册流程。集成者必须使用自己有权使用的设备标识，并验证所安装版本的 ChatGPT 如何发现设备。在官方提供第三方发现或认证机制之前，本项目适合开发、研究和互操作测试，不应宣传为官方认证兼容。

发布前检查清单

• central 的 USB-only 和 USB+BLE 构建均通过。
• peripheral 在不启用 Codex snippet 时仍可构建。
• 普通键盘、consumer、鼠标、触控板和 ZMK Studio 功能没有回归。
• 检查目标控制器的 Flash 与 RAM，而不只看 UF2 文件大小。
• 重新配对每个启用过 Codex BLE 的 profile。
• 分别测试 USB、蓝牙、输出切换以及多台电脑。
• 不要发布带实验身份的 UF2。

从哪里开始

模块、补丁、集成文档和 Corne 示例都位于 nxtkb/zmk-feature-codex-micro。 建议先让示例在自己的 ZMK 环境中通过，再把同样的 west 项目、snippets 和 behavior 绑定迁移到实际键盘。