把 Codex 装进桌面控制台：Codex Micro 插件下载安装与配置教程

chxdon

如果你经常在 Codex Desktop 里同时处理多个任务，来回找窗口、切任务、点 Fast 或提交输入，很容易打断思路。Codex Micro 可以把这些高频操作放到 Ulanzi D200 Series 的实体按键上：任务状态直接显示在键面，按一下就能切换任务，还能快捷使用 Fast、Usage、Pin、New、Fork、Steer、Mic 和 Submit。

本文介绍两种安装方式：让 LLM/代码 Agent 自动完成安装，或者从 GitHub 下载后手动执行命令。两种方式都会安装 Ulanzi Studio 插件与本机 Codex Bridge，最后再配置实体按键布局。

项目地址：UlanziTechnology/OpenCodexMicro

一、Codex Micro 能做什么？

功能	用途
Codex Task 1–5	显示最近五个 Codex 任务的标题与实时状态，按键可准确打开对应任务
Fast	开关当前任务的 Fast 模式
Usage	在键面显示剩余用量，按下后聚焦 Codex
Pin	固定或取消固定当前任务
New	新建 Codex 任务
Fork	从当前任务创建分支任务
Steer	把输入框中的内容作为补充指令发送给正在运行的任务
Mic	控制 Codex 麦克风操作
Submit	提交或排队发送输入框中的内容

任务按键会根据实际状态切换空闲、运行、完成、等待处理、错误和离线图标。设备布局完全由 Ulanzi Studio 管理，不需要额外设置快捷键映射。

二、安装前准备
请先确认以下环境：

- macOS，并已安装当前可用的 Codex Desktop；
- Ulanzi Studio 3.0 或更高版本；
- Ulanzi D200 Series 已连接到 Ulanzi Studio；
- Node.js 20 或更高版本；
- 电脑可以访问 GitHub。

在终端执行下面的命令可以检查 Node.js 版本：

1. node --version

复制代码

如果显示的主版本号小于 20，请先升级 Node.js。

三、方式一：使用 LLM/Agent 安装（推荐）
如果你正在使用 Codex 等能够操作本机文件和终端的代码 Agent，可以让 Agent 按仓库内置的安装说明自动完成检查、安装和验证。

注意：普通网页聊天机器人无法直接操作你的 Mac。这里的 LLM/Agent 必须能够读取 GitHub 仓库、运行终端命令，并在需要退出或打开应用时与你确认。

1. 把 GitHub 地址交给 Agent
在 Agent 中输入：

1. 请帮我安装这个插件：https://github.com/UlanziTechnology/OpenCodexMicro

复制代码

2. Agent 会做什么？
仓库中的

1. AGENTS.md

复制代码

已规定安装流程。Agent 应当：

1. 检查 Ulanzi Studio 已安装插件的

1. manifest.json

复制代码

；
2. 只有找到 UUID 为

1. com.ulanzi.ulanzistudio.codexmicro

复制代码

，并确认清单中的

1. CodePath

复制代码

文件存在，才判断插件有效；
3. 插件缺失或损坏时，使用仓库内的

1. install-ulanzi-studio-plugin

复制代码

skill 安装预构建插件；
4. 插件验证通过后，使用

1. setup-codex-bridge

复制代码

skill 安装或修复

1. Codex Bridge.app

复制代码

与本机 sidecar；
5. 分别报告 Ulanzi Studio 插件状态和 Bridge 连接状态。

这套检查可以避免仅凭文件夹名称误判安装状态，也不会在插件已经有效时重复覆盖安装。

3. 配合 Agent 完成需要确认的操作
如果 Ulanzi Studio 正在运行，Agent 会请你先退出应用，再替换已加载的插件；它不应在未经允许时强制关闭应用。Bridge 安装完成后，启动

1. Codex Bridge.app

复制代码

会退出当前正在运行的 Codex 实例，因此请先保存正在进行的工作。

安装结束后，确认 Agent 分别给出以下结果：

- Codex Micro 插件的 manifest、入口文件和本地化文件验证通过；
- Bridge 后台服务正常；
-

1. http://127.0.0.1:17373/health

复制代码

可访问；
- 从

1. Codex Bridge.app

复制代码

启动 Codex 后，状态接口显示已连接。

如果你希望完全自己操作，请使用下面的手动安装方式。

四、方式二：从 GitHub 手动安装
1. 下载项目并安装依赖
打开“终端”，依次执行：

1. git clone https://github.com/UlanziTechnology/OpenCodexMicro.git
2. cd OpenCodexMicro
3. npm install

复制代码

1. git clone

复制代码

会从 Ulanzi 官方 GitHub 组织下载项目，

1. npm install

复制代码

会安装 Bridge 构建所需的依赖。

如果终端提示

1. git: command not found

复制代码

，请先执行

1. xcode-select --install

复制代码

，安装完成后再重试。

2. 安装 Ulanzi Studio 插件
安装前请先完全退出 Ulanzi Studio，避免正在加载的插件文件被替换。然后在项目目录中执行：

1. npm run install:plugin

复制代码

该命令会校验仓库内预构建插件的清单与入口文件，再原子安装 Codex Micro，不会改动其他 Ulanzi Studio 插件。

安装完成后重新打开 Ulanzi Studio，在右侧插件列表中搜索

1. codex

复制代码

。看到 Codex Micro 分类及一组操作项，说明 Studio 插件已经安装成功。

3. 安装并启动 Codex Bridge
Codex Micro 由两部分组成：Ulanzi Studio 插件负责设备界面和按键；Codex Bridge 负责在本机连接 Codex Desktop。继续在项目目录执行：

1. npm run setup

复制代码

脚本会构建 Bridge sidecar、注册当前用户的后台服务，并把应用安装到：

1. ~/Applications/Codex Bridge.app

复制代码

接下来请按这个顺序操作：

1. 完全退出普通方式启动的 Codex Desktop；
2. 打开

1. ~/Applications/Codex Bridge.app

复制代码

；
3. 等待 Codex Desktop 被 Bridge 拉起；
4. 保持 Ulanzi Studio 正常运行并连接 D200 Series。

注意事项
以后使用 Codex Micro 时，必须通过

1. ~/Applications/Codex Bridge.app

复制代码

启动 Codex，请勿直接打开 Codex Desktop。

五、在 Ulanzi Studio 中配置按键
在 Ulanzi Studio 右侧搜索

1. codex

复制代码

，展开 Codex Micro，把需要的 Action 拖到设备键位即可。

建议把 Codex Task 1–5 连续放在同一排，方便按“最近任务”顺序快速切换；其余位置再放 Fast、Usage、Pin、New、Fork、Steer、Mic 和 Submit。布局没有硬编码，同一个 Action 也可以放到多个按键上。

下面是实际配置完成后的 Ulanzi Studio 界面：

Codex Micro 在 Ulanzi Studio 中的实际按键配置

图中右侧已经显示 Codex Micro 的全部操作项，中间 D200 键盘区域则配置了任务切换、Fast、Usage、Pin、New、Fork、Steer、Mic 和 Submit 等常用功能。你可以根据自己的工作习惯自由调整。

六、验证连接是否正常
在终端执行：

1. curl http://127.0.0.1:17373/health
2. curl http://127.0.0.1:17373/state

复制代码

1. health

复制代码

接口用于确认 Bridge 服务已启动，

1. state

复制代码

接口用于查看 Codex 是否连接以及当前任务状态。Bridge API 只监听本机回环地址

1. 127.0.0.1:17373

复制代码

；Codex 调试接口也只绑定本机地址，不会直接暴露到局域网。

七、常见问题
1. Ulanzi Studio 里找不到 Codex Micro
确认安装插件前已经退出 Ulanzi Studio，并在安装后重新启动。如果仍然看不到，回到项目目录再次执行：

1. npm run install:plugin

复制代码

2. 按键显示 Offline
通常是 Codex 没有通过 Bridge 启动。请完全退出 Codex Desktop，再打开：

1. ~/Applications/Codex Bridge.app

复制代码

随后用前面的

1. health

复制代码

和

1. state

复制代码

命令检查连接。

3. 某个任务按键无法切换
先确认按键显示的任务仍在 Codex 最近任务列表中，再查看 Bridge 错误日志：

1. tail -f "$HOME/Library/Application Support/OpenCodexMicro/bridge-error.log"

复制代码

4. Steer 或 Submit 没有效果
Steer 需要当前任务正在运行，并且 Codex 界面中存在可用的输入框内容。Submit 用于提交或排队发送输入框内容；请先确认 Codex 窗口处于可交互状态。

八、后续更新
进入已经下载的项目目录，执行：

1. git pull
2. npm install
3. npm run check
4. npm run setup
5. npm run install:plugin

复制代码

更新插件后需要重新启动 Ulanzi Studio。

写在最后
Codex Micro 把“看任务状态、切任务、控制常用操作”集中到了 D200 的实体按键上。对于经常并行使用 Codex 的用户，它更像是一块随手可按的任务控制台，而不只是快捷键集合。

本项目基于 MIT License 发布。它是连接 OpenAI 产品的独立、非官方集成，不隶属于 OpenAI，也不代表 OpenAI 的赞助、背书或官方支持。Ulanzi 在本项目中的实现与维护范围仅限 Ulanzi Studio 插件目录；插件消费现有本机 Bridge 暴露的状态与操作接口，Ulanzi 未参与 CDP 或 Codex CDP 实现的设计、规范制定、开发或维护。详细说明请参阅项目仓库中的 NOTICE.md。