快速开始:3 步用 npx 部署 codex-mobile,Linux/Windows/手机全平台 AI 编程指南
快速开始:3 步用 npx 部署 codex-mobile,Linux/Windows/手机全平台 AI 编程指南
codex-mobile 是一款让 Codex 桌面版体验"浏览器化"的开源 Web UI 工具:只需一条 npx 命令,就能在 Linux、Windows 或 Android(Termux)上启动本地 Web 服务,把完整的 AI 编程对话界面、Skills Hub、语音输入和远程隧道能力装进浏览器。本文是一份面向新手的完整部署指南,3 个步骤即可全平台跑通。
一、部署前 30 秒:了解 codex-mobile 是什么
codex-mobile(npm 包名 @brutalstrikedevs/codexapp)本质上是一个轻量级桥接器:浏览器通过 HTTP/WebSocket 连接到它,它再通过 RPC 调用背后的 Codex App Server。
┌─────────────────────────────┐
│ 浏览器(桌面 / 手机) │
└──────────────┬──────────────┘
│ HTTP/WebSocket
┌──────────────▼──────────────┐
│ codexapp(Express + Vue) │
└──────────────┬──────────────┘
│ RPC/Bridge
┌──────────────▼──────────────┐
│ Codex App Server │
└─────────────────────────────┘
✅ 部署前只需满足 3 个条件:
| 条件 | 说明 |
|---|---|
| Node.js 18+ | 唯一硬性依赖,node -v 查看版本 |
| Codex app-server 环境 | 工具会自动引导 codex login 完成登录 |
| 浏览器 | 能访问主机与端口即可(本机、局域网或隧道) |
二、3 步部署:从 0 到打开 codex-mobile 聊天界面
第 1 步:确认 Node.js 版本
在终端执行:
node -v # 应显示 18 或更高版本
若版本过低,先升级 Node.js 再继续。
第 2 步:一条 npx 命令完成部署
无需全局安装,直接运行:
npx @brutalstrikedevs/codexapp
命令会自动拉起本地 Web 服务,并默认启动 cloudflared 隧道,把隧道 URL、终端二维码和密码一起打印到控制台,手机扫码即可直连。
第 3 步:打开浏览器访问界面
- 本机访问:
http://localhost:18923 - 局域网访问:其他设备打开同一网络下该主机的对应端口
- 远程访问:使用启动时打印的隧道 URL + 密码
部署完成后,你会看到这样的聊天工作台——左侧是项目与会话树,右侧是与桌面版一致的对话输入区(支持 / 唤起技能、模型切换、语音输入):
三、分平台部署要点:Linux / Windows / Android
Linux 与 Windows:几乎零配置
# Linux / Windows PowerShell 通用
node -v
npx @brutalstrikedevs/codexapp
如果你的 Provider 或 AI 网关已完成鉴权,不想让它在启动时强制 codex login,可加上 --no-login 参数:
npx @brutalstrikedevs/codexapp --no-login
Android(Termux):让服务在后台稳定存活
pkg update && pkg upgrade -y
pkg install nodejs -y
npx @brutalstrikedevs/codexapp
termux-wake-lock # 可选但推荐
📱 手机端保活 4 要点:
- 不要关闭运行
codexapp的 Termux 会话; - 在 Android 设置中为 Termux 关闭电池优化;
- 保留 Termux 的常驻通知;
- 用 Android 浏览器打开启动时显示的 URL。
iPhone / iPad:通过 Tailscale Serve 走 HTTPS
iOS 对安全上下文较敏感,推荐私有 HTTPS 方案:
npx @brutalstrikedevs/codexapp --no-tunnel --port 5900
tailscale serve --bg 5900
然后访问 https://<your-machine>.<your-tailnet>.ts.net。该方案实测支持 Safari 访问、"添加到主屏幕",以及应用内置的语音听写功能。
四、常用启动参数速查表
参数定义见 src/cli/index.ts,新手重点看下面这几个:
| 参数 | 作用 | 适合场景 |
|---|---|---|
-p, --port <port> |
指定监听端口(默认 5900) | 解决端口冲突 |
--no-tunnel |
禁用 cloudflared 隧道 | 仅本机/局域网使用 |
--no-login |
跳过自动 Codex 登录 | 已有鉴权的 Provider |
--no-password |
关闭密码保护 | 纯本地可信环境 |
--open-project <path> |
启动时直接打开指定项目目录 | 多项目快速切换 |
--sandbox-mode <mode> |
选择沙箱模式(read-only / workspace-write / danger-full-access) | 控制 AI 写文件权限 |
五、部署完成:codex-mobile 还能带给你什么
开箱即用的 Skills Hub
启动后左侧导航即可进入 Skills Hub,搜索、安装和管理社区技能(Skills),与聊天输入区的 / 快捷菜单无缝联动:
按住说话的语音听写
Composer 内置"hold to dictate"语音输入:按住麦克风、松手转写、文本自动追加到草稿,手机上打字编程从此解放双手:
更多实用能力
- 📦 项目 ZIP 导出/导入:连同
.codex-project/chats/下的会话历史一起迁移,详见 llm-wiki/raw/features/project-zip-portability.md - 🤖 可选 Telegram Bot 桥接:在机器人里发消息即可转发到对应会话,配置方法见 README.md 中 "Telegram Bot Bridge" 小节
- 🖥️ 内嵌终端、定时任务(Cron Automations)、Git 分支切换与回滚等能力,均可在 tests/ 目录下的功能文档中找到说明
六、常见问题快速修复
| ❌ 问题 | ✅ 修复方法 |
|---|---|
| 端口被占用 | 用 -p 换一个空闲端口,或停止旧进程 |
npx 执行失败 |
升级 npm / Node.js 后重试 |
| Termux 安装失败 | 先 pkg update && pkg upgrade,再重装 nodejs |
| 其他设备打不开 | 检查防火墙、绑定地址与局域网路由 |
| 手机浏览器断连 | 确认 Termux 未被系统杀死,必要时重跑启动命令 |
七、进阶:克隆仓库从源码运行
如果想参与二次开发或定制界面,可以克隆仓库(前端为 Vue 3 + Vite,CLI 入口为 src/cli/index.ts):
git clone https://gitcode.com/gh_mirrors/co/codex-mobile
cd codex-mobile
npm install
npm run dev
仓库内还有完整的代理规格 ProxySpec.md、npm 发布流程 docs/publishing.md 与协议 Schema 文档 documentation/APP_SERVER_DOCUMENTATION.md,方便深入阅读。
💡 小结:npx @brutalstrikedevs/codexapp → 拿到端口/隧道 URL → 浏览器打开,3 步即可拥有跨 Linux、Windows、Android 的统一 AI 编程工作台。现在就去试试吧!


