做移动端 AI 应用这件事我最近半年几乎是被 Codex 推着在走。接到一个“App 里要带 AI 对话、移动端体验还得拿得出手”的需求时团队手里只有一批 Relay 原型图和半页需求描述没有完整的设计标注、没有后端文档、没有联调环境——放在以前光是把原型图啃成页面结构再手写接口怎么也得两周。现在整个链路变成了Relay 原型图进 Codex前端页面、后端接口、AI 接入、部署脚本一次生成我负责拆任务、看代码、兜底。这篇不是 Codex 的官方教程而是我从一个真实项目里踩出来的工作流。如果你也在做移动端 AI 全栈开发手里有原型图但缺人手和时间想搞清楚 AI Agent 到底能在交付链路上帮你承担多少活这篇文章可以当一份实战参考。里面提到的安装方式、文件结构、复现步骤都是我在机器上实际跑过的有些坑也是真的踩过。先说结论Codex 确实能缩短从原型图到可交付的链路但前提是你要把链路拆清楚、把约束写明白否则它只会给你一堆“看起来很对”的代码。1. 先把链路想清楚Relay 原型图到交付Codex 到底该干哪几份活1.1 为什么是 Codex而不是传统补全工具我身边很多人还在把 AI 编程工具当“高级补全”用让模型在光标后面蹦单词那当然体会不到质变。Codex 跟我之前用的工具最大的区别是它是一个 Agent会自己读仓库、找文件、跑命令、改代码出错了还能根据报错信息自己修。简单说传统工具是给你提词Codex 是替你干活你把任务边界和验收标准给它就行。这套特性放到移动端全栈开发里特别值钱。移动端项目最烦的不是某个页面难写而是横跨前端、后端、AI 服务、构建脚本的杂活太多。以前改一个接口字段要同时动 TypeScript 类型、请求封装、页面状态、后端 DTO一个不漏地改完还得跑测试。Codex 能在一整个仓库上下文里做全局修改这种跨层改动正是它擅长的。现在网上流行“vibe coding”拿一大段模糊的提示词让 AI 乱造我其实不太认同这种玩法。我更偏向带约束的 Spec-Driven Development先把需求拆成规格再让 Codex 照着实现每个任务都有明确的验收条件。当然Agent 越强越需要你把“活儿”拆清楚。我见过不少翻车现场直接甩一句“帮我做个 App”就给 Codex它当然会给你一套看起来完整、实际跑不起来的项目。所以我在项目开始前会跟团队定一条铁律Codex 只负责“执行已拆解的任务”需求分析和任务拆解永远是人来做。你要当好那个“给 AI 派活的人”这比你自己写代码更重要。1.2 Relay 原型图在我这里的定位先解释一下标题里的 Relay。在我们团队里Relay 是设计侧维护原型图的那套平台和约定设计同学会把每个页面、每个状态空态、加载态、报错态、每个交互分支都铺在原型图上。对我这种开发来说Relay 的价值不是“图好看”而是它导出的结构足够完整页面层级、组件关系、字段命名、跳转逻辑都能从里面扒出来。但模型没法直接“看懂”一套原型图系统里的多页面画板。我试过直接把原型图的截图链接丢给 Codex效果很一般它分不清哪个组件属于哪个页面。后来我总结出一个可靠的路径先把 Relay 里的页面导成 PNG 截图再让 Codex 基于这些截图和我补充的文字说明生成一份结构化的页面文档我习惯叫 structure.md包含页面清单、每个页面的元素树、交互事件、需要对接的数据字段。这份文档就是 Codex 往后写代码的唯一事实来源。这一步很关键。它把设计稿这种“人看的东西”转换成了“模型能稳定理解的东西”。结构文档写得越细后面 Codex 生成代码的一次通过率越高。我在项目里还让 Codex 顺手给这份文档加上验收标准比如“登录页需包含手机号、验证码、登录按钮点击后调 /auth/login并处理 401 错误”——这就是后面验收它代码的依据。1.3 整条链路长什么样整条链路我分成五段需求拆解、原型图结构化、前后端代码生成、AI 能力接入、交付前打磨。需求拆解阶段人负责写清楚“要做什么”以及“不做范围”Codex 辅助把它变成任务清单。原型图结构化阶段如上一条说的产出 structure.md。代码生成阶段Codex 按页面粒度逐个生成前端再按接口文档生成后端。AI 能力接入阶段我把大模型接口规范和鉴权信息交给 Codex让它把流式对话、历史上下文、错误降级全接上。交付前打磨阶段主要做移动端性能优化、真机适配、构建产物瘦身。这里要泼一盆冷水这个流程不等于“零开发”。Codex 会把 80% 的重复代码搞定但剩下 20% 的架构决策、边界处理、性能优化恰恰是决定交付质量的部分。后面几章我会按这条链路把我实际操作中的细节和踩过的坑都摊开讲。宁可多说一些具体的命令和文件内容也不写虚的。2. Codex 环境搭建实录安装、鉴权、代理变量与 Monorepo 脚手架2.1 Codex 安装的几种方式与我的选择官方目前提供了桌面应用和 Codex CLI 两条主要路径。桌面应用的好处是有图形界面能直接拖拽截图给它看交互直观CLI 的好处是能跑在终端里方便接进自动化流程而且它天然工作在你的项目目录里读文件、跑命令、看报错都很顺。我的选择是 CLI 为主、桌面应用为辅。安装这块macOS 上最简单的是用 Homebrew一条命令就能装好。如果你本来就是 Node 生态用 npm 全局安装也可以包名是 openai/codex。Windows 和 Linux 官方文档里也有对应的包管理方式具体以你当前 CLI 版本提供的说明为准。我自己的经验是 Homebrew 装的版本更新更及时npm 装的版本则跟 Node 工具链更统一看你的偏好。装完第一步不是写代码而是把鉴权配好。CLI 支持两种方式一种是用 codex login 走浏览器登录授权另一种是直接用 API Key 写进环境变量 OPENAI_API_KEY。如果你所在的团队有统一的网关或代理还可以在配置里指定 base_url让 CLI 走团队网关。这个设计对团队协作很友好因为密钥不用分发到每个人本地直接配网关地址就行。提示我遇到过不止一次“装完 codex 命令找不到”的情况大多是 npm 全局目录没加进 PATH。跑一下 npm bin -g 看看输出目录把它加进 shell 配置就行不用重新安装。2.2 终端网络与环境变量的坑Codex CLI 本质上是把本地代码、你的指令拼装成请求发到远程模型服务。所以终端的网络环境必须能让它顺利访问到 /responses 端点。这里最常见的问题就是本地代理配置。如果你平时调试其他工具习惯给终端设置 http_proxy 和 https_proxyCodex CLI 也会继承这些变量而一旦代理端口写错、鉴权没带上它就会报出类似 cc switch local proxy failed 的错误。这类问题我在第 5 章会单独拉出来讲排查步骤。这里想强调一个容易被忽略的点很多 Mac 用户只在系统设置里开了代理终端默认是不走系统代理的。Codex CLI 运行在终端里所以你需要确认 shell 环境变量是否真的有 HTTP_PROXY / HTTPS_PROXY或者你的代理工具是否提供了终端代理命令行开关。另外一个经验如果网络环境不稳定CLI 会频繁超时重试表现为“感觉 Codex 变笨了”其实它根本没有收到完整响应。我的做法是先把网络链路调通再让项目代码跑起来不然排查问题的时候多个变量混在一起会非常痛苦。2.3 项目脚手架Monorepo 与移动端技术栈选择我当前这个项目用的是 React Native Expo 做移动端Node.js TypeScript 做后端全仓库用 pnpm workspace 管成 Monorepo。选这套组合的理由是Codex 对 TypeScript 生态的训练数据最充分生成代码出错率相对低Expo 又能让真机调试、构建、发布这条链路很顺。目录结构大概是这样的my-app/ apps/ mobile/ # Expo 应用 api/ # Node.js 后端 packages/ shared/ # 共享类型与工具函数 docs/ structure.md # 原型图结构文档 AGENTS.md # Codex 任务说明与约束这个结构的好处是把前后端放进同一个仓库Codex 一次能看到的上下文更完整。shared 目录专门放接口类型和校验函数改一个字段前后端都能同步引用避免“前端说是 string后端实际返回 number”这类的低级问题。初始化脚手架我建议让 Codex 用框架官方命令来创建而不是让它手写配置。比如让 Codex 执行 npx create-expo-app再执行 npm init 初始化 API 服务这样能保证基础工程是官方维护的后续出问题也能在社区找到答案。Codex 自己手搓的 webpack/metro 配置跑起来之后往往是一堆警告。2.4 让 Codex 读懂项目AGENTS.md 的写法Codex 官方支持在项目里放 AGENTS.md 之类的说明文件每次对话时它会自动读取相当于给 AI 一个“项目入职手册”。这个文件特别适合放那些你不想每次重复交代但模型必须知道的东西比如技术栈是什么、目录怎么划分、代码风格要求、哪些目录是生成产物不要改动、测试命令是什么。我一开始嫌麻烦没写结果每开一个新对话都要重新跟 Codex 解释技术栈和目录结构而且它经常忘记前后端代码风格不统一。后来我花二十分钟写了一份 AGENTS.md效果立竿见影生成代码时对目录的认知稳定多了不再出现把 API 路由文件塞进移动端目录这种错误。写 AGENTS.md 有一点要注意描述要具体而不是抽象。不要写“代码要优雅”要写“接口返回类型必须放在 packages/shared 里并用 zod 声明”不要写“注意移动端性能”要写“长列表必须使用 FlatList禁止用 map 渲染大量数据”。模型对具体约束的执行力远高于对抽象口号的执行力。3. 从 Relay 截图到可运行前端移动端适配与性能优化的落地细节3.1 让 Codex 读懂原型图从截图到结构化文档前文说了我习惯先把原型图转成 structure.md。实操时我会先把 Relay 里的页面按流程分组导出 PNG比如“登录注册组”“首页信息流组”“AI 对话组”“个人中心组”一组一个目录文件名用页面命名比如 login.png、home.png、chat.png。然后我会把每个页面配一段需求描述扔给 Codex让它生成结构文档。例如我会跟它说“这是一份截图请识别页面中的 UI 元素输出一个 markdown 页面说明包含元素清单、布局要点、交互事件和数据字段。不要写代码。”这一步产出的 structure.md 等于把设计稿变成了模型可以反复消费的“中间表示”。这个阶段我也会让 Codex 把异常状态写进去加载中长什么样、空数据时显示什么、接口失败有没有 toast。很多 AI 生成的应用看着能用但一断网就白屏、一没数据就卡死根因就是最早的结构文档里没写这些状态。宁可结构文档多 20% 篇幅也不要后续返工。生成前端代码时我一般是按页面粒度提交任务一次只让 Codex 做一个页面读取 structure.md 里对应章节生成页面组件和路由跑 TypeScript 类型检查确认通过后再做下一个。页面之间共享的组件按钮、输入框、列表项我会在第一个页面前先让 Codex 建好避免后面每个页面各写一套样式。3.2 移动端适配光是“能跑”远远不够Codex 生成的页面在浏览器里通常没问题一上真机就露馅。移动端适配不是“把宽度设成 100%”这么简单真实开发里最常遇到的是这四类问题。第一安全区。iPhone 的刘海、底部 Home Indicator 会遮挡内容。我的做法是明确告诉 Codex“使用 SafeAreaView 或 SafeAreaProvider 处理顶部和底部安全区不要在安全区外放可点击元素。”不写这条它生成的页面经常出现底部按钮被手势条盖住一半的情况。第二点击区域。移动端不适合细小的链接和按钮苹果官方建议的最小点击区域是 44x44pt。我会在项目规范里加一条“所有可点击元素最小宽高 44文字按钮也要保证 padding 足够。”这个约束写进 AGENTS.md 之后Codex 生成的按钮观感立刻正常了点错的概率也小了很多。第三尺寸单位。React Native 默认是 pt 逻辑像素不是浏览器里的 CSS 像素。Codex 有时会把网页习惯带进来写出固定 px 字号导致小屏手机上字小到看不清。后来我在规范里加了“字号建议用 14/16/20 三档间距用 4 的整数倍”整体视觉节奏就稳了。第四键盘弹起。移动端表单页在键盘弹起时输入框经常被挡。这个 Codex 基础代码不会主动处理我一般会让它给 ScrollView 或 KeyboardAvoidingView 配好键盘躲避逻辑并在真机上反复测。这几个问题都属于“不真机测根本发现不了”的类型Codex 写不出来只能靠你来补约束。3.3 性能优化从哪几处下手移动端性能优化是个大话题但作为交付链路里的一环我觉得先抓三个性价比最高的点列表渲染、图片加载、包体积。列表这块有个很容易犯的错用 map 渲染长列表。数据一多滑动就卡因为 JS 线程和 UI 线程的活全挤在一起了。React Native 下正确姿势是用 FlatList它自带窗口化只渲染屏幕附近的项目。我会让 Codex 在生成列表时直接用 FlatList并且给每行组件包 React.memo避免父组件状态一变整屏项目全部重渲染。图片是另一个大坑。如果不做缓存用户在信息流里反复滑动每张图都重新加载流量和内存都爆炸。现在一般会配合图片 CDN 的裁剪参数在请求时就按屏幕宽度取合适的尺寸同时用 expo-image 的缓存能力做本地缓存。Codex 默认生成的 Image 组件没有这些处理需要你把这些要求写成明确的规则它才会照着实现。包体积影响的是下载转化率App 动辄上百 MB 没人想装。这个阶段我会让 Codex 分析依赖列表把用不到的 polyfill、图标库、开发依赖从产物里剔除。Expo 和 Metro 都能输出构建分析报告照着报告去删依赖通常能砍掉 20% 以上的体积。别小看这 20%在用户眼里就是“装得快”和“怎么还没下完”的天壤之别。3.4 生成代码后的强制 review 清单让 Codex 生成代码不等于代码可以直接上库。我现在不管任务多急都会在合并前过一遍 review重点看四类问题。一看类型和接口。TypeScript 类型能不能编译通过是最低线另外要抽查 shared 里的类型定义和后端实际的返回结构是否一致AI 有时候会“自己想当然”两边各写一套。二看错误处理。接口失败有没有 catchloading 状态有没有置回用户重复提交有没有防抖或禁用这一步能过滤掉大量“看起来正常、点着点着就崩”的问题。三看状态管理。项目里用全局状态还是服务端缓存Codex 常常会把局部状态随便塞进全局 store导致页面一多内存就涨。我个人倾向于让服务端数据走请求层缓存UI 状态尽量贴近组件减少全局 store 的负担。四看安全与明文。API Key、token 有没有被硬编码进前端代码请求有没有校验AI 生成代码时为了“能跑”经常会把密钥写死在配置里这种我只要在 diff 里看到直接打回。注意Codex 不是审核工具它写代码的能力强但“这个需求到底要不要这么实现”得人来判断。Review 清单不是走流程是真的会拦住 90% 的上线事故。4. 后端与 AI 能力接入流式对话、共享类型与真机联调要点4.1 后端接口设计REST 流式响应的选择现在很多 AI 应用核心不只是“App 能发请求”而是“AI 对话体验要流畅”。移动端 AI 应用的后端我建议一开始就确定数据交互方式是 REST SSE 流式响应而不是等 AI 生成完整文本再一次性返回。你想用户问一句话模型要“思考”好几秒如果整段返回用户面对的是一动不动好几秒的加载转圈体感极差。流式输出让第一个字在几百毫秒内就出现在屏幕上配合光标闪动用户会觉得“它在回我”。这是 AI 类应用体验的关键。后端我用 Node.js Fastify 做接口层数据库先用 PostgreSQL本地开发切 SQLite 兜底。Codex 在这个阶段的工作是根据 structure.md 里的数据字段定义生成数据库表结构、路由、鉴权中间件和基础 CRUD。我要做的是把接口契约想清楚比如登录、历史会话、对话列表、消息详情每个接口的入参出参是什么错误码怎么定义。接口契约我喜欢用 zod 定义并放在 packages/shared 里共享给前端。这样前后端都用同一套 schema 做校验Codex 改代码的时候不容易跑偏。举个简单的例子POST /api/chat 的入参要有 sessionId 和 content返回的流里每块文本带 delta 字段这些共享类型定义好以后前端直接用同款类型解析流式响应省掉了大量对齐成本。4.2 AI 能力接入流式对话与上下文管理接入大模型能力的部分是整个项目里 Codex 最能帮上忙又最容易搞砸的地方。我通常会给 Codex 提供一份简明的模型接口规范OpenAI 兼容格式让它生成一个独立的 service 模块封装“发送会话、接收流式事件、把增量文本转给客户端”这段逻辑。流式接入的实现要点是客户端用 fetch 而不是 EventSource。很多人以为流式只能用 SSE 的 EventSource但对 Post 请求要带认证和 body原生 EventSource 根本支持不了。正确做法是用 fetch 读取 response.body 的 ReadableStream逐段解析数据。Codex 只要理解了这点生成的代码基本能跑通。我也踩过它生成 EventSource 的坑前端接口文档拿过来一看就不是 Post当场返工。上下文管理是另一个大坑。大模型接口的上下文窗口有限我们不能把整段历史都丢给它。我的做法是取最近 N 条消息加上系统提示词组装成请求体如果内容超长就按旧消息优先裁剪。这块逻辑一定要写成明确规则让 Codex 实现否则它只会简单粗暴地拼接全部历史。提示AI 接口请求里超时和网络波动几乎是必然的。一定要让 Codex 在 service 里做“超时重试 熔断降级”重试 2 次间隔指数退避重试失败返回用户可读的错误提示。没人愿意在 AI 聊天页看到英文堆栈。4.3 联调阶段真机访问与开发环境细节前后端都生成得差不多了就该真机联调了。React Native 在 Expo 模式下手机和开发机连同一个 Wi-Fi 就能跑但这里有个经典坑手机访问开发机 API不能写 localhost要写开发机的局域网 IP。所以我会让 Codex 在项目里做一个基于DEV的环境区分配置开发环境 API 地址用局域网 IP从 Expo 的 debuggerHost 里动态解析生产环境用正式域名。这个配置不写清楚很容易出现“模拟器上好好的真机上一请求就失败”的奇怪现象。CORS 也要顺手处理。后端要允许开发环境的来源尤其要走流式接口时预检请求和响应头都得配好。我自己就在联调时栽过页面正常加载但 fetch 流式接口报错排查半天才发现是后端没配跨域浏览器里 GET 能过、POST 带自定义头直接被拦。最后真机调试时性能面板要看两个数JS 线程帧率和内存占用。如果页面滚动时帧率掉到 30 以下优先看长列表是否用了虚拟化如果内存持续上涨优先看是否有定时器没清理、图片大图没有释放。这些是 Codex 不会替你感知的问题只能靠人盯。5. 踩坑记录Codex 报错、代码矛盾与移动端性能排查清单5.1 cc switch local proxy failed while handling codex endpoint /responses这是我在 Codex CLI 场景下高频遇到的一个报错出问题的地方在 Codex 请求 /responses 端点时本地代理链路没有正确转发。字面意思就是本地某个代理切换机制在处理这个请求时失败了Codex 连接不上模型服务。我建议按这个顺序排查第一步确认当前终端能不能正常访问目标服务用 curl 测一下接口看是网络不通还是代理不通第二步确认 HTTP_PROXY/HTTPS_PROXY 之类的环境变量指向的代理端口是否真实可用常有端口写错或服务没启动的情况第三步如果用了代理工具的“增强模式”或证书拦截确认本地 CA 证书是否装好TLS 握手失败也会包装成类似错误信息第四步直接去掉代理变量在纯净网络下跑一次 codex能通就是代理链路的问题。另外Codex CLI 和桌面应用对代理的读取路径不一样桌面应用可能读的是系统代理CLI 读的是终端环境变量。你系统里开了代理不代表终端能用反之亦然。这个报错大概率就是“两端配置不一致”导致的。我自己的习惯是把代理相关的配置固定成脚本换网络环境时一条命令切换避免同一个终端里多个代理工具互相打架。5.2 Codex 生成的代码前后矛盾怎么办Codex 单次生成的质量通常不错但项目一大、文件一多就会出现“这次生成的 A 页面引用了上次还没定义的 B 组件”“共享类型改了页面里老用法没同步”这类前后不一致。我的解法是把任务拆得足够小并且每一步都留“检查点”每完成一个页面或一个模块先跑一遍 TypeScript 类型检查、lint、单元测试通过了再进入下一步。如果出现矛盾不要在一个对话里无限纠缠直接把相关文件路径和报错信息粘贴给 Codex让它先定位再改比它自己乱猜高效得多。另外强烈建议用上 AGENTS.md 和维护一份任务记录。Codex 每次开工前读一下这份记录就能少犯“重复创建已存在的工具函数”“把另一个文件里的能力重写一遍”这类毛病。说白了AI 的记忆是零散的你要用文档给它做外置记忆这是整个协作流程里最容易被忽略但回报最高的一步。5.3 移动端性能优化排查顺序性能问题不像功能问题那样有具体报错它更像“慢”“卡”“烫”得靠清单排查。我整理的移动端性能排查顺序从易到难大致是这样。先查包体积。看构建产物多大有没有把整个图标库、未用到的 SDK 打包进去。再查启动时间。App 启动时有没有同步执行网络请求、大文件解压、复杂动画初始化。接着查列表滑动帧率。打开一个数据密集页面快速滑动用帧率工具看掉帧情况同时观察内存曲线有没有持续上升。最后查耗电与发热。源于后台定时器、定位监听、推送通道长连接没有合理释放。这里有个原则优化要在“数据量大 真机弱网”的环境下测。很多项目在模拟器和开发机上毫秒级响应一到用户手上就卡就是因为测试条件太好。我在交付前会专门让 Codex 生成一批大数据量的 mock 数据用真机压一遍滑动和输入再根据帧率和内存数据决定下一步优化方向。性能优化这种事没有数据支撑就是在猜猜来猜去最后还是得回到工具面板上看数据。5.4 关于接入替代模型与兼容接口的一次尝试Codex 官方服务对大部分开发者来说很方便但团队里也有人问过“能不能接其他模型跑 Codex CLI”。这个问题其实是可行的Codex CLI 在较新版本里支持通过配置自定义模型提供商只要目标服务开放的是兼容接口协议可以在配置里增加 provider指定 base_url、模型名和鉴权方式。我实际试过一次把 CLI 指向 DeepSeek 这类兼容接口的模型服务基本的代码生成、文件修改流程能跑通。但不同模型在指令遵循和代码生成能力上有差异Codex 官方模型的“自动执行命令、自己看报错”这类 Agent 能力不一定能在替代模型上完整复现。所以我的建议是如果你只是测试 API 兼容性、或者团队有数据不能出内网的合规要求可以尝试替代模型如果你要的是一整套完整的 Agent 开发体验那官方服务或者与官方能力对齐的方案更稳妥。这个结论是实测得来的不是理论推演。最后说一点个人体会。Codex 这套工具链真正改变的不是“写代码的速度”而是“一个人能 hold 住的项目规模”。以前移动端全栈这种活前端、后端、AI 三摊事至少要三个人各管一摊现在一个人加一个 Agent能把全链路跑通到可交付状态。但这个前提是你自己得真的懂这条链路知道哪里容易翻车、哪些代码必须人工 review。我现在的工作方式更像是“产品经理 架构师 测试”三位一体Codex 是我的主力执行者。它会写 CRUD、会搭页面、会处理流式响应但它不会替你想清楚“用户为什么要这个功能”“这个接口失败时用户看到什么”。想明白这些再用好 Codex你会发现 AI 编程时代真正稀缺的还是对业务和工程质量有判断力的人。如果这篇文章能帮你少踩几个坑我就挺满足了。后续我也打算把 Relay 原型图自动生成结构文档的模板整理出来到时候再跟你们细聊。