codex-cli-web

面向 Codex CLI 的本机优先 Web UI，底层基于 codex app-server（通过 stdio 的 JSON-RPC）。

简体中文 | English

目录

• 亮点
• 快速开始
• Web UI
• 配置
• 认证与多用户
• 历史（SQLite）
• 上传
• 开发
• 开源协作
• 安全策略
• 许可证

亮点

• 对接本机已安装的 codex CLI（本仓库不内置 Codex）。
• 默认仅监听回环地址（127.0.0.1），降低本地部署时误对外暴露风险。
• 支持多用户认证，并按管理员分配的 workspace 边界隔离权限。
• 支持 CODEX_CONFIG 单入口运行时配置（内联 JSON 或 JSON 文件路径）。
• 提供 SQLite 历史链路（可通过 CODEX_WEB_HISTORY_MODE=off 关闭）。

快速开始

环境要求

• Node.js 18+
• 已安装并可执行 codex CLI（codex --help 可用）

安装依赖

npm ci
# 或：npm install

开发模式启动

npm run dev

浏览器打开 http://127.0.0.1:5173。

开发模式默认：

• Web 服务：127.0.0.1:8787
• Vite 前端：127.0.0.1:5173
• 代理：/api、/ws、/socket.io 转发到服务端

构建与运行（生产模式）

npm run build
npm start

浏览器打开 http://127.0.0.1:8787。

默认仅监听回环地址（127.0.0.1）。如果要对局域网开放：

CODEX_WEB_HOST=0.0.0.0 npm start

Windows PowerShell 写法：

$env:CODEX_WEB_HOST="0.0.0.0"; npm start

Windows cmd.exe 写法：

set CODEX_WEB_HOST=0.0.0.0 && npm start

注意：管理员初始化未完成（或仍存在默认口令账号）时，服务会拒绝监听非回环地址。 建议先用回环地址启动，在 Web UI 完成管理员初始化后，再用 CODEX_WEB_HOST=0.0.0.0 重启。

作为 npm CLI 使用（ccw）

本节适用于“已发布到 npm 后”，或通过 npm 从本地路径安装包的场景。

使用 npx（无需全局安装）：

npx -p @very_aq/codex-cli-web ccw --config ./config.json

全局安装：

npm install -g @very_aq/codex-cli-web
ccw --config ./config.json

也可以通过 CLI 参数指定监听地址/端口（等价于 CODEX_WEB_HOST / CODEX_WEB_PORT）：

ccw -hostname 127.0.0.1 --prot 8787 --config ./config.json
# 或
ccw --hostname 127.0.0.1 --port 8787 --config ./config.json

如果你是直接从 git 仓库运行，且 ccw 提示缺少 server/dist/index.js，先执行：

npm run build

Web UI

本节用于对齐当前 Web UI 的主要功能入口（与你提供的运行截图一致）。

工作区（Workspace rail）

• 左侧竖向轨道展示“可用工作区”列表（按目录名首字母// 显示），点击可切换当前工作区。
• 当前工作区会影响：
  • 侧栏线程列表的过滤范围；
  • 新建线程默认使用的 cwd。

侧栏（线程 + 设置）

• 侧栏主入口：新线程、设置。
• 设置 面板包含常用操作：刷新线程列表、登出、主题/语言切换、颜色（Accent/Background）、紧凑视图；管理员额外提供“用户管理”入口。
• 线程卡片展示：标题、模型提供方（model provider）、更新时间；右侧归档按钮可将线程归档。

主区与输入框

• 顶部常用按钮：刷新当前线程、快速新建线程、查看文件变更（Changes）、上下文使用率、WS 连接状态。
• 输入框工具栏支持：
  • Plan / Model / Reasoning effort（可点击循环切换）；
  • 附件上传（也支持直接粘贴图片触发上传）；
  • 输入 / 打开 slash 命令菜单（也可用 /help 查看帮助）；
  • 输入 $ 打开 skills 选择（会从服务端加载可用 skills）。

配置

配置优先级

运行时配置按以下顺序解析：

1. 环境变量
2. CODEX_CONFIG（内联 JSON 或 JSON 文件路径）
3. 内置默认值（server/src/config/serverConfig.ts）

CODEX_CONFIG（单入口配置）

CODEX_CONFIG 支持两种形式：

• 内联 JSON：CODEX_CONFIG='{\"web\":{\"port\":9000}}' npm start
• JSON 文件路径：CODEX_CONFIG=./config.json npm start

Windows PowerShell（建议使用 JSON 文件路径形式）：

$env:CODEX_CONFIG="./config.json"; npm start

Windows cmd.exe：

set CODEX_CONFIG=./config.json && npm start

本仓库提供了带 +comment 字段注释的示例文件：config.json。

CLI 启动参数

服务端启动时会解析 config 参数，并同步到环境变量 CODEX_CONFIG：

• --config ./config.json
• ---config ./config.json（兼容写法）
• --config=./config.json（等价写法）
• ---config=./config.json（等价写法）

常用环境变量

• Web：CODEX_WEB_HOST、CODEX_WEB_PORT
• 认证：SESSION_TOKEN、CODEX_WEB_AUTH_DB_PATH
• Codex：CODEX_BIN、CODEX_APP_SERVER_ARGS、CODEX_CWD、CODEX_ALLOWED_CWD_ROOTS、CODEX_APPROVAL_POLICY、CODEX_SANDBOX_MODE、CODEX_HISTORY_PERSISTENCE、CODEX_DISABLE_RESPONSE_STORAGE
• 历史：CODEX_WEB_HISTORY_MODE、CODEX_WEB_HISTORY_DB_PATH、CODEX_WEB_HISTORY_PAGE_LIMIT、CODEX_WEB_HISTORY_WORKERS
• 上传：CODEX_WEB_UPLOAD_BASE_DIR、CODEX_WEB_MAX_UPLOAD_BYTES
• 调试/日志：CODEX_WEB_LOG_CWD_SWITCH
• CODEX_CWD 用于相对路径解析基准；新建线程未显式提供 cwd 时会使用该目录。

Windows 原生命令差异

原生 Windows 环境下，Codex CLI 的子命令/参数可能与 Linux/macOS 不一致。如果默认的 codex app-server --listen stdio:// 在你的环境跑不通，可以覆盖 app-server 启动参数：

• 用 CODEX_CONFIG（codex.appServerArgs），或
• 用 CODEX_APP_SERVER_ARGS（支持 JSON 数组或逗号分隔列表），例如：

PowerShell：

$env:CODEX_APP_SERVER_ARGS="app-server,--listen,stdio://"; npm start

cmd.exe：

set CODEX_APP_SERVER_ARGS=app-server,--listen,stdio:// && npm start

打开线程 turns 上限

• CODEX_WEB_OPEN_THREAD_TURNS_LIMIT：打开线程时首包返回的 turns 数量上限（默认：2；设置为数字可限制首包体积；设置为 all、unlimited 或 infinite 可取消限制，等价于 Number.MAX_SAFE_INTEGER / 9007199254740991）。

认证与多用户

服务端支持多用户认证，并对不同用户的工作区权限进行隔离。

• 管理员初始化：
  • 首次安装后，系统不会预置任何管理员账号（不会自动创建 admin/pass）。
  • 首次打开登录页会进入初始化流程（后端接口 POST /api/auth/bootstrap-admin/setup），由你自行创建管理员用户名和密码（密码最少 8 位）。
  • 在初始化完成前，服务拒绝监听非回环地址（例如 0.0.0.0）。
• pass 仅用于旧版本升级场景下的弱口令兼容检测，不是新安装时的默认可用密码；初始化流程也不允许把新密码设置为 pass。
• 认证/设置 DB：用户、工作区分配、用户自建工作目录、UI 偏好等都会持久化到 SQLite。
  • 可用 CODEX_WEB_AUTH_DB_PATH 覆盖路径（默认：~/.codex_cli_web/auth.db）。
• 两个工作区概念（解耦）：
  • auth workspaces：管理员分配的权限根目录（/api/auth/me 的 workspaces 字段）。
  • user-created workspaceDirs：用户保存的具体 cwd 列表（/api/workspaces/user-created）。
• 工作区隔离：非管理员只能在管理员分配的 workspaces 内操作。
  • 同时在 HTTP 与 WebSocket 行为中强制校验。
  • member 的访问边界只以管理员分配的 workspaces 为准（不会与 CODEX_ALLOWED_CWD_ROOTS 再取交集）。

历史（SQLite）

Web 服务可以将会话历史持久化到 SQLite。

• CODEX_WEB_HISTORY_MODE：off / shadow / primary（shadow 为兼容值，当前行为与 primary 一致）
• CODEX_WEB_HISTORY_DB_PATH：SQLite 文件路径（默认：~/.codex_cli_web/history.db；相对路径以仓库/工作区根目录解析）
• CODEX_WEB_HISTORY_PAGE_LIMIT：历史消息列表分页默认大小（默认：2，仅按 user/assistant 边界计数；最大：500）
• CODEX_WEB_HISTORY_WORKERS：SQLite worker 数量（默认：1；0 表示禁用 worker；最大：16）

上传

• CODEX_WEB_UPLOAD_BASE_DIR：上传根目录（默认：<CODEX_CWD>/.codex-web/uploads；相对路径以 CODEX_CWD 解析）
• CODEX_WEB_MAX_UPLOAD_BYTES：单文件上限（默认：104857600，即 100MB）

开发

常用命令

npm run dev              # 同时启动 server + web（开发模式）
npm run build            # 先构建 web，再构建 server
npm start                # 启动构建后的服务
npm test                 # 运行 server 侧测试（Vitest）
npm run codex:generate   # 重新生成 Codex 协议 TS 类型（需要 codex 在 PATH）

目录结构

server/  # Node/TypeScript 服务端，负责对接 Codex 进程
web/     # React + Vite 前端
docs/    # 计划与项目文档

开源协作

参见 CONTRIBUTING.md。

安全策略

参见 SECURITY.md。

许可证

本项目采用 MIT 许可证，详见 LICENSE。