本文主要内容

一直想找一个好用的Codex WebUI项目，就是可以Docker部署然后在哪都能用的，但是找来找去，要么是bug多，要么是直接不接受pr，所以干脆我直接自己写了一个，还是比较满意的捏。有问题直接提issue即可，欢迎star和fork。

项目地址#

LimLLL

codex-webui

Waiting for api.github.com...

00K

Waiting...

Codex WebUI 项目说明#

给 OpenAI Codex CLI 做的 Web 前端。把命令行交互搬到浏览器里，支持多线程并发、文件管理、终端、插件市场等。

后端用 NestJS 通过 stdio JSON-RPC 和 codex app-server 通信，前端 React + Vite，中间用 Socket.IO 实时推送。

功能#

对话与线程

多线程并发运行，互不干扰
线程按工作区分组，支持归档、fork、回滚、重命名
Markdown 渲染 + Shiki 代码高亮
@ 引用文件、粘贴图片
追问（steer）和中断（stop）正在执行的 turn

审批流程

命令执行、文件变更的审批卡片，直接在页面上操作
支持安全策略切换（sandbox 级别）
多设备同时在线时的 CAS 防冲突

文件管理

树形文件浏览器，支持拖拽移动
Monaco Editor 代码查看
Git diff 分栏对比（@git-diff-view）
上传 / 下载 / 重命名 / 复制 / 移动 / 新建目录

终端

多 tab 共享终端（node-pty + xterm.js）
断线重连，输出不丢失
headless VT 回放

集成与插件

其他

JWT + API Key 认证
插件/MCP 服务器管理
深色/浅色主题，中英文切换
响应式布局，手机平板也能用
Docker 一键部署

技术栈#

1
浏览器
2
  React 19 · Vite 8 · TanStack (Router + Query + Virtual)
3
  Zustand · Socket.IO Client · Monaco Editor · xterm.js
4
  Tailwind CSS 4 · shadcn/ui · Framer Motion · dnd-kit
5
     ↕  REST + WebSocket
6
后端
7
  NestJS 11 · Fastify 5 · Socket.IO · node-pty
8
  SQLite (better-sqlite3 + Drizzle ORM) · Pino
9
     ↕  stdio JSON-RPC
10
  codex app-server（子进程）

快速开始#

前置条件#

Node.js >= 20
pnpm >= 9
Codex CLI 已安装并可用

Docker 部署（推荐）#

直接从 GHCR 拉取镜像，无需本地构建：

1
# 创建 .env
2
cat <<EOF > .env
3
WEBUI_API_KEY=your-secret-key
4
OPENAI_API_KEY=sk-xxx
5
EOF
6

7
# 启动（自动拉取多架构镜像）
8
docker compose up -d

或者手动运行：

1
docker run -d --name codex-webui \
2
  -p 8172:8172 \
3
  -e WEBUI_API_KEY=your-secret-key \
4
  -e OPENAI_API_KEY=sk-xxx \
5
  -v codex_root:/root \
6
  -v codex_workspaces:/workspaces \
7
  ghcr.io/limlll/codex-webui:latest

服务运行在 http://localhost:8172。

/root 卷持久化 codex/claude/MCP 配置及运行时工具链。首次启动自动释放内置 seed。

本地开发#

1
git clone https://github.com/LimLLL/codex-webui.git
2
cd codex-webui
3
pnpm install
4

5
cp .env.example .env
6
# 编辑 .env，至少设置 WEBUI_API_KEY
7

8
# 启动后端（默认端口 8172）
9
pnpm start:dev
10

11
# 另一个终端，启动前端（端口 5173，自动代理到后端）
12
cd web && pnpm dev

打开 http://localhost:5173 即可使用。

环境变量#

变量	必填	默认值	说明
`WEBUI_API_KEY`	是	—	登录密钥，同时用于派生 JWT 签名
`PORT`	否	`8172`	后端监听端口
`CODEX_BIN`	否	`codex`	codex CLI 可执行文件路径
`CODEX_HOME`	否	`~/.codex`	Codex 主目录
`WORKSPACE_ROOTS`	否	—	逗号分隔的允许访问目录
`LOG_LEVEL`	否	`info`	Pino 日志级别
`WEBUI_DB_PATH`	否	`CODEX_HOME/codex-webui.sqlite`	SQLite 数据库路径
`WEBUI_UPLOAD_MAX_BYTES`	否	`104857600`	上传文件大小限制（100MB）
`DEFAULT_TERMINAL_CWD`	否	—	终端默认工作目录
`WEBUI_TERMINAL_MAX_SESSIONS`	否	`10`	最大并发终端会话数（1-50）
`WEBUI_TERMINAL_GRACE_MS`	否	`45000`	断开连接后终端保活时长
`WEBUI_TERMINAL_SCROLLBACK`	否	`5000`	终端回滚缓冲区行数

项目结构#

1
├── src/                  # NestJS 后端
2
│   ├── codex/            # 进程管理、JSON-RPC 客户端
3
│   ├── threads/          # 线程 CRUD、WebSocket 网关
4
│   ├── files/            # 文件操作、路径安全校验
5
│   ├── terminal/         # 多 tab 终端（node-pty）
6
│   ├── auth/             # JWT + API Key 认证
7
│   ├── database/         # SQLite + Drizzle ORM
8
│   └── ...               # 其他模块
9
├── web/                  # React 前端
10
│   └── src/
11
│       ├── routes/       # TanStack Router 页面
12
│       ├── components/   # UI 组件
13
│       ├── stores/       # Zustand 状态管理
14
│       ├── hooks/        # 自定义 hooks
15
│       └── generated/    # Hey API SDK（自动生成）
16
├── Dockerfile            # 多阶段构建 + seed root
17
└── docker-compose.yml

常用命令#

1
pnpm start:dev          # 后端开发模式
2
pnpm build              # 编译后端
3
pnpm test               # 运行测试
4
pnpm lint               # ESLint 检查
5
pnpm db:generate        # 生成数据库迁移
6
pnpm db:migrate         # 执行迁移
7
cd web && pnpm dev      # 前端开发模式
8
cd web && pnpm build    # 前端构建（输出到 public/）

License#

AGPL-3.0

Codex WebUI项目