🔥 @sunwu51/codexwebui

🚀 在 Linux、Windows 或 Android Termux 上随时运行 Codex 网页界面 🚀

English | 中文说明

把 Codex UI 直接放进浏览器。一个命令就能跑。

本质上就是把你的 Codex 桌面端体验通过 Web UI 暴露出来，并且支持跨平台运行。

 ██████╗ ██████╗ ██████╗ ███████╗██╗  ██╗██╗   ██╗██╗
██╔════╝██╔═══██╗██╔══██╗██╔════╝╚██╗██╔╝██║   ██║██║
██║     ██║   ██║██║  ██║█████╗   ╚███╔╝ ██║   ██║██║
██║     ██║   ██║██║  ██║██╔══╝   ██╔██╗ ██║   ██║██║
╚██████╗╚██████╔╝██████╔╝███████╗██╔╝ ██╗╚██████╔╝██║
 ╚═════╝ ╚═════╝ ╚═════╝ ╚══════╝╚═╝  ╚═╝ ╚═════╝ ╚═╝

这是什么？

@sunwu51/codexwebui 是一个轻量级桥接层，用来把 Codex app-server 工作流暴露成浏览器可访问的 Web UI。

你只需要运行一个命令，它会启动本地 Web 服务。之后你可以在本机、局域网设备，或者任何你已经打通网络的环境里访问它。

一句话：把 Codex 桌面端体验解锁到 Linux、Windows 和基于 Termux 的 Android 场景里。

快速开始

# 推荐：直接运行
npx @sunwu51/codexwebui

# 然后在浏览器打开
# http://localhost:18923

默认情况下，@sunwu51/codexwebui 还会额外启动：

cloudflared tunnel --url http://localhost:<port>

启动输出里会同时打印：

• 隧道访问地址
• 终端二维码
• 访问密码

如果不想自动启动隧道，可以加：

npx @sunwu51/codexwebui --no-tunnel

如果你已经在本机或代理层准备好了认证，不希望启动时强制执行 codex login，可以用：

npx @sunwu51/codexwebui --no-login

Linux

node -v   # 需要 18+
npx @sunwu51/codexwebui

Windows PowerShell

node -v   # 需要 18+
npx @sunwu51/codexwebui

Android Termux

pkg update && pkg upgrade -y
pkg install nodejs -y
npx @sunwu51/codexwebui

Android 上建议额外处理这些后台问题：

1. 保持当前 Termux 会话不要被关闭。
2. 在 Android 系统设置里关闭 Termux 的电池优化。
3. 保持 Termux 常驻通知开启，降低被系统杀掉的概率。
4. 可选但推荐：

termux-wake-lock

5. 在手机浏览器里打开启动输出里的地址；如果进程被系统杀掉，回到 Termux 重新执行 npx @sunwu51/codexwebui。

iPhone / iPad + Tailscale Serve

如果你想在 iPhone 或 iPad 的 Safari 中使用，推荐通过 HTTPS 提供服务。

一个比较实用的私有方案是：

npx @sunwu51/codexwebui --no-tunnel --port 5900
tailscale serve --bg 5900

然后打开：

https://<your-machine>.<your-tailnet>.ts.net

这个方案适合：

• iPhone Safari 访问
• 添加到主屏幕
• 使用内置语音输入 / 转写功能
• 直接访问 Windows 主机上的同一套项目和对话

补充说明：

• Tailscale Serve 会把访问限制在你的 tailnet 里
• iOS 上通常需要 HTTPS / secure context 才能稳定使用移动端访问和语音输入
• Safari 可能还有少量移动端样式细节问题，但不影响基本使用
• 具体认证体验可能会受代理方式影响
• 如果 Web UI 新建的对话没有立刻出现在 Windows 端，重启一次 Windows 应用通常就能刷新出来

功能特性

• 一条命令启动：npx @sunwu51/codexwebui
• 支持 Linux、Windows、Android Termux
• 浏览器优先的 Codex UI 体验，默认地址 http://localhost:18923
• 方便局域网设备访问
• 适合远程主机 / 无头环境运行 Codex
• 可配合反向代理、隧道、Tailscale 使用
• 不需要全局安装就能快速试用
• 内置按住说话的语音输入，转写后回填到输入框
• 可选 Telegram bot 桥接
• 支持项目 ZIP 导出 / 导入
• 导入聊天时会自动重写 CODEX_HOME、项目路径和 provider/model 信息，方便跨环境恢复

Telegram Bot 桥接（可选）

启动前设置这些环境变量：

export TELEGRAM_BOT_TOKEN="<your-telegram-bot-token>"
export TELEGRAM_ALLOWED_USER_IDS="<your-telegram-user-id>,<optional-second-id>"
export TELEGRAM_DEFAULT_CWD="$PWD"
npx @sunwu51/codexwebui

说明：

• TELEGRAM_ALLOWED_USER_IDS 是必须的
• 只有白名单中的 Telegram 用户可以使用这个桥接
• 如果未配置允许用户，收到的 Telegram 消息会被拒绝

常用 bot 命令：

• /start
• /threads
• /newthread
• /thread <threadId>
• /current
• /history
• /status
• /whoami
• /help

最近功能更新

• 新建线程时支持可搜索的项目选择器
• Select folder 旁边增加 Create Project
• 新建项目自动置顶
• 自动生成更智能的新项目名建议
• 全局持久化项目排序
• 线程刷新 / 轮询期间保留 optimistic in-progress 状态
• 更好的移动端侧边栏
• Skills Hub 移动端布局优化
• 更好的语音输入体验，包括转写中状态展示和转写结果回填输入框

适合哪些场景？

| 场景 | 你得到什么 | |---|---| | Linux 工作站 | 不依赖桌面壳层，直接在浏览器里使用 Codex | | Windows 电脑 | 快速从 Chrome / Edge 打开 Web UI | | Android Termux | 在手机上启动服务并用浏览器控制 | | 远程开发机 | 服务跑在服务器，界面在客户端看 | | 局域网共享 | 同网段其他设备也能打开 | | 无头工作流 | 终端和浏览器分离，提高效率 | | 自定义路由 | 可以放在反代 / 隧道后面 |

截图

Skills Hub

Chat

Mobile UI

架构

┌─────────────────────────────┐
│  浏览器（桌面 / 移动端）     │
└──────────────┬──────────────┘
               │ HTTP/WebSocket
┌──────────────▼──────────────┐
│   @sunwu51/codexwebui       │
│  (Express + Vue UI bridge)  │
└──────────────┬──────────────┘
               │ RPC / Bridge calls
┌──────────────▼──────────────┐
│      Codex App Server       │
└─────────────────────────────┘

运行要求

• Node.js 18+
• 可用的 Codex app-server 环境
• 浏览器能访问到宿主机地址和端口
• 如果使用语音输入，需要麦克风权限

常见问题

| 问题 | 处理方式 | |---|---| | 端口被占用 | 换一个空闲端口，或停止旧进程 | | npx 运行失败 | 升级 npm / node 后重试 | | Termux 安装失败 | 先 pkg update && pkg upgrade，再重装 nodejs | | 其他设备无法访问 | 检查防火墙、监听地址、局域网路由 |

自动发布

这个仓库已经配置了基于 GitHub Actions + npm Trusted Publishing 的自动发布流程：

• 触发分支：master
• 触发条件：package.json 里的 version 发生变化
• 发布动作：安装依赖、执行 pnpm run build、自动 npm publish

如果你只是使用者，这部分可以忽略；如果你是维护者，改版本号并 push 到 master 即可自动发布。

参与贡献

欢迎提 Issue 和 PR。

如果你发现：

• 平台兼容问题
• 移动端体验问题
• provider / voice / project import-export 相关问题

都很适合直接提出来。

Star 支持

如果你也觉得 Codex UI 应该可以在 任何机器、任何系统、任何屏幕 上访问，欢迎给这个项目点个 Star。

Forked from pavel-voronin/codex-web-local by Pavel Voronin.