1. 背景与核心概念1.1 Codex 到底是什么先回答一个很多人第一次听到 Codex 时的疑问它和 ChatGPT、Cursor 这类工具有什么区别Codex 是 OpenAI 推出的 AI 编程智能体它不是一个“聊天窗口 代码补全”那么简单。Codex 更像一个能够理解你项目目录、直接读取文件、执行命令、修改代码、运行测试的“AI 工程师”。你可以把它理解成住在你电脑里的一个同事你说需求它动手改代码跑命令给你看结果遇到问题还会自己排查。和传统 AI 聊天工具相比Codex 有几个关键差异它能读取当前项目里的文件结构和内容而不是只靠你粘贴代码片段。它能直接执行终端命令比如安装依赖、运行构建、启动服务。它能修改多个文件并告诉你改了哪些地方。它的使用方式更像“任务下发”而不是“一问一答”。所以用 Codex 做项目并不是简单地把代码拷来拷去而是从需求描述、代码生成、本地联调到部署发布整个流程都可以在 AI 的协助下完成。这也是本文标题里“不会写代码也能做项目”的核心原因。1.2 AI 剧本杀项目拆解剧本杀又叫“谋杀之谜”是一类角色扮演推理游戏。玩家各自拿到一个角色剧本通过对话、搜证、推理找出真相。线下剧本杀需要一个主持人DM来控场、发线索、推进剧情而线上 AI 剧本杀则可以让 AI 来承担主持人和 NPC非玩家角色的职责。一个最小可用的 AI 剧本杀 Web 应用至少需要包含以下模块模块功能说明剧本管理保存剧本、角色、线索、结局等数据房间机制创建房间、加入房间、开始游戏对话系统玩家与 AI 主持人或 NPC 对话推理投票玩家提交推理结论、投票找出凶手前端界面剧本选择、角色选择、对话页面、结果页如果靠手写代码这个项目哪怕是一个简化版也需要后端接口开发、前端页面开发、数据库建模、联调部署等一整套工作。但对于 AI 辅助开发来说我们就可以把这些模块拆成一个一个的“任务”交给 Codex 逐步完成。1.3 为什么这个项目适合用 Codex 完成我选择“AI 剧本杀”作为案例是因为它非常适合展示 AI 编程的完整链路一是技术栈可以很简单。后端用 FastAPI 或 Node.js 这种轻量框架前端用 Vue 或 React数据库用 SQLite 或 PostgreSQL都是 AI 非常熟悉的领域生成质量高。二是业务逻辑足够清晰。剧本杀的核心逻辑是“对话 状态管理 投票”没有复杂的算法没有高并发的性能压力适合作为 AI 编程实战项目。三是容易演示“自动发布上线”。整个项目可以打包成 Docker 镜像通过 GitHub Actions 自动部署到云服务器完整跑通 DevOps 流程。如果你完全不懂代码做完这个项目后你也能建立起对前后端分工、API 接口、部署流程的直观认知。如果你本身是开发者这篇文章则能帮你掌握用 Codex 提效的完整方法。2. 环境准备与版本说明2.1 环境清单在开始之前先准备好以下环境。版本需要根据你的项目实际情况调整本文示例以常见环境为例重点演示配置思路。环境项说明操作系统Windows 10/11、macOS、Ubuntu 均可Codex CLI需要安装并登录 OpenAI 账号编程语言Python 3.10 或 Node.js 18数据库开发环境使用 SQLite生产环境建议 PostgreSQL前端构建Vite Vue 3容器化Docker部署平台云服务器或其他可运行 Docker 的环境如果你在 Windows 上开发建议在 PowerShell 或 Windows Terminal 中操作如果你在 macOS 或 Linux 上开发直接用系统终端即可。2.2 安装 Codex CLICodex 的常见使用方式有两种一种是终端 CLI命令行工具另一种是 IDE 插件。安装 CLI 的常见方式是使用 npmnpm install -g openai/codex安装完成后先查看版本确认安装成功codex --version如果是第一次使用需要先登录codex login登录过程会在浏览器中打开授权页面按提示完成授权即可。如果你是在服务器等无浏览器环境使用也可以将密钥配置到环境变量中具体配置方式请以官方文档为准。如果你使用 VS Code也可以在扩展市场搜索 Codex 插件。需要注意的是Codex 插件和 CLI 之间存在关联当你启动插件时它需要找到 Codex CLI 的可执行文件。如果找不到就会出现文章后面要讲的unable to locate the codex cli binary报错。所以建议先完成 CLI 安装和登录再安装 IDE 插件。2.3 初始化项目目录这里我们创建一个名为ai-script-killer的项目目录。你可以手动创建也可以让 Codex 帮忙生成。mkdir ai-script-killer cd ai-script-killer我们计划采用前后端分离的结构ai-script-killer/ ├── backend/ # 后端 FastAPI 项目 ├── frontend/ # 前端 Vue 3 Vite 项目 ├── docker-compose.yml └── README.md如果你暂时不知道这些文件里应该写什么没关系这正是 Codex 要完成的工作。3. Codex 的核心用法与提示词设计3.1 在终端和 IDE 中使用 CodexCodex CLI 的交互模式非常简单。在项目目录下启动codexEntering 交互界面后你可以直接输入自然语言需求。Codex 会先分析当前项目结构然后给出执行计划并询问你确认后执行操作。举一个最简单的例子。在空目录backend中启动 Codex输入在这个目录下创建一个 FastAPI 项目提供 /health 健康检查接口并输出 requirements.txtCodex 会自动创建main.py写入 FastAPI 代码生成requirements.txt然后告诉你如何启动。你也可以使用非交互模式把需求作为参数传给它codex 创建一个 FastAPI 项目提供 /health 健康检查接口在日常使用中交互模式更适合复杂任务因为你可以根据 Codex 的执行结果动态调整方向非交互模式适合已经明确的小任务。3.2 把需求拆成可执行的 Prompt用 Codex 做项目最关键的能力不是“会聊”而是“会拆任务”。一个模糊的大需求比如“帮我做一个剧本杀网站”Codex 往往不知道该从哪里下手。但如果你把它拆成下面这样的小任务Codex 的执行成功率和代码质量都会高很多创建后端项目骨架配置数据库连接。创建剧本表、角色表、房间表和线索表。编写创建房间接口、加入房间接口、开始游戏接口。编写对话接口调用大模型返回 NPC 回复。投票接口统计投票结果。编写前端页面做成响应式布局。前后端联调修复跨域问题。编写 Dockerfile 和部署脚本。每一步都对应一个明确的交付物Codex 就像一个很听话的实习生你给的任务越清楚它的产出越稳定。3.3 让 Codex 写代码时的约束规则在给 Codex 下达任务时建议在 Prompt 中明确以下约束信息技术栈明确使用什么框架、什么语言避免它自己发挥。文件路径明确代码要放在哪个文件方便后续维护。接口协议明确请求方法、请求参数、返回格式。数据模型给出关键表的字段。非目标告诉它“本次不需要实现什么”防止过度设计。举个例子在 backend/app/main.py 中新增一个 POST /api/room 接口 接收 JSON 参数 { room_name: string, player_name: string } 返回 { room_id: string, player_id: string }。 不需要做登录鉴权不需要考虑分布式注册中心。这种写法非常实用。相比空泛的“帮我写个创建房间的接口”这种约束明确的 Prompt 会极大减少返工。4. 实战用 Codex 实现 AI 剧本杀前后端4.1 项目整体结构最终的代码结构大致如下ai-script-killer/ ├── backend/ │ ├── app/ │ │ ├── main.py # FastAPI 入口 │ │ ├── models.py # 数据模型 │ │ ├── schemas.py # 请求响应模型 │ │ ├── api/ │ │ │ ├── room.py # 房间相关接口 │ │ │ └── game.py # 游戏对话相关接口 │ │ └── core/ │ │ └── llm.py # 大模型调用 │ ├── requirements.txt │ └── Dockerfile ├── frontend/ │ ├── src/ │ │ ├── views/ │ │ │ ├── Home.vue # 首页 │ │ │ ├── Room.vue # 房间/游戏页 │ │ │ └── Result.vue # 结果页 │ │ ├── api/ │ │ │ └── index.js # 请求封装 │ │ └── App.vue │ ├── package.json │ ├── vite.config.js │ └── Dockerfile ├── docker-compose.yml └── README.md下面我们来看如何通过 Codex 一步步把这个结构填满。4.2 用 Codex 生成后端 API先创建后端项目。在backend目录下启动 Codexcd backend codex发送第一条任务当前目录为空。请创建一个 FastAPI 项目要求如下 1. 新建 app/main.py包含 FastAPI 应用实例。 2. 使用 SQLAlchemy 连接 SQLite 数据库数据库文件为 ./ai_script.db。 3. 创建三个模型Script剧本、Room房间、Player玩家。 Script 字段id, title, story, create_time Room 字段id, script_id, status, create_time Player 字段id, room_id, name, role, is_host 4. 提供 /api/room/create 接口创建房间并添加房主玩家。 5. 提供 /api/room/join 接口加入房间。 6. 在 requirements.txt 中列出依赖。这个任务已经非常具体Codex 会根据这些约束生成代码。生成完成后它会提示你安装了哪些依赖、如何启动。一个简化版本的后端接口代码大致长这样# 文件路径backend/app/main.py from fastapi import FastAPI, Depends, HTTPException from sqlalchemy.orm import Session from app import models, schemas from app.database import SessionLocal, engine models.Base.metadata.create_all(bindengine) app FastAPI(titleAI Script Killer API) def get_db(): db SessionLocal() try: yield db finally: db.close() app.post(/api/room/create, response_modelschemas.RoomOut) def create_room(payload: schemas.RoomCreate, db: Session Depends(get_db)): room models.Room(script_idpayload.script_id, statuswaiting) db.add(room) db.commit() db.refresh(room) player models.Player( room_idroom.id, namepayload.player_name, rolehost, is_hostTrue, ) db.add(player) db.commit() db.refresh(player) return schemas.RoomOut(room_idroom.id, player_idplayer.id, statusroom.status)这段代码是“结果示例”实际由 Codex 生成的文件内容不会和你完全一样但整体逻辑是相通的。你不需要手写这段代码Codex 会帮完成但你需要有能力看懂 Codex 生成的结果并判断是否满足需求。接下来继续给 Codex 发送对话接口任务在 backend/app 下新增 api/game.py实现对话接口 POST /api/game/chat。 这个接口接收 { room_id, player_id, message }返回 { reply }。 reply 由大模型生成调用 core/llm.py 中的 function call_llm(messages) 你只需要写好调用逻辑不需要实现真实的 LLM 调用先预留函数占位。这一步之后后端就具备了最核心的接口。其他的“加入房间”“获取剧本列表”“投票”等接口可以继续按同样的方式逐个下发任务。4.3 用 Codex 生成前端页面后端完成之后回到项目根目录创建前端项目cd ../frontend codex任务可以这样写当前目录为空。请基于 Vue 3 Vite 创建一个前端项目。 1. 使用 npm 初始化项目安装 vue、vue-router、axios。 2. 创建 Home.vue展示剧本列表点击“开始游戏”后拿到 room_id 并跳转 Room 页面。 3. 创建 Room.vue展示剧本信息、玩家列表、对话输入框。 调用 POST /api/room/create 创建房间调用 POST /api/game/chat 发送消息。 4. 配置 vite.config.js将 /api 请求代理到 http://localhost:8000。 5. 页面样式使用简洁的暗色卡片风格。Codex 会初始化前端项目并生成对应的 Vue 组件。下面是一个简化版的对话区组件!-- 文件路径frontend/src/components/ChatPanel.vue -- template div classchat-panel div v-for(msg, index) in messages :keyindex classmessage span classrole{{ msg.role }}/span span classcontent{{ msg.content }}/span /div div classinput-row input v-modelinput placeholder输入你的推理或发言 keyup.entersend / button clicksend发送/button /div /div /template script setup import { ref } from vue; import axios from axios; const props defineProps({ roomId: String, playerId: String, }); const messages ref([]); const input ref(); async function send() { if (!input.value.trim()) return; const { data } await axios.post(/api/game/chat, { room_id: props.roomId, player_id: props.playerId, message: input.value, }); messages.value.push({ role: 玩家, content: input.value }); messages.value.push({ role: AI, content: data.reply }); input.value ; } /script这里需要提醒的是v-model、ref、defineProps这些 Vue 语法并不需要你完全理解但你应该能从 Codex 的上下文说明中看出这个文件的职责。Codex 生成完代码后通常会在终端给出运行方式和文件清单你需要对照做一次人工确认。4.4 本地联调与验证前后端代码都生成后先启动后端cd backend pip install -r requirements.txt uvicorn app.main:app --reload --port 8000再启动前端cd frontend npm install npm run dev浏览器打开 Vite 输出的地址比如http://localhost:5173你应该能看到首页。选择剧本、创建房间、进入对话页面发送消息后能看到 AI 的回复。如果前端页面能打开但接口调用失败最常见的两个原因是跨域问题。请求地址不对。跨域问题可以在后端 FastAPI 中启用 CORSMiddleware或者在前端 Vite 中配置代理。Codex 生成的代码一般会处理其中一种方式。如果你使用的是 Vite 代理那么前端请求应该使用相对路径/api/...而不是写死http://localhost:8000/api/...。5. 自动发布上线从本地到服务器5.1 为项目生成 Docker 配置本地联调通过后下一步就是把项目自动化发布到服务器。这里采用 Docker Compose 的方式把前端和后端分别打包成镜像。后端 Dockerfile 示例# 文件路径backend/Dockerfile FROM python:3.11-slim WORKDIR /app COPY requirements.txt . RUN pip install --no-cache-dir -r requirements.txt COPY . . EXPOSE 8000 CMD [uvicorn, app.main:app, --host, 0.0.0.0, --port, 8000]前端 Dockerfile 示例# 文件路径frontend/Dockerfile FROM node:18-alpine AS build WORKDIR /app COPY package*.json ./ RUN npm install COPY . . RUN npm run build FROM nginx:stable-alpine COPY --frombuild /app/dist /usr/share/nginx/html COPY nginx.conf /etc/nginx/conf.d/default.conf EXPOSE 80前端 nginx 配置需要处理单页应用路由和 API 代理# 文件路径frontend/nginx.conf server { listen 80; location / { root /usr/share/nginx/html; index index.html; try_files $uri $uri/ /index.html; } location /api/ { proxy_pass http://backend:8000; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; } }最后编写docker-compose.yml# 文件路径docker-compose.yml version: 3.8 services: backend: build: ./backend container_name: script-backend restart: always environment: - DATABASE_URLsqlite:///./ai_script.db volumes: - ./backend/data:/app/data ports: - 8000:8000 frontend: build: ./frontend container_name: script-frontend restart: always depends_on: - backend ports: - 80:80这些配置文件同样可以交给 Codex 生成。任务描述如下为这个项目编写 Docker 配置 1. backend 使用 python:3.11-slim 镜像。 2. frontend 使用 node:18 构建再用 nginx 托管 dist。 3. nginx 需要将 /api 反向代理到 backend 服务。 4. 编写 docker-compose.yml后端暴露 8000前端暴露 80。5.2 使用 GitHub Actions 自动化部署要让“自动发布上线”名副其实不能每次手动登录服务器执行 docker compose。我们可以通过 GitHub Actions 实现“推送代码到主分支 → 自动构建镜像 → 服务器拉取并重启”。首先将项目推送到 GitHub 仓库然后在仓库的 Settings → Secrets 中配置服务器登录信息Secret 名称说明SERVER_HOST服务器 IP 或域名SERVER_USERSSH 登录用户名SERVER_SSH_KEYSSH 私钥接着创建 workflow 文件# 文件路径.github/workflows/deploy.yml name: Deploy AI Script Killer on: push: branches: - main jobs: deploy: runs-on: ubuntu-latest steps: - name: Checkout uses: actions/checkoutv4 - name: Deploy to Server uses: appleboy/ssh-actionv1.0.3 with: host: ${{ secrets.SERVER_HOST }} username: ${{ secrets.SERVER_USER }} key: ${{ secrets.SERVER_SSH_KEY }} script: | cd /opt/ai-script-killer git pull origin main docker compose up -d --build这个 workflow 的含义是只要 main 分支有新的提交GitHub 就会通过 SSH 登录服务器拉取最新代码然后重新构建并启动容器。这个流程演示了最基础的 CI/CD 能力。它并不是最安全的方案比如没有做健康检查、没有处理容器回滚但对于一个从零开始的 AI 项目来说已经足够让你体会到“代码写完自动上线”的完整链路。5.3 上线后的验收清单部署完成后可以做一轮简单的验收打开服务器公网 IP 或域名能否看到首页创建房间、加入房间、发送消息是否正常如果使用了数据库重启容器后数据是否还在访问/api/health或类似健康检查接口是否返回 200查看容器日志是否有报错docker compose logs -f注意生产环境部署时请务必把敏感配置移出代码文件。比如大模型 API Key、数据库连接串等应该通过环境变量注入而不是写死在代码或 docker-compose.yml 中。你可以在服务器上创建.env文件并在 docker-compose.yml 中引入。6. 常见问题与排查思路在实际使用 Codex 和部署项目的过程中会有几个高频问题。下面把现象、原因和解决思路整理成表格并展开说明。问题现象常见原因解决思路Codex 插件启动报 unable to locate the codex cli binary插件找不到 codex 可执行文件安装 CLI或在设置中指定 codex_cli_pathcodex endpoint /responses 请求代理失败Codex 设置了本地代理或网络环境异常检查网络、关闭多余代理确认接口地址正确提示 model is not supported当前 Codex 可用的模型列表与账号不匹配确认账号可用模型升级版本或切换模型前端访问后端接口 404nginx 代理路径或后端路由路径不一致检查 /api 前缀和代理配置页面刷新后 404SPA 路由没有回退到 index.html配置 nginx try_files容器启动后端口冲突本机已有服务占用 80/8000 端口修改映射端口或停掉旧服务6.1 unable to locate the codex cli binary这是 Codex IDE 插件最常见的报错之一。报错信息很直白插件找不到 Codex CLI 的可执行文件。解决思路确认已经全局安装 CLInpm install -g openai/codex。在终端中执行codex --version确认命令可用。如果命令可用但插件仍报错需要在 IDE 插件设置中手动指定 CLI 路径。比如在 mac 上路径可能是/usr/local/bin/codex在 Windows 上可能是C:\Users\你的用户名\AppData\Roaming\npm\codex.cmd。设置好路径后重启 IDE。要注意不同版本、不同系统的路径不完全一样遇到报错时先用where codexWindows或which codexmacOS/Linux确认实际路径。6.2 codex endpoint /responses 代理错误这条报错通常是网络环境或代理配置引起的。Codex 在调用 API 时会通过本地代理转发请求如果代理配置不正确就会出现类似cc switch local proxy failed while handling codex endpoint /responses的错误。解决思路检查系统代理设置关闭不必要的全局代理。检查 Codex 配置文件中的代理参数确保代理地址和端口正确。查看 Codex 日志确认具体的失败原因。如果你的网络环境本身无法访问 API需要先解决网络连通性而不是修改代码。6.3 model is not supported这个错误表示当前账号或当前 Codex 版本不支持你指定的模型。比如错误信息中出现gpt-5.6-sol model is not supported说明配置里指定了一个 Codex 不能使用的模型名。解决思路在 Codex 配置中检查模型参数改为官方支持的模型。更新 Codex 到最新版本新版本通常会同步最新的模型列表。如果使用自定义 base_url 或网关需要确认网关是否支持该模型。查看官方文档确认当前账号可使用的模型范围。这里要特别提醒模型名称变化较快不要照搬任何教程里的模型名要以你实际环境中codex --version和官方文档为准。6.4 前端接口请求失败如果前端页面能打开但发消息无响应优先用浏览器开发者工具查看 Network 面板请求是否发出请求地址是否正确是绝对地址还是相对地址返回状态码是 404、500 还是 CORS 错误后端日志有没有打印异常如果是在本地开发环境建议优先使用 Vite 代理// 文件路径frontend/vite.config.js import { defineConfig } from vite; import vue from vitejs/plugin-vue; export default defineConfig({ plugins: [vue()], server: { port: 5173, proxy: { /api: { target: http://localhost:8000, changeOrigin: true, }, }, }, });这样前端页面里的axios.post(/api/...)会被自动转发到后端服务也避免了跨域问题。6.5 部署后页面白屏部署后打开网站白屏通常是以下原因前端构建时访问了错误的后端地址导致打包后的 JS 无法请求 API。nginx 没有正确读取到dist目录。SPA 路由刷新后 404看起来像白屏。排查步骤在服务器上执行docker compose logs frontend查看 nginx 日志。进入前端容器检查/usr/share/nginx/html下是否有index.html和静态资源。直接访问http://服务器IP/观察是否正常。如果刷新后白屏检查 nginx 的try_files配置。7. 最佳实践与工程建议7.1 不要追求一次生成全量代码我在这个项目里最大的感受是Codex 虽然能一口气生成很多代码但一次性让它完成整个系统反而不容易控制质量。更推荐的做法是“小步快跑”一次只实现一个功能模块。每次生成后先运行验证。再把下一次需求追加给它。这样做的好处是如果某一步生成的代码有问题你可以很快定位到是哪个任务导致的而不是在几万行代码里找 Bug。7.2 Prompt 数量化、结构化给 Codex 写 Prompt本质上和给开发团队写需求文档类似。一个结构好的 Prompt通常包含目标这一步要完成什么。约束用什么技术栈放在哪个目录。输入接口需要接收哪些参数。输出期望的返回结构。边界这一步不需要做什么。如果把“做一个登录页面”改成“在 frontend/src/views/Login.vue 中创建登录页面使用手机号和密码登录提交到 POST /api/auth/login成功后跳转到首页”Codex 写出来的代码会精准很多。7.3 人工检查的五个安全点使用 AI 编程不等于可以完全脱离人工审查。以下几个地方建议无论如何都要自己看一遍密钥泄露检查是否有 API Key、密码被写进代码。权限漏洞检查创建房间、修改数据等接口是否有越权隐患。输入校验检查用户输入是否可能注入恶意内容。数据库操作检查删除、更新类的操作是否使用了 WHERE 条件。依赖安全安装依赖后执行npm audit或pip-audit查看已知漏洞。尤其是涉及生产环境、用户数据、支付等功能时一定要在测试环境验证通过后再发布并且遵循最小权限原则不要给应用过高的系统权限。7.4 从“AI 生成项目”到“AI 参与运维”Codex 的价值不应该止步于“生成代码”。当你具备了 AI 辅助开发的流程后可以让它承担更多工作让 Codex 解释它生成的代码。让它为项目补测试用例。让它写部署文档。让它根据报错日志分析问题。这样一来AI 就成了你团队里的一个“全栈工程师”。即使你平时主要写前端或者主要写后端也可以在另一个陌生的技术领域快速落地。8. 总结与下一步学习路线通过这个 AI 剧本杀项目主要掌握了三件事第一Codex 不是简单的代码生成器而是一个可以操作文件、运行命令、迭代修改代码的 AI 智能体。你的角色从一个“写代码的人”变成了“下发任务和控制质量的人”。第二一个完整的前后端分离项目可以拆分成后端 API、前端页面、Docker 配置、自动部署等多个阶段每个阶段都可以由 AI 辅助完成。关键不是会不会写代码而是会不会把需求描述清楚。第三AI 生成代码之后人工审查仍然是不可省略的环节。安全、权限、密钥管理、依赖安全这些问题AI 不会自动替你负责你需要具备基本的安全意识和排查能力。接下来如果你想继续深入可以从这几个方向入手学习 FastAPI 基础理解路由、依赖注入和数据库操作。学习 Vue 3 的响应式原理理解前端组件通信。学习 Docker 和 Docker Compose掌握容器化部署。学习 GitHub Actions尝试编写更完善的 CI/CD 流水线。研究如何把大模型接入业务逻辑比如角色扮演提示词设计。如果你也是从零开始接触 AI 编程建议先按照本文的流程把一个小项目完整跑通。哪怕只是用一个晚上让 Codex 帮你从空目录生成一个能打开、能访问、能部署的小应用也比反复看教程更有效果。动手做一遍之后你会发现自己对前后端协作、接口设计、部署流程的理解会提升一个台阶。
Codex AI编程智能体实战：从零构建AI剧本杀全栈项目
1. 背景与核心概念1.1 Codex 到底是什么先回答一个很多人第一次听到 Codex 时的疑问它和 ChatGPT、Cursor 这类工具有什么区别Codex 是 OpenAI 推出的 AI 编程智能体它不是一个“聊天窗口 代码补全”那么简单。Codex 更像一个能够理解你项目目录、直接读取文件、执行命令、修改代码、运行测试的“AI 工程师”。你可以把它理解成住在你电脑里的一个同事你说需求它动手改代码跑命令给你看结果遇到问题还会自己排查。和传统 AI 聊天工具相比Codex 有几个关键差异它能读取当前项目里的文件结构和内容而不是只靠你粘贴代码片段。它能直接执行终端命令比如安装依赖、运行构建、启动服务。它能修改多个文件并告诉你改了哪些地方。它的使用方式更像“任务下发”而不是“一问一答”。所以用 Codex 做项目并不是简单地把代码拷来拷去而是从需求描述、代码生成、本地联调到部署发布整个流程都可以在 AI 的协助下完成。这也是本文标题里“不会写代码也能做项目”的核心原因。1.2 AI 剧本杀项目拆解剧本杀又叫“谋杀之谜”是一类角色扮演推理游戏。玩家各自拿到一个角色剧本通过对话、搜证、推理找出真相。线下剧本杀需要一个主持人DM来控场、发线索、推进剧情而线上 AI 剧本杀则可以让 AI 来承担主持人和 NPC非玩家角色的职责。一个最小可用的 AI 剧本杀 Web 应用至少需要包含以下模块模块功能说明剧本管理保存剧本、角色、线索、结局等数据房间机制创建房间、加入房间、开始游戏对话系统玩家与 AI 主持人或 NPC 对话推理投票玩家提交推理结论、投票找出凶手前端界面剧本选择、角色选择、对话页面、结果页如果靠手写代码这个项目哪怕是一个简化版也需要后端接口开发、前端页面开发、数据库建模、联调部署等一整套工作。但对于 AI 辅助开发来说我们就可以把这些模块拆成一个一个的“任务”交给 Codex 逐步完成。1.3 为什么这个项目适合用 Codex 完成我选择“AI 剧本杀”作为案例是因为它非常适合展示 AI 编程的完整链路一是技术栈可以很简单。后端用 FastAPI 或 Node.js 这种轻量框架前端用 Vue 或 React数据库用 SQLite 或 PostgreSQL都是 AI 非常熟悉的领域生成质量高。二是业务逻辑足够清晰。剧本杀的核心逻辑是“对话 状态管理 投票”没有复杂的算法没有高并发的性能压力适合作为 AI 编程实战项目。三是容易演示“自动发布上线”。整个项目可以打包成 Docker 镜像通过 GitHub Actions 自动部署到云服务器完整跑通 DevOps 流程。如果你完全不懂代码做完这个项目后你也能建立起对前后端分工、API 接口、部署流程的直观认知。如果你本身是开发者这篇文章则能帮你掌握用 Codex 提效的完整方法。2. 环境准备与版本说明2.1 环境清单在开始之前先准备好以下环境。版本需要根据你的项目实际情况调整本文示例以常见环境为例重点演示配置思路。环境项说明操作系统Windows 10/11、macOS、Ubuntu 均可Codex CLI需要安装并登录 OpenAI 账号编程语言Python 3.10 或 Node.js 18数据库开发环境使用 SQLite生产环境建议 PostgreSQL前端构建Vite Vue 3容器化Docker部署平台云服务器或其他可运行 Docker 的环境如果你在 Windows 上开发建议在 PowerShell 或 Windows Terminal 中操作如果你在 macOS 或 Linux 上开发直接用系统终端即可。2.2 安装 Codex CLICodex 的常见使用方式有两种一种是终端 CLI命令行工具另一种是 IDE 插件。安装 CLI 的常见方式是使用 npmnpm install -g openai/codex安装完成后先查看版本确认安装成功codex --version如果是第一次使用需要先登录codex login登录过程会在浏览器中打开授权页面按提示完成授权即可。如果你是在服务器等无浏览器环境使用也可以将密钥配置到环境变量中具体配置方式请以官方文档为准。如果你使用 VS Code也可以在扩展市场搜索 Codex 插件。需要注意的是Codex 插件和 CLI 之间存在关联当你启动插件时它需要找到 Codex CLI 的可执行文件。如果找不到就会出现文章后面要讲的unable to locate the codex cli binary报错。所以建议先完成 CLI 安装和登录再安装 IDE 插件。2.3 初始化项目目录这里我们创建一个名为ai-script-killer的项目目录。你可以手动创建也可以让 Codex 帮忙生成。mkdir ai-script-killer cd ai-script-killer我们计划采用前后端分离的结构ai-script-killer/ ├── backend/ # 后端 FastAPI 项目 ├── frontend/ # 前端 Vue 3 Vite 项目 ├── docker-compose.yml └── README.md如果你暂时不知道这些文件里应该写什么没关系这正是 Codex 要完成的工作。3. Codex 的核心用法与提示词设计3.1 在终端和 IDE 中使用 CodexCodex CLI 的交互模式非常简单。在项目目录下启动codexEntering 交互界面后你可以直接输入自然语言需求。Codex 会先分析当前项目结构然后给出执行计划并询问你确认后执行操作。举一个最简单的例子。在空目录backend中启动 Codex输入在这个目录下创建一个 FastAPI 项目提供 /health 健康检查接口并输出 requirements.txtCodex 会自动创建main.py写入 FastAPI 代码生成requirements.txt然后告诉你如何启动。你也可以使用非交互模式把需求作为参数传给它codex 创建一个 FastAPI 项目提供 /health 健康检查接口在日常使用中交互模式更适合复杂任务因为你可以根据 Codex 的执行结果动态调整方向非交互模式适合已经明确的小任务。3.2 把需求拆成可执行的 Prompt用 Codex 做项目最关键的能力不是“会聊”而是“会拆任务”。一个模糊的大需求比如“帮我做一个剧本杀网站”Codex 往往不知道该从哪里下手。但如果你把它拆成下面这样的小任务Codex 的执行成功率和代码质量都会高很多创建后端项目骨架配置数据库连接。创建剧本表、角色表、房间表和线索表。编写创建房间接口、加入房间接口、开始游戏接口。编写对话接口调用大模型返回 NPC 回复。投票接口统计投票结果。编写前端页面做成响应式布局。前后端联调修复跨域问题。编写 Dockerfile 和部署脚本。每一步都对应一个明确的交付物Codex 就像一个很听话的实习生你给的任务越清楚它的产出越稳定。3.3 让 Codex 写代码时的约束规则在给 Codex 下达任务时建议在 Prompt 中明确以下约束信息技术栈明确使用什么框架、什么语言避免它自己发挥。文件路径明确代码要放在哪个文件方便后续维护。接口协议明确请求方法、请求参数、返回格式。数据模型给出关键表的字段。非目标告诉它“本次不需要实现什么”防止过度设计。举个例子在 backend/app/main.py 中新增一个 POST /api/room 接口 接收 JSON 参数 { room_name: string, player_name: string } 返回 { room_id: string, player_id: string }。 不需要做登录鉴权不需要考虑分布式注册中心。这种写法非常实用。相比空泛的“帮我写个创建房间的接口”这种约束明确的 Prompt 会极大减少返工。4. 实战用 Codex 实现 AI 剧本杀前后端4.1 项目整体结构最终的代码结构大致如下ai-script-killer/ ├── backend/ │ ├── app/ │ │ ├── main.py # FastAPI 入口 │ │ ├── models.py # 数据模型 │ │ ├── schemas.py # 请求响应模型 │ │ ├── api/ │ │ │ ├── room.py # 房间相关接口 │ │ │ └── game.py # 游戏对话相关接口 │ │ └── core/ │ │ └── llm.py # 大模型调用 │ ├── requirements.txt │ └── Dockerfile ├── frontend/ │ ├── src/ │ │ ├── views/ │ │ │ ├── Home.vue # 首页 │ │ │ ├── Room.vue # 房间/游戏页 │ │ │ └── Result.vue # 结果页 │ │ ├── api/ │ │ │ └── index.js # 请求封装 │ │ └── App.vue │ ├── package.json │ ├── vite.config.js │ └── Dockerfile ├── docker-compose.yml └── README.md下面我们来看如何通过 Codex 一步步把这个结构填满。4.2 用 Codex 生成后端 API先创建后端项目。在backend目录下启动 Codexcd backend codex发送第一条任务当前目录为空。请创建一个 FastAPI 项目要求如下 1. 新建 app/main.py包含 FastAPI 应用实例。 2. 使用 SQLAlchemy 连接 SQLite 数据库数据库文件为 ./ai_script.db。 3. 创建三个模型Script剧本、Room房间、Player玩家。 Script 字段id, title, story, create_time Room 字段id, script_id, status, create_time Player 字段id, room_id, name, role, is_host 4. 提供 /api/room/create 接口创建房间并添加房主玩家。 5. 提供 /api/room/join 接口加入房间。 6. 在 requirements.txt 中列出依赖。这个任务已经非常具体Codex 会根据这些约束生成代码。生成完成后它会提示你安装了哪些依赖、如何启动。一个简化版本的后端接口代码大致长这样# 文件路径backend/app/main.py from fastapi import FastAPI, Depends, HTTPException from sqlalchemy.orm import Session from app import models, schemas from app.database import SessionLocal, engine models.Base.metadata.create_all(bindengine) app FastAPI(titleAI Script Killer API) def get_db(): db SessionLocal() try: yield db finally: db.close() app.post(/api/room/create, response_modelschemas.RoomOut) def create_room(payload: schemas.RoomCreate, db: Session Depends(get_db)): room models.Room(script_idpayload.script_id, statuswaiting) db.add(room) db.commit() db.refresh(room) player models.Player( room_idroom.id, namepayload.player_name, rolehost, is_hostTrue, ) db.add(player) db.commit() db.refresh(player) return schemas.RoomOut(room_idroom.id, player_idplayer.id, statusroom.status)这段代码是“结果示例”实际由 Codex 生成的文件内容不会和你完全一样但整体逻辑是相通的。你不需要手写这段代码Codex 会帮完成但你需要有能力看懂 Codex 生成的结果并判断是否满足需求。接下来继续给 Codex 发送对话接口任务在 backend/app 下新增 api/game.py实现对话接口 POST /api/game/chat。 这个接口接收 { room_id, player_id, message }返回 { reply }。 reply 由大模型生成调用 core/llm.py 中的 function call_llm(messages) 你只需要写好调用逻辑不需要实现真实的 LLM 调用先预留函数占位。这一步之后后端就具备了最核心的接口。其他的“加入房间”“获取剧本列表”“投票”等接口可以继续按同样的方式逐个下发任务。4.3 用 Codex 生成前端页面后端完成之后回到项目根目录创建前端项目cd ../frontend codex任务可以这样写当前目录为空。请基于 Vue 3 Vite 创建一个前端项目。 1. 使用 npm 初始化项目安装 vue、vue-router、axios。 2. 创建 Home.vue展示剧本列表点击“开始游戏”后拿到 room_id 并跳转 Room 页面。 3. 创建 Room.vue展示剧本信息、玩家列表、对话输入框。 调用 POST /api/room/create 创建房间调用 POST /api/game/chat 发送消息。 4. 配置 vite.config.js将 /api 请求代理到 http://localhost:8000。 5. 页面样式使用简洁的暗色卡片风格。Codex 会初始化前端项目并生成对应的 Vue 组件。下面是一个简化版的对话区组件!-- 文件路径frontend/src/components/ChatPanel.vue -- template div classchat-panel div v-for(msg, index) in messages :keyindex classmessage span classrole{{ msg.role }}/span span classcontent{{ msg.content }}/span /div div classinput-row input v-modelinput placeholder输入你的推理或发言 keyup.entersend / button clicksend发送/button /div /div /template script setup import { ref } from vue; import axios from axios; const props defineProps({ roomId: String, playerId: String, }); const messages ref([]); const input ref(); async function send() { if (!input.value.trim()) return; const { data } await axios.post(/api/game/chat, { room_id: props.roomId, player_id: props.playerId, message: input.value, }); messages.value.push({ role: 玩家, content: input.value }); messages.value.push({ role: AI, content: data.reply }); input.value ; } /script这里需要提醒的是v-model、ref、defineProps这些 Vue 语法并不需要你完全理解但你应该能从 Codex 的上下文说明中看出这个文件的职责。Codex 生成完代码后通常会在终端给出运行方式和文件清单你需要对照做一次人工确认。4.4 本地联调与验证前后端代码都生成后先启动后端cd backend pip install -r requirements.txt uvicorn app.main:app --reload --port 8000再启动前端cd frontend npm install npm run dev浏览器打开 Vite 输出的地址比如http://localhost:5173你应该能看到首页。选择剧本、创建房间、进入对话页面发送消息后能看到 AI 的回复。如果前端页面能打开但接口调用失败最常见的两个原因是跨域问题。请求地址不对。跨域问题可以在后端 FastAPI 中启用 CORSMiddleware或者在前端 Vite 中配置代理。Codex 生成的代码一般会处理其中一种方式。如果你使用的是 Vite 代理那么前端请求应该使用相对路径/api/...而不是写死http://localhost:8000/api/...。5. 自动发布上线从本地到服务器5.1 为项目生成 Docker 配置本地联调通过后下一步就是把项目自动化发布到服务器。这里采用 Docker Compose 的方式把前端和后端分别打包成镜像。后端 Dockerfile 示例# 文件路径backend/Dockerfile FROM python:3.11-slim WORKDIR /app COPY requirements.txt . RUN pip install --no-cache-dir -r requirements.txt COPY . . EXPOSE 8000 CMD [uvicorn, app.main:app, --host, 0.0.0.0, --port, 8000]前端 Dockerfile 示例# 文件路径frontend/Dockerfile FROM node:18-alpine AS build WORKDIR /app COPY package*.json ./ RUN npm install COPY . . RUN npm run build FROM nginx:stable-alpine COPY --frombuild /app/dist /usr/share/nginx/html COPY nginx.conf /etc/nginx/conf.d/default.conf EXPOSE 80前端 nginx 配置需要处理单页应用路由和 API 代理# 文件路径frontend/nginx.conf server { listen 80; location / { root /usr/share/nginx/html; index index.html; try_files $uri $uri/ /index.html; } location /api/ { proxy_pass http://backend:8000; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; } }最后编写docker-compose.yml# 文件路径docker-compose.yml version: 3.8 services: backend: build: ./backend container_name: script-backend restart: always environment: - DATABASE_URLsqlite:///./ai_script.db volumes: - ./backend/data:/app/data ports: - 8000:8000 frontend: build: ./frontend container_name: script-frontend restart: always depends_on: - backend ports: - 80:80这些配置文件同样可以交给 Codex 生成。任务描述如下为这个项目编写 Docker 配置 1. backend 使用 python:3.11-slim 镜像。 2. frontend 使用 node:18 构建再用 nginx 托管 dist。 3. nginx 需要将 /api 反向代理到 backend 服务。 4. 编写 docker-compose.yml后端暴露 8000前端暴露 80。5.2 使用 GitHub Actions 自动化部署要让“自动发布上线”名副其实不能每次手动登录服务器执行 docker compose。我们可以通过 GitHub Actions 实现“推送代码到主分支 → 自动构建镜像 → 服务器拉取并重启”。首先将项目推送到 GitHub 仓库然后在仓库的 Settings → Secrets 中配置服务器登录信息Secret 名称说明SERVER_HOST服务器 IP 或域名SERVER_USERSSH 登录用户名SERVER_SSH_KEYSSH 私钥接着创建 workflow 文件# 文件路径.github/workflows/deploy.yml name: Deploy AI Script Killer on: push: branches: - main jobs: deploy: runs-on: ubuntu-latest steps: - name: Checkout uses: actions/checkoutv4 - name: Deploy to Server uses: appleboy/ssh-actionv1.0.3 with: host: ${{ secrets.SERVER_HOST }} username: ${{ secrets.SERVER_USER }} key: ${{ secrets.SERVER_SSH_KEY }} script: | cd /opt/ai-script-killer git pull origin main docker compose up -d --build这个 workflow 的含义是只要 main 分支有新的提交GitHub 就会通过 SSH 登录服务器拉取最新代码然后重新构建并启动容器。这个流程演示了最基础的 CI/CD 能力。它并不是最安全的方案比如没有做健康检查、没有处理容器回滚但对于一个从零开始的 AI 项目来说已经足够让你体会到“代码写完自动上线”的完整链路。5.3 上线后的验收清单部署完成后可以做一轮简单的验收打开服务器公网 IP 或域名能否看到首页创建房间、加入房间、发送消息是否正常如果使用了数据库重启容器后数据是否还在访问/api/health或类似健康检查接口是否返回 200查看容器日志是否有报错docker compose logs -f注意生产环境部署时请务必把敏感配置移出代码文件。比如大模型 API Key、数据库连接串等应该通过环境变量注入而不是写死在代码或 docker-compose.yml 中。你可以在服务器上创建.env文件并在 docker-compose.yml 中引入。6. 常见问题与排查思路在实际使用 Codex 和部署项目的过程中会有几个高频问题。下面把现象、原因和解决思路整理成表格并展开说明。问题现象常见原因解决思路Codex 插件启动报 unable to locate the codex cli binary插件找不到 codex 可执行文件安装 CLI或在设置中指定 codex_cli_pathcodex endpoint /responses 请求代理失败Codex 设置了本地代理或网络环境异常检查网络、关闭多余代理确认接口地址正确提示 model is not supported当前 Codex 可用的模型列表与账号不匹配确认账号可用模型升级版本或切换模型前端访问后端接口 404nginx 代理路径或后端路由路径不一致检查 /api 前缀和代理配置页面刷新后 404SPA 路由没有回退到 index.html配置 nginx try_files容器启动后端口冲突本机已有服务占用 80/8000 端口修改映射端口或停掉旧服务6.1 unable to locate the codex cli binary这是 Codex IDE 插件最常见的报错之一。报错信息很直白插件找不到 Codex CLI 的可执行文件。解决思路确认已经全局安装 CLInpm install -g openai/codex。在终端中执行codex --version确认命令可用。如果命令可用但插件仍报错需要在 IDE 插件设置中手动指定 CLI 路径。比如在 mac 上路径可能是/usr/local/bin/codex在 Windows 上可能是C:\Users\你的用户名\AppData\Roaming\npm\codex.cmd。设置好路径后重启 IDE。要注意不同版本、不同系统的路径不完全一样遇到报错时先用where codexWindows或which codexmacOS/Linux确认实际路径。6.2 codex endpoint /responses 代理错误这条报错通常是网络环境或代理配置引起的。Codex 在调用 API 时会通过本地代理转发请求如果代理配置不正确就会出现类似cc switch local proxy failed while handling codex endpoint /responses的错误。解决思路检查系统代理设置关闭不必要的全局代理。检查 Codex 配置文件中的代理参数确保代理地址和端口正确。查看 Codex 日志确认具体的失败原因。如果你的网络环境本身无法访问 API需要先解决网络连通性而不是修改代码。6.3 model is not supported这个错误表示当前账号或当前 Codex 版本不支持你指定的模型。比如错误信息中出现gpt-5.6-sol model is not supported说明配置里指定了一个 Codex 不能使用的模型名。解决思路在 Codex 配置中检查模型参数改为官方支持的模型。更新 Codex 到最新版本新版本通常会同步最新的模型列表。如果使用自定义 base_url 或网关需要确认网关是否支持该模型。查看官方文档确认当前账号可使用的模型范围。这里要特别提醒模型名称变化较快不要照搬任何教程里的模型名要以你实际环境中codex --version和官方文档为准。6.4 前端接口请求失败如果前端页面能打开但发消息无响应优先用浏览器开发者工具查看 Network 面板请求是否发出请求地址是否正确是绝对地址还是相对地址返回状态码是 404、500 还是 CORS 错误后端日志有没有打印异常如果是在本地开发环境建议优先使用 Vite 代理// 文件路径frontend/vite.config.js import { defineConfig } from vite; import vue from vitejs/plugin-vue; export default defineConfig({ plugins: [vue()], server: { port: 5173, proxy: { /api: { target: http://localhost:8000, changeOrigin: true, }, }, }, });这样前端页面里的axios.post(/api/...)会被自动转发到后端服务也避免了跨域问题。6.5 部署后页面白屏部署后打开网站白屏通常是以下原因前端构建时访问了错误的后端地址导致打包后的 JS 无法请求 API。nginx 没有正确读取到dist目录。SPA 路由刷新后 404看起来像白屏。排查步骤在服务器上执行docker compose logs frontend查看 nginx 日志。进入前端容器检查/usr/share/nginx/html下是否有index.html和静态资源。直接访问http://服务器IP/观察是否正常。如果刷新后白屏检查 nginx 的try_files配置。7. 最佳实践与工程建议7.1 不要追求一次生成全量代码我在这个项目里最大的感受是Codex 虽然能一口气生成很多代码但一次性让它完成整个系统反而不容易控制质量。更推荐的做法是“小步快跑”一次只实现一个功能模块。每次生成后先运行验证。再把下一次需求追加给它。这样做的好处是如果某一步生成的代码有问题你可以很快定位到是哪个任务导致的而不是在几万行代码里找 Bug。7.2 Prompt 数量化、结构化给 Codex 写 Prompt本质上和给开发团队写需求文档类似。一个结构好的 Prompt通常包含目标这一步要完成什么。约束用什么技术栈放在哪个目录。输入接口需要接收哪些参数。输出期望的返回结构。边界这一步不需要做什么。如果把“做一个登录页面”改成“在 frontend/src/views/Login.vue 中创建登录页面使用手机号和密码登录提交到 POST /api/auth/login成功后跳转到首页”Codex 写出来的代码会精准很多。7.3 人工检查的五个安全点使用 AI 编程不等于可以完全脱离人工审查。以下几个地方建议无论如何都要自己看一遍密钥泄露检查是否有 API Key、密码被写进代码。权限漏洞检查创建房间、修改数据等接口是否有越权隐患。输入校验检查用户输入是否可能注入恶意内容。数据库操作检查删除、更新类的操作是否使用了 WHERE 条件。依赖安全安装依赖后执行npm audit或pip-audit查看已知漏洞。尤其是涉及生产环境、用户数据、支付等功能时一定要在测试环境验证通过后再发布并且遵循最小权限原则不要给应用过高的系统权限。7.4 从“AI 生成项目”到“AI 参与运维”Codex 的价值不应该止步于“生成代码”。当你具备了 AI 辅助开发的流程后可以让它承担更多工作让 Codex 解释它生成的代码。让它为项目补测试用例。让它写部署文档。让它根据报错日志分析问题。这样一来AI 就成了你团队里的一个“全栈工程师”。即使你平时主要写前端或者主要写后端也可以在另一个陌生的技术领域快速落地。8. 总结与下一步学习路线通过这个 AI 剧本杀项目主要掌握了三件事第一Codex 不是简单的代码生成器而是一个可以操作文件、运行命令、迭代修改代码的 AI 智能体。你的角色从一个“写代码的人”变成了“下发任务和控制质量的人”。第二一个完整的前后端分离项目可以拆分成后端 API、前端页面、Docker 配置、自动部署等多个阶段每个阶段都可以由 AI 辅助完成。关键不是会不会写代码而是会不会把需求描述清楚。第三AI 生成代码之后人工审查仍然是不可省略的环节。安全、权限、密钥管理、依赖安全这些问题AI 不会自动替你负责你需要具备基本的安全意识和排查能力。接下来如果你想继续深入可以从这几个方向入手学习 FastAPI 基础理解路由、依赖注入和数据库操作。学习 Vue 3 的响应式原理理解前端组件通信。学习 Docker 和 Docker Compose掌握容器化部署。学习 GitHub Actions尝试编写更完善的 CI/CD 流水线。研究如何把大模型接入业务逻辑比如角色扮演提示词设计。如果你也是从零开始接触 AI 编程建议先按照本文的流程把一个小项目完整跑通。哪怕只是用一个晚上让 Codex 帮你从空目录生成一个能打开、能访问、能部署的小应用也比反复看教程更有效果。动手做一遍之后你会发现自己对前后端协作、接口设计、部署流程的理解会提升一个台阶。
