快速开始:3 步用 npx 部署 codex-mobile,Linux/Windows/手机全平台 AI 编程指南

原创2026-10-22 23:07:193,298 阅读

快速开始: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 + 密码

部署完成后,你会看到这样的聊天工作台——左侧是项目与会话树,右侧是与桌面版一致的对话输入区(支持 / 唤起技能、模型切换、语音输入):

codex-mobile 聊天界面:项目会话列表与 AI 编程对话输入区

三、分平台部署要点: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 要点:

  1. 不要关闭运行 codexapp 的 Termux 会话;
  2. 在 Android 设置中为 Termux 关闭电池优化;
  3. 保留 Termux 的常驻通知;
  4. 用 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),与聊天输入区的 / 快捷菜单无缝联动:

codex-mobile Skills Hub 界面:技能搜索与已安装技能管理

按住说话的语音听写

Composer 内置"hold to dictate"语音输入:按住麦克风、松手转写、文本自动追加到草稿,手机上打字编程从此解放双手:

codex-mobile 语音听写录音界面:实时波形与转写状态

更多实用能力

  • 📦 项目 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 编程工作台。现在就去试试吧!

登录后查看全文
codex-mobile