Skip to content
begincodePublic

About

Codex Web Console 是一个适配手机端的本地 Codex Web 控制台。 可以远程查看本机项目与历史任务、继续对话、接收流式回复、处理操作审批,并安全管理访问口令。

Resources

Stars

1 star

Watchers

0 watching

Forks

Repository files navigation

Codex Remote Console

一个面向个人使用的移动端优先 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

可以使用手机浏览器的“添加到主屏幕”,获得接近独立应用的显示效果。

macOS 后台守护

安装用户级 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。

Codex 升级

App Server 协议随 Codex CLI 版本生成。如需在本机核对最新协议类型,升级 CLI 后执行:

npm run protocol:generate
npm run build

protocol/ 是本机 Codex CLI 生成的类型定义,仅用于开发时核对审批和事件结构,不会提交到 Git。

About

Codex Web Console 是一个适配手机端的本地 Codex Web 控制台。 可以远程查看本机项目与历史任务、继续对话、接收流式回复、处理操作审批,并安全管理访问口令。

Resources

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages