Codex Web Console

一个面向本地开发场景的 Codex Web 工作台。它用浏览器界面连接本地项目目录，读取和继续 Codex 历史会话，并通过 codex app-server 启动新的 Codex turn、接收实时输出和处理执行/审批请求。

这个项目的定位是“本机 Codex 操作台”，不是云端 SaaS。它适合在可信网络内使用，用来集中管理多个本地代码项目的 Codex 记录、文件上下文和运行状态。

功能

• 本地项目管理：选择或连接项目目录，按用户保存可见项目列表。
• Codex 历史记录：按项目目录的 cwd 匹配 Codex threads，支持查看历史记录和继续会话。
• 新建/继续任务：在指定项目目录中启动新的 Codex turn，支持选择模型、推理强度、沙盒和审批策略。
• 实时状态：通过 WebSocket 展示 Codex 输出增量，并在会话列表和会话头部显示 running / idle 状态。
• 文件上传：把文件上传到当前项目的 .codex-web/uploads/，并自动把上传文件路径加入 prompt 上下文。
• 文件预览：支持 Markdown、文本、图片、PDF 和二进制文件信息预览，文本预览最多读取 2 MB。
• 用户视图：内置 admin 用户，可创建其他用户来分别记忆项目列表。用户切换只影响本工具里的项目可见性，不隔离 Codex 登录态或系统权限。
• LAN 访问：服务端默认监听 0.0.0.0:4573，可以通过环境变量调整监听地址和端口。

技术栈

• 前端：React 19、Vite、lucide-react、react-markdown
• 后端：Fastify、WebSocket、Zod
• 本地存储：node:sqlite
• Codex 集成：codex app-server --listen stdio://
• 测试：Vitest

运行要求

• Node.js 需要支持 node:sqlite。本项目当前在 Node.js v25.6.1 下验证过。
• npm
• 已安装并登录可用的 Codex CLI
• 需要访问的本地项目目录

可以先确认本机工具：

node --version
npm --version
codex --version

快速开始

安装依赖：

npm install

开发模式启动：

npm run dev

开发模式会同时启动：

• Fastify API / WebSocket 服务：本机访问 http://127.0.0.1:4573，监听所有网卡
• Vite 前端服务：本机访问 http://127.0.0.1:5173，监听所有网卡

Vite 会把 /api 和 /ws 代理到后端。局域网设备可以访问 http://<本机局域网 IP>:5173。

生产构建：

npm run build

运行构建后的服务：

npm run serve

默认访问地址：

http://127.0.0.1:4573

服务默认监听所有网卡。同一局域网内的其他设备可以使用本机局域网 IP 访问，例如：

http://192.168.250.102:4573

常用脚本

npm run dev                  # 同时启动后端和 Vite 前端
npm run dev:server           # 只启动 Fastify 后端
npm run dev:client           # 只启动 Vite 前端
npm run build                # TypeScript 检查 + Vite 构建
npm run test                 # 运行 Vitest 测试
npm run serve                # 启动后端并托管 dist 前端
npm run generate:codex-schema

环境变量

变量	默认值	说明
CODEX_WEB_HOST	0.0.0.0	后端监听地址
CODEX_WEB_PORT	4573	后端监听端口
CODEX_WEB_PROJECT_ROOT	/Volumes/DevDrive/program	默认允许浏览和创建项目的根目录
CODEX_WEB_DATA_DIR	.codex-web	SQLite 数据库和运行数据目录
CODEX_WEB_CODEX_BIN	codex	Codex CLI 可执行文件
CODEX_WEB_ALLOW_OUTSIDE_PROJECT_ROOT	未开启	设为 1、true、yes 或 on 后允许连接默认根目录之外的项目

示例：

CODEX_WEB_PROJECT_ROOT="$HOME/code" \
CODEX_WEB_ALLOW_OUTSIDE_PROJECT_ROOT=true \
npm run dev

数据位置

• 项目和用户元数据：.codex-web/codex-web.sqlite
• 上传文件：当前项目目录下的 .codex-web/uploads/
• 前端构建产物：dist/

.gitignore 已忽略 node_modules/、dist/、.codex-web/、日志和覆盖率文件。

工作方式

后端启动时会拉起：

codex app-server --listen stdio://

浏览器不会直接解析 Codex 的隐藏状态文件，而是通过后端桥接到 codex app-server：

• thread/list：列出项目相关历史会话
• thread/read：读取会话详情
• thread/start：创建新会话
• thread/resume：恢复已有会话
• turn/start：启动新的 Codex turn
• turn/steer：向运行中的 turn 追加引导
• turn/interrupt：中断运行中的 turn
• command/exec：执行命令
• approval.respond：响应 Codex 发起的审批请求

项目可见性按用户保存在 SQLite 中。会话记录来自 Codex 自身，按 cwd 和所选项目目录匹配。

文件访问边界

项目目录默认必须位于 CODEX_WEB_PROJECT_ROOT 下。如果开启 CODEX_WEB_ALLOW_OUTSIDE_PROJECT_ROOT=true，可以连接默认根目录之外的项目。

即使开启越界项目连接，文件预览和上传仍会被限制在当前选中的项目目录内，避免通过文件链接读取项目外部文件。

安全说明

• 默认沙盒是 danger-full-access，默认审批策略是 never。这更适合个人本机可信环境。
• 如果要在不完全可信的项目中使用，建议在界面里切换为 read-only 或 workspace-write，并把审批策略改为 on-request。
• 用户切换不是登录系统，也不隔离 Codex 账号、文件系统权限或系统进程。
• 如果把服务暴露到局域网，请只在可信网络中运行，并确认端口访问范围。

测试

运行：

npm run test

当前测试覆盖了：

• Codex RPC envelope 分类和 bridge 行为
• 目录浏览
• 实时运行状态
• 路径边界策略
• 项目/用户 SQLite 存储
• Codex thread fallback 和列表分页

项目结构

.
├── server/
│   ├── codexBridge.ts       # codex app-server stdio 桥接
│   ├── config.ts            # 服务配置和默认运行策略
│   ├── db.ts                # SQLite 项目/用户存储
│   ├── directoryBrowser.ts  # 可浏览目录列表
│   ├── index.ts             # Fastify 服务入口
│   ├── liveState.ts         # 实时 turn / agent message 状态
│   ├── pathPolicy.ts        # 项目和文件访问边界
│   ├── routes.ts            # REST API
│   ├── socket.ts            # WebSocket 消息协议
│   ├── threadFallback.ts    # JSONL thread 读取兜底
│   └── threadList.ts        # Codex thread 分页读取
├── src/
│   ├── App.tsx              # 主界面
│   ├── api.ts               # REST API 客户端
│   ├── codexSocket.ts       # WebSocket 客户端
│   ├── styles.css           # UI 样式
│   └── types.ts             # 前端类型
├── tests/                   # Vitest 测试
├── scripts/
│   └── generate-codex-schema.mjs
├── package.json
├── vite.config.ts
└── tsconfig.json