arthurcolle/codex-micro-open

# Codex Micro Open [](https://github.com/arthurcolle/codex-micro-open/actions/workflows/ci.yml) [](https://arthurcolle.github.io/codex-micro-open/) [](pyproject.toml) [](LICENSE)  **[阅读完整的图文拆解](https://arthurcolle.github.io/codex-micro-open/)** 针对由 Work Louder 制造、OpenAI 以 Codex Micro 名义销售的设备，提供开源的净室 macOS 集成：USB/BLE HID 取证、Report 6 JSON-RPC、灯光、摇杆控制、已签名的原生 helper，以及六通道代理控制台。 本项目是对 OpenAI 作为 **Codex Micro** 销售的 Work Louder 设备进行的非侵入性技术拆解和净室主机探测。手头设备的机身标签为 **Creator Micro 2**；其 USB 产品字符串为 **Codex Micro**；OpenAI 的产品页面将该设计/SKU 命名为 **`kbd-1.0-codex-micro`**。这是同一设备的三个层级的身份信息，而不是三个不同的观察到的设备。 核心结论非常实用：这是一款可编程的 ESP 级 HID 设备，而不是一个封闭的按键盒。其出厂固件公开了一个 63 字节的双向厂商 HID 报告，携带带帧的 JSON-RPC。主机应用程序可以监听按键、编码器转动和摇杆动作；查询固件/电池状态；并且无需使用 ChatGPT 用户界面即可驱动灯光。 ## 目录 - [技术档案](reports/technical-dossier.md)：完整的脱敏、证据驱动的拆解，包括主机架构和未决事实。 - [公开技术文章](article/codex-micro-open-integration.md)：适合公开发布的脱敏叙述。 - [独立可视化审阅版](article/codex-micro-open-integration.html)：包含格式化打印的 JSON 证据卡、三个可运行的控制演练、插图和可扩展的 13 张图表技术图集的渲染故事。 - [图表规格](article/diagram-specs.md)：每个技术视图的 Mermaid 源码、标题、来源标签和证据链接。 - [游戏控制器和六代理蓝图](reports/expansion-blueprints.md)：已实现的映射、平台限制、状态模型和扩展设计。 - [混合功能矩阵](reports/hybrid-control-capability-matrix.md) 和 [可视化控制手册](reports/hybrid-control-visual-manual.md)：精确的 HID 功能、Navigate/Pointer/Swarm 操作和恢复程序。 - `src/codex_micro_probe/`：无依赖的 Python 3.11+ IOKit 传输、帧解析、解析器、描述符解码器、固件解析器和安全 CLI。 - `tests/`：针对两种传输方式、报告重组、描述符结构、固件元数据、事件规范化和禁用方法的离线测试。 - `evidence/`：脱敏的原始抓包、公开图像元数据、主张来源以及安全分类。所有有用的抓包都包含在此存储库中。 已提交的 [`docs/`](docs/) 目录树是轻量级的 GitHub Pages 版本。 13 MB 的文章构建版本依然是一个独立的离线版本，内嵌了其 CSS、照片和技术图集。 ## 已确定的精确设备事实 | 事实 | 结果 | 证据类别 | |---|---|---| | USB 标识 | Work Louder `303A:8360`，产品 `Codex Micro` | 精确设备 | | USB 状态 | USB 2.0 全速，活动的 HID，500 mA 电流分配 | 精确设备 | | 固件状态 | `v0.4.1`；状态暴露了配置文件、层、电池、充电情况 | 精确设备探测往返 | | USB HID 描述符 | 275 字节；报告 1, 2, 3, 4 和 6 | 精确设备 | | BLE HID 描述符 | 216 字节；报告 1, 2, 3 和 6；无游戏手柄 Report 4 | 精确设备 | | 私有通道 | 使用页面 `0xFF00`，Report ID 6，63 字节输入/输出 | 精确设备 | | 通过 BLE 输入 | 全部 13 个开关 ID、编码器按下/旋转、全范围摇杆 | 精确设备 | | 运行时灯光 | 环境预览和六个独立的 Agent LED，包括动画 | 精确设备 | | 设备文件系统 | 一个 939 字节的 `keymap.json`；执行了只读清点 | 精确设备 | | 静态固件 | ESP32-S3 镜像，ESP-IDF 5.3.2 血统，factory/NVS/LittleFS/coredump | 公开 v0.4.0 镜像 | 公开的 v0.4.0 二进制文件是目前可用的最接近的固件工件，而不是本设备上运行的 v0.4.1 镜像。档案对于每个静态声明都保持了这一界限。 ## 快速开始 直接从检出的代码运行；安装是可选的： ``` git clone https://github.com/arthurcolle/codex-micro-open.git cd codex-micro-open PYTHONPATH=src python3 -m codex_micro_probe discover --json PYTHONPATH=src python3 -m codex_micro_probe descriptor PYTHONPATH=src python3 -m codex_micro_probe permissions PYTHONPATH=src python3 -m codex_micro_probe doctor PYTHONPATH=src python3 -m codex_micro_probe status --json PYTHONPATH=src python3 -m codex_micro_probe listen --duration 15 PYTHONPATH=src python3 -m codex_micro_probe gamepad --duration 15 PYTHONPATH=src python3 -m codex_micro_probe agents \ --mapping config/agent-map.current.json --duration 15 PYTHONPATH=src python3 -m codex_micro_probe agent-animation \ --pattern evil-eyes --duration 12 --fps 4 PYTHONPATH=src python3 -m codex_micro_probe voice-swarm \ --cwd "$HOME/Dsco" # 针对正在运行的 daemon： PYTHONPATH=src python3 -m codex_micro_probe mode \ --json-request '{"command":"hybrid-mode","value":"navigate"}' PYTHONPATH=src python3 -m codex_micro_probe mode \ --json-request '{"command":"hybrid-mode","value":"pointer"}' PYTHONPATH=src python3 -m codex_micro_probe mode \ --json-request '{"command":"hybrid-mode","value":"swarm"}' ``` 用户当前的物理键帽排列保留在 [physical-layout.png](evidence/live/2026-07-31/physical-layout.png) 中，并由 `config/agent-map.current.json` 中的物理开关 ID 进行映射。 Codex Micro 本身没有被观察到的音频输入接口。DSCO 语音控制从选定的 **Mac 麦克风** 进行录音，并通过 **Mac 扬声器** 播放其语音状态确认；Micro 提供物理手势和视觉反馈。 macOS 要求为终端或承载 Python 的应用程序授予 **隐私与安全性 → 输入监控** 权限。在没有它的情况下仍然可以进行发现和描述符捕获；但打开报告流将返回 `kIOReturnNotPermitted`。 机器可读的事件以 JSON Lines 格式发出，因此非 Python 软件可以将该探测作为子进程使用： ``` PYTHONPATH=src python3 -m codex_micro_probe listen | your-service ``` ## DSCO 物理控制词汇表 **来源：** 这是一个基于精确设备 HID 事件和可逆灯光调用的主机端 DSCO 控制策略。它不是一种隐藏的固件模式，也不描述官方 Codex 应用程序的行为。 六个透明的 Agent 位置是稳定的模型通道。按住一对键的同时按下普通的操作键，即可同时寻址两个通道： | 配对 | 物理 ID | 普通 DSCO 目标 | |---|---|---| | 顶部 | `AG00` + `AG01` | 两个 Sol 通道 | | 左侧 | `AG02` + `AG03` | 两个 Terra 通道 | | 右侧 | `AG04` + `AG05` | 两个 Luna 通道 | | 中间 | `AG03` + `AG04` | 跨配对：内部的 Terra 和 Luna 通道 | 这些常规任务在 `workspace-write` 下仍然是可以恢复的 Codex 通道。仅通过配对寻址永远不会提升它们的权限。 ### 直接 DSCO 控制 这些控制仅通过本地 DSCO daemon 执行；没有任何控制会更改 Micro 固件、macOS 安全权限或默认的沙箱。 | 物理控制 | DSCO 动作 | 范围 / 护栏 | |---|---|---| | 编码器顺时针/逆时针旋转 | 将选定通道的工作量标记增加/减少 `0.1` | 限制在 `0.0`–`1.0` 之间，仅限运行时，在菜单栏状态中可见 | | 编码器按下 | 为选定的通道准备恢复 | 仅适用于下一次分发，且仅当存在持久的 DSCO/Codex 线程时 | | Play / `ACT06` | 主要操作 | 在命令驾驶舱中，它选取/释放一个 Agent；在 Mac 控制模式下，长按它进行点击拖拽；否则它会准备一个持久通道的恢复 | | YOLO / `ACT07` | 批准 / 确认 | 在当前的物理布局中位于 YEET 左侧；同时也会完成显式的一次性权限序列 | | YEET / `ACT08` | 拒绝 / 取消 | 在当前的物理布局中位于 YOLO 右侧；取消挂起的扇出或权限准备 | | Stop / `ACT09` | 停止 / 后退 | 停止活动的语音简报，取消选定的工作，退出驾驶舱，或者在 Mac 控制模式下发送 Escape | | 宽语音/空格键 / `ACT10+ACT11` | 语音输入 | 一个覆盖在两个开关上的可见键帽；两个物理报告被合并为一个逻辑麦克风动作 | | 四点键 / `ACT12` | 打开图形化命令面板 | 调出上下文建议，并在面板打开时将编码器重新用于安全的菜单导航 | | 摇杆 | Agent 光标或显式准备好的 Mac 指针 | 原始极坐标位置仍然可以通过 `gamepad` 获取；桌面注入默认关闭，需要可见的 **Joystick Controls This Mac** 开关 | 因此，顶部的六个键依然是 Agent 地址，而操作行和编码器用于选择执行姿态，无需将工作绑定到特定的聊天中。 ### 命令面板：图形化叠加层 `native/CodexMicroVoice` 现在提供的是一个本地的 macOS 命令面板，而不是一个单纯的按键映射器。它是一个浮动叠加层，由与 daemon 相同的仅限本地主机、白名单控制 socket 提供支持。它显示六个 Agent 通道及其模型和实时状态、选定通道的工作量、当前焦点以及简短的上下文命令列表。 按下四点 `ACT12` 键即可打开它。在它打开期间，转动编码器以高亮显示一个操作，然后按下编码器以调用它。鼠标点击使用相同的命令。可用的六个操作经过了刻意精简并清晰可见： 1. **语音简报** — 启动选定的单通道简报。 2. **快速通道** — 准备一个简短的下一步分发；它既不更改沙箱也不更改治理。 3. **模型配对** — 选择焦点模型的两个通道。 4. **恢复** — 准备单个持久线程的恢复。 5. **确认扇出** — 显式启动显示的多通道简报。 6. **停止监听** — 关闭活动的本地麦克风简报。 该叠加层无法发送任意的 prompt、shell 命令、RPC 方法或固件更改。语音或键入注入仍然提供任务文本，而一次性红色权限锁存器依然是通向原生 `--systems-agent --gov-model none` 分发的唯一路径。 macOS 菜单应用程序现在拥有并监督 Python daemon，因此即使在构建终端关闭后，驾驶舱仍会继续运行，并在意外退出后重启 daemon。**Official Codex Mode** 释放 HID 句柄；**DSCO Swarm Mode** 重新获取它。正常的物理操作永远不会打开浏览器；文章位于一个独立的、明确命名的菜单项之后。 ### Backpiece Visual Lab 非按键的导光板现在是一个一流的群组显示器，而不仅仅是一个静态装饰。在 DSCO 模式下，daemon 将群组状态映射到一个命名的、仅运行时的背板场景，并将按键背光保持在接近最低水平，因此外壳的光晕在视觉上与六个 Agent 平铺区区分开来。正常的基线是 **Forest**；工作、批准、完成和失败可以暂时取得优先权。 从菜单栏或浮动的命令驾驶舱打开 **Backpiece Visual Lab** 以预览八个受限场景中的一个：Forest、Emerald Tide、Ocean、Aurora、Ember、Gold Alert、Moonlight 和 Fault。预览持续 15 秒，使用五帧过渡，然后恢复由群组派生的场景。**Restore Swarm State** 会立即结束预览。批准和失败信号会抢占手动预览，因此视觉实验无法掩盖关键状态。 只有命名的场景会通过本地 socket。此 UI 中没有任意的灯光或 RPC 字段，并且渲染器使用 `lights.preview`；它不会更改已保存的设备灯光配置。驾驶舱显示当前场景、源（`swarm`、`preview` 或关键覆盖）、原因和剩余的预览时间，因此无法解释的闪烁都有可见的原因。 DSCO 模式还为单个原生 DSCO 任务提供了一个特意设计得显眼、短暂的权限锁存器： 1. 点按并释放顶部和弦（`AG00` + `AG01`）。主机会播放第一次准备确认，并将可逆的运行时背景设置为立即变为纯亮黄色。 2. 在该阶段过期之前，点按并释放中间的和弦（`AG03` + `AG04`）。主机会播放第二次确认，并将背景更改为立即变为纯亮红色。 3. 按下 `ACT07` / **YOLO**。这会为随后的恰好**一次单通道**原生 DSCO 分发创建一个内存中的授权。token 被消耗一次后，主机返回到平静的绿色基线。 特权分发使用等效于以下参数的向量： ``` dsco --profile worker --model MODEL \ --systems-agent --gov-model none --prompt PROMPT ``` 它故意**不**使用 `-e codex`、shell 插或 Codex 的 `danger-full-access` 沙箱标志。这种区别至关重要：DSCO 自己的源代码将 `--systems-agent --gov-model none` 描述为 **UNGOVERNED**，并且**没有安全防护**。物理序列控制进入该状态的入口；它不会使随后执行的任务变得安全或受治理。 `ACT08`、错误的序列、阶段过期、切换模式或设备断开连接都会取消该锁存器。准备状态和 token 永远不会写入状态文件。取消、过期和一次性消耗会恢复绿色的仅运行时灯光；官方 Codex 模式不会接收 DSCO 灯光写入。 **精确设备现场证明 (2026-07-31)：** 连接 USB 的 v0.4.1 设备渲染了完整的黄色和红色背景预览，播放了所有三个 Mac 扬声器提示音，从 Mac 麦克风转录了“Run LS.”，消耗了一次授权，并以 `systems_agent=true`、`governance_model=none` 和退出代码 0 完成了一个原生的 Sol 通道 DSCO 任务。脱敏记录为 `evidence/live/2026-07-31/privilege-latch-live-proof.json`。 如果需要，可以安装独立的命令： ``` python3 -m venv .venv .venv/bin/pip install -e . .venv/bin/codex-micro-probe doctor ``` ## 安全契约 此设备探测 RPC 接口默认关闭。它没有任意 RPC 命令，并永久阻止： - `sys.bootloader` - `fs.write` 和 `fs.writebin` - `fs.delete` - `fs.format` 自检、充电器诊断和焦点应用程序更改也无法通过公共 CLI 使用。`fs-inventory` 发送一个受限的 `fs.list` 请求，并且不进行递归或写入。运行时灯光必须显式选择；`v.oai.rgbcfg` 还需要确认，因为其持久化语义尚未完全表征。受限的 `agent-animation` 命令仅使用运行时 `v.oai.thstatus` 通知，将持续时间限制在 30 秒，帧率限制在 8 fps，并保持已保存的设备灯光配置不变。 本研究没有进行任何 bootloader 进入、固件刷写、恢复出厂设置、打开外壳或设备文件系统更改的操作。 该设备-固件边界与上文记录的明确不受治理的单任务 DSCO 执行路径是分开的。后者受到保护以防止意外激活，但一旦被消耗，它就不受此 HID/RPC 白名单的约束。 ## 可重复性 使用标准库运行离线套件： ``` PYTHONPATH=src python3 -m unittest discover -s tests -v ``` 重新分析本地下载的公开固件镜像而无需提交它： ``` PYTHONPATH=src python3 scripts/analyze_firmware.py \ /private/tmp/codex-micro-firmware-v0.4.0.bin \ --expected-sha256 93596dec08f36a74e6860cd47ff7951e11ca3c8e4f3a2870665d1f95f768dee8 ``` 可以使用 `scripts/capture_host.sh` 将新的 macOS 证据暂存在被忽略的 `dist/captures/` 目录下。编辑序列号、位置 ID 和个人路径，运行 `python3 scripts/audit_release.py`，然后将有用的抓包提升到被追踪的 `evidence/captures/` 或 `evidence/live/` 目录树中。 构建并验证两个发布版本： ``` CODEX_MICRO_REUSE_DIAGRAMS=1 python3 scripts/build_html_article.py --target all python3 scripts/build_substack_article.py python3 scripts/check_links.py python3 scripts/audit_release.py ``` ## 来源与独立性 主要的商业和操作来源是 [OpenAI Codex Micro 页面](https://openai.com/supply/co-lab/work-louder/)、 [Work Louder 设置指南](https://worklouder.cc/micro-setup) 和 [官方固件发布存储库](https://github.com/worklouder/cm-v2-fw-releases)。 独立开发的、基于 MIT 许可证的 [FreeMicro 协议笔记](https://github.com/eliBenven/freemicro/blob/main/docs/PROTOCOL.md) 被用作确证的接口证据，特别是对于 BLE 行为。 该探测不包含任何厂商源代码、私有包内容、固件二进制文件或复制的 ChatGPT 实现。它是根据观察到的 HID 接口事实、Apple 公开的 IOKit 头文件和独立记录的通信行为编写的。

标签：HID设备, Python, 云资产清单, 后端开发, 无后门, 物联网, 硬件交互, 逆向工程