一个面向个人使用的移动端优先 Codex Web 控制台。Codex 和代码都留在个人电脑上,浏览器通过私人 VPN 访问。
本项目由 AI(OpenAI Codex)开发,并由项目维护者审阅和维护。
- Web 页面运行在
3100端口。 - Node 网关运行在
8787端口,并通过 stdio 管理codex app-server。 - Codex 复用电脑上的
~/.codex登录、配置和历史任务。 - 权限默认跟随本机 Codex 配置;
trusted项目会使用完全访问,避免重复命令审批。 - 浏览器只持有 HttpOnly 会话 Cookie,不接触 Codex 凭证。
- 网关只允许访问
config/projects.json中声明的目录。
要求 Node.js 22.13+ 和已登录的 Codex CLI:
codex login
npm install
cp .env.example .env项目没有内置默认口令。第一次启动前,必须生成自己的初始访问口令:
openssl rand -hex 32将命令输出的完整随机字符串填入本机 .env 的 CODEX_WEB_TOKEN。这个值就是第一次登录 Web 控制台时使用的口令,不要把真实值写入 README、源码或提交到 Git。
首次启动后,服务会将口令的哈希和随机会话密钥保存到 ~/.codex-web/auth.json,不会保存明文口令。之后应通过页面中的“安全设置”修改口令;只修改 .env 不会覆盖已经初始化的口令。
如果忘记口令,可以停止服务,删除 ~/.codex-web/auth.json,在 .env 中设置新口令后重新启动。
然后设置 VPN 访问参数:
CODEX_GATEWAY_HOST=0.0.0.0
CODEX_GATEWAY_PORT=8787
CODEX_ALLOWED_ORIGINS=http://你的VPN地址:3100
CODEX_SECURE_COOKIE=false例如个人电脑的 VPN 地址是 100.64.0.8:
CODEX_ALLOWED_ORIGINS=http://100.64.0.8:3100默认情况下,网页端任务权限会跟随本机 Codex 客户端配置,例如 ~/.codex/config.toml 中的项目 trust_level。当当前项目或其父目录是 trusted 时,网页端会按完全访问启动任务,即 approvalPolicy=never 和 sandbox=danger-full-access。如需强制网页端使用更保守的审批策略,可以在 .env 中设置:
CODEX_WEB_PERMISSION_MODE=safe如需完全自定义网页端权限,可以设置:
CODEX_WEB_PERMISSION_MODE=custom
CODEX_APPROVAL_POLICY=on-request
CODEX_APPROVALS_REVIEWER=user
CODEX_SANDBOX=workspace-write复制项目配置模板:
cp config/projects.example.json config/projects.json编辑 config/projects.json,加入允许远程操作的项目。路径必须存在并使用绝对路径。该文件包含本机路径,已被 Git 忽略。
开发模式:
npm run dev:all长期运行:
npm run build
npm start手机连接同一个 VPN 后打开:
http://你的VPN地址:3100
可以使用手机浏览器的“添加到主屏幕”,获得接近独立应用的显示效果。
安装用户级 launchd 服务:
npm run service:install安装命令会先构建当前源码,然后分别创建 Web 与 Gateway 两个守护作业。它们会在用户登录时自动启动,并在任一组件异常退出后单独重启。运行日志保存在 ~/Library/Logs/CodexWeb/;手动执行重启命令时会先重新构建源码。
常用管理命令:
npm run service:status # 查看状态
npm run service:restart # 重新构建并重启
npm run service:logs # 持续查看日志
npm run service:uninstall # 停止并卸载服务- 不要在路由器上将
3100或8787映射到公网。 - 防火墙应只允许 VPN 网卡或 VPN 地址段访问这两个端口。
CODEX_ALLOWED_ORIGINS不要使用*。- 默认跟随本机 Codex 配置;如果希望网页端更保守,可设置
CODEX_WEB_PERMISSION_MODE=safe。 .env、~/.codex和访问口令不要提交到 Git。- 如果用 HTTPS 反向代理,将
CODEX_SECURE_COOKIE改为true。
App Server 协议随 Codex CLI 版本生成。如需在本机核对最新协议类型,升级 CLI 后执行:
npm run protocol:generate
npm run buildprotocol/ 是本机 Codex CLI 生成的类型定义,仅用于开发时核对审批和事件结构,不会提交到 Git。