Codex Session Grid

Beta 测试版 · v0.1.0-beta.1

已在作者本机的 macOS + Codex Desktop 环境跑通。当前版本用于公开测试，不建议用于关键生产任务。

一个保持 Codex 视觉风格的多任务工作台，可用四宫格或九宫格同时查看、发送和跟踪多个真实 Codex Session。它是独立开发的本地辅助工具，并非 OpenAI 官方产品。

现在能做什么

• 四宫格、九宫格展示多个 Codex 任务，支持筛选、折叠、拖拽换位和单任务跳回 Codex App。
• 同步用户消息、Assistant 回复、工具调用、已查看图像、已读取文件等 Session 动态。
• 网页发出的消息由 macOS 原生桥接提交到对应 Codex App 任务，再从同一个 Session 同步回来。
• 运行中的任务显示绿色状态点；消息区按 Markdown 自动排版。
• 支持浏览器语音输入、引导提示词、模型、速度和推理强度控件。
• 服务只监听 127.0.0.1，复用本机已有的 Codex 登录，不需要填写 API Key。

同步与 Token 逻辑

网页不是另一套聊天系统，而是 Codex Session 的多窗口遥控器和监视器。

flowchart LR
    A["浏览器宫格"] -->|"读取任务与进度"| B["本机 Sidecar"]
    B --> C["Codex Session / app-server"]
    A -->|"发送一条消息"| D["macOS 原生桥接"]
    D --> E["Codex App 对应任务输入框"]
    E -->|"只发送一次"| C
    C -->|"同一 Session 的消息、回复、工具状态"| A

Loading

网页点击发送后，原生桥接会找到 Codex App 中的目标任务、填入输入框并按下发送。网页立即显示“已发送 · 等待回复”，随后持续读取同一个 Session。因此 App 和网页看到的是同一份对话，不会因为网页端再启动一次推理而浪费双份 Token。

环境要求

• macOS 与已登录的 Codex Desktop App。
• Node.js，建议使用当前 LTS 版本。
• Xcode Command Line Tools 提供的 swiftc，用于首次编译原生单次发送桥接。
• 原生发送需要在“系统设置 → 隐私与安全性 → 辅助功能”中允许 Codex。
• 语音输入需要浏览器支持 Web Speech API，并允许麦克风权限；Codex 内置浏览器不支持时，请改用 Chrome 或 Safari。

安装或更新插件后，建议新建一个 Codex 任务，让更新后的插件技能完整生效。

本地运行

git clone https://github.com/streetlightstartupnotes/codex-session-grid.git
cd codex-session-grid
bash scripts/start.sh

默认地址为 http://127.0.0.1:4317。启动命令会保持在前台运行；可按 Ctrl+C 停止，或在另一个终端执行：

bash scripts/stop.sh

需要换端口时，启动和停止都传入同一个变量：

CODEX_SESSION_GRID_PORT=4318 bash scripts/start.sh
CODEX_SESSION_GRID_PORT=4318 bash scripts/stop.sh

仓库当前按单插件源码结构发布，可直接用上面的脚本运行。Codex marketplace 一键安装结构将在后续版本补充；本机已有个人 marketplace 的开发者也可以把该目录登记为本地插件。

首次使用

1. 先打开 Codex App，并确认目标任务正常存在。
2. 按上面的命令启动工作台并打开本机地址。
3. macOS 首次询问辅助功能权限时允许 Codex，然后重新启动工作台。
4. 如需语音输入，在浏览器地址栏或系统设置中允许麦克风权限。
5. 在任意卡片底部输入消息并发送；网页会显示发送状态并同步 App 中同一 Session 的后续回复。

当前限制

• 当前重点测试平台是 macOS；原生单次发送依赖 Accessibility API，其他系统尚不支持这一发送方式。
• Codex app-server 接口属于实验能力，Codex 更新后可能需要跟随调整。
• 网页的模型、速度和推理强度控件目前可以完整显示并保存选择，但原生单次发送仍以 Codex App 当前输入框的设置为准。需要精确控制时，请先在 App 中调整；网页直控会在后续版本完善。
• Session 更新采用高频轮询，体验接近实时，但并非严格的推送协议。
• 浏览器语音识别能力和稳定性由 Web Speech API、浏览器及网络环境决定。
• 原生桥接会短暂定位目标任务并恢复原窗口，恢复过程属于尽力而为。

安全与隐私

• HTTP 服务固定绑定 127.0.0.1，请勿改成局域网或公网地址。
• 项目不会要求或保存 OpenAI API Key，也不会修改用户的 Codex 配置。
• 为展示与同步任务，服务会读取本机 Codex 的 Session 元数据和对话记录。
• 提交 Issue 时请先删除截图、日志中的任务内容、本机路径、账号信息和其他隐私数据。

更多安全说明见 SECURITY.md。

项目结构

.
├── .codex-plugin/plugin.json       # Codex 插件清单
├── public/                         # 宫格 Web UI
├── scripts/server.mjs              # localhost Sidecar 与 Session 同步
├── scripts/native-bridge.swift     # macOS 原生单次发送桥接
├── scripts/start.sh                # 启动脚本
├── scripts/stop.sh                 # 停止脚本
└── skills/codex-session-grid/      # Codex 技能与引导配置

开发检查

node --check scripts/server.mjs
node --check public/app.js
sh -n scripts/start.sh scripts/stop.sh
swiftc -typecheck scripts/native-bridge.swift

发布记录见 CHANGELOG.md，参与开发前请阅读 CONTRIBUTING.md。

路线图

• 让网页模型、速度和推理强度直接、安全地控制原生发送设置。
• 降低对实验性 app-server 协议的耦合。
• 增强语音识别错误诊断和浏览器兼容提示。
• 完善安装器、自动更新和更多 macOS 版本测试。

作者

路灯同学创业笔记

• X / Twitter
• 小红书
• GitHub

许可

本项目采用有限测试许可，公开源码不代表授予开放源代码权利。

允许个人和非商业组织在本机安装、运行、研究及测试；未经作者书面许可，不得商用、收费集成、转售、再分发、换名发布或作为在线服务提供。© 2026 路灯同学创业笔记，保留所有未明确授予的权利。