Codex 完全指南：用 AGENTS.md 与 Goal 模式打通 Computer Use 操控电脑全流程

1. 为什么你的 Codex 总是“跑一半就停”从真实桌面场景说起Codex 的 Computer Use 能力简单说就是让 AI 长出鼠标和眼睛能直接操控你的 Mac 桌面应用、内置浏览器甚至自己跑完一整套多步任务。它适合谁适合那些每天在重复操作 GUI 软件、手动跑测试、来回切换浏览器和终端的人。我试过让它自己打开 Xcode 跑一个圈叉游戏、发现 bug、改代码、再重跑全程没碰键盘。但问题来了大多数人第一次用 Computer Use都会遇到同一个坑——Codex 跑到第三步就停了或者点错了按钮或者干脆“看不懂”当前屏幕。根本原因不是模型不行而是你没给它一份清晰的“项目说明书”和“目标定义”。AGENTS.md 就是那份说明书Goal 模式就是那个目标定义。没有这两样Computer Use 就像一个没有工牌的新员工进了办公室不知道先开哪个抽屉。这篇指南会从 AGENTS.md 的声明式配置入手结合 Goal 模式拆解多步任务演示内置浏览器 Atlas 与系统操控的协同。我会给出可复制的 AGENTS.md 骨架、Goal 模式任务模板以及逐步验证 Computer Use 是否按预期执行的操作清单。你跟着做就能把 Codex 从“代码补全工具”变成真正能替你干活的数字同事。2. 前置准备TaoToken 接入与 Codex 环境配置在开始操控桌面之前你需要先让 Codex 能稳定调用模型。这里我用 TaoToken 作为 API 网关来接入原因是它支持程序化配置适合 Codex CLI 这种需要自定义 API 网关的场景。官网地址是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 端点是 https://taotoken.net/api 。第一步去控制台创建一个 API Key。打开 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite 登录后进入 API Keys 页面点“新建密钥”复制生成的 sk- 开头的字符串。这个 Key 只显示一次先存到安全的地方。第二步配置 Codex CLI 的环境变量。Codex CLI 是开源的支持自定义 API 网关。你可以在终端里这样设置export OPENAI_API_KEYsk-你的TaoToken密钥 export OPENAI_BASE_URLhttps://taotoken.net/api如果你用的是 Codex 桌面 App在设置里找到“自定义 API 端点”填入https://taotoken.net/api再把 Key 粘贴进去。注意API 地址不要加 UTM 参数保持干净。第三步验证接入是否成功。运行一个最简单的请求curl https://taotoken.net/api/v1/models \ -H Authorization: Bearer sk-你的TaoToken密钥如果返回一个包含模型列表的 JSON说明网关通了。这一步很关键因为后面 Computer Use 的所有操作都依赖模型调用的稳定性。如果这里报 401检查 Key 是否复制完整如果报 404检查 base URL 是否写成了https://taotoken.net/api而不是带/v1的路径。第四步开启 Mac 的屏幕录制和辅助功能权限。Codex 的 Computer Use 需要这两个权限才能“看到”屏幕和“点击”按钮。打开“系统设置 → 隐私与安全性 → 屏幕录制”勾选 Codex再进入“辅助功能”同样勾选 Codex。Codex 在安装 Computer Use 组件时会引导你完成这些设置但手动检查一遍更稳妥。3. 可复制配置AGENTS.md 骨架与 Goal 模式任务模板3.1 AGENTS.md 骨架让 Codex 记住项目规则AGENTS.md 放在项目根目录Codex 进入项目时会自动读取。它的作用是告诉 Codex这个项目用什么命令、遵循什么代码风格、有哪些坑。下面是一个可以直接复制的骨架我把它分成了 Commands、Code Style、Architecture、Computer Use Rules 四个区块# Codex Project Rules ## Commands - Dev: npm run dev - Test: npm test - Build: npm run build - Lint: npm run lint ## Code Style - Use 2 spaces for indentation - Prefer const over let - Use TypeScript for all new files - No any types unless absolutely necessary ## Architecture - Pages in /app (Next.js App Router) - Components in /components - Utils in /lib - API routes in /app/api ## Computer Use Rules - Before clicking any button, take a screenshot and describe what you see - After each action, verify the screen state changed as expected - If a dialog appears, read the dialog text before clicking OK - Never close the terminal window without saving logs - When testing a GUI app, always start from a clean launch ## Common Gotchas - Remember to run prisma generate after schema changes - API routes need export const dynamic force-dynamic - The dev server must be running before Computer Use tests这个骨架里Computer Use Rules 是专门为桌面操控加的。它强制 Codex 在每次点击前先截图确认点击后验证状态变化。实测下来这一条规则能减少大约 70% 的误点击。3.2 Goal 模式任务模板把模糊需求变成可量化目标Goal 模式的核心是“不干完不罢休”但前提是目标必须可量化。模糊的指令在普通对话里没问题在 Goal 模式下 Agent 无法判断何时停止。下面是一个可复制的任务模板/goal 在 macOS 上完成以下任务 1. 打开 Xcode 项目 /Users/me/projects/tic-tac-toe 2. 点击 Run 按钮启动游戏 3. 试玩 3 局记录每局的胜负结果 4. 如果发现任何 UI 异常或逻辑 bug截图保存到 /tmp/codex-bugs/ 5. 修复发现的 bug重新运行测试 6. 确认 3 局游戏均正常结束后输出一份 Markdown 报告到 /tmp/codex-report.md 约束条件 - 不修改游戏的核心逻辑只修复 UI 和交互问题 - 每步操作后截图保存到 /tmp/codex-screenshots/ - 如果 10 分钟内无法完成暂停并输出当前进度这个模板的关键在于每一步都有明确的动作和验证点约束条件限定了修改范围超时机制防止无限循环。你可以把 Xcode 项目路径换成你自己的应用把试玩局数改成你需要的数字。3.3 内置浏览器 Atlas 的协同配置Atlas 是 Codex 内置的浏览器目前主要支持 localhost 上的本地网页应用。你可以在 AGENTS.md 里加一段浏览器规则## Browser Rules (Atlas) - Local dev server runs on http://localhost:3000 - Before interacting with the page, wait for the network to be idle - When selecting text on the page, use the element selector, not coordinates - After each UI change, reload the page and verify the change persisted这样 Codex 在操控浏览器时会先等网络空闲再用元素选择器而不是坐标点击。坐标点击在页面滚动后会失效元素选择器更稳定。4. 验证请求与成功结果逐步检查 Computer Use 是否按预期执行配置写好了怎么知道 Codex 真的在按预期操控电脑我整理了一份操作清单你可以逐步验证。第一步启动一个简单的 Goal 任务只做一件事打开计算器输入 11截图结果。命令如下codex goal 打开 macOS 计算器输入 11截图保存到 /tmp/calc.png然后关闭计算器预期结果终端输出每一步的动作日志/tmp/calc.png存在且显示结果为 2。如果截图是黑屏说明屏幕录制权限没给如果计算器没打开说明辅助功能权限没给。第二步验证 Atlas 浏览器协同。先启动一个本地 dev servernpm run dev然后让 Codex 打开 localhost 并修改页面文字codex goal 用 Atlas 打开 http://localhost:3000找到页面上的标题文字把它改成 Codex Test Passed然后截图保存到 /tmp/atlas.png预期结果/tmp/atlas.png显示标题已改。如果 Codex 说“找不到元素”检查 AGENTS.md 里的 Browser Rules 是否写了正确的端口。第三步验证多步任务拆解。用一个包含 3 个步骤的 Goalcodex goal 1. 打开终端运行 npm test2. 如果测试通过打开浏览器访问 localhost:3000 并截图3. 如果测试失败把错误日志保存到 /tmp/test-error.log预期结果Codex 会根据测试结果走不同分支。这一步验证的是 Goal 模式的条件判断能力。如果它不管测试结果都走同一个分支说明 Goal 描述里的条件不够明确需要改成“如果 npm test 的退出码为 0则……否则……”。第四步检查持久化。关掉终端合上笔记本等 5 分钟再打开运行codex goal status预期结果显示上次未完成的目标和当前进度。如果显示“无活跃目标”说明 Goal 没有正确持久化检查 Codex 版本是否支持 app-server 状态层。5. 本篇常见错排查Codex Computer Use 报错与修复5.1 报错 “Screen recording permission denied”这是最常见的错误。Codex 需要屏幕录制权限才能“看到”屏幕内容。修复方法打开“系统设置 → 隐私与安全性 → 屏幕录制”找到 Codex勾选。如果 Codex 不在列表里点“”号手动添加/Applications/Codex.app。添加后必须重启 Codex权限才会生效。5.2 报错 “Element not found in Atlas”Atlas 浏览器找不到页面元素。原因通常是页面还没加载完或者元素选择器写错了。修复方法在 AGENTS.md 的 Browser Rules 里加一条“等待 network idle 后再操作”。如果还是找不到让 Codex 先截图你看截图里元素的实际位置再调整选择器。5.3 Goal 模式无限循环不停止Goal 模式跑了几十步还在继续说明目标没有可量化的终止条件。修复方法在 Goal 描述里加明确的成功标准和超时限制。比如“最多尝试 5 次5 次后仍未成功则输出失败报告并停止”。另外检查 AGENTS.md 里是否有“每次操作后验证状态变化”的规则没有的话加上。5.4 API 调用返回 401 或 403检查 TaoToken 的 Key 是否过期或者 base URL 是否写错。正确的 base URL 是https://taotoken.net/api不要加/v1。如果 Key 没问题去控制台看看余额是否充足。接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 里面有详细的错误码说明。5.5 Computer Use 操作干扰了正常使用Codex 的 Computer Use 默认在后台静默运行但如果你同时在用电脑可能会冲突。修复方法在 AGENTS.md 里加一条“操作前检查当前活跃应用如果用户正在使用目标应用等待 30 秒再操作”。或者把 Codex 的任务安排在你不用电脑的时候跑比如午休或下班后。6. 长期编码与 Agent 工作流用 Coding Plan 把 Computer Use 变成日常如果你打算把 Codex 的 Computer Use 用在日常开发里比如每天自动跑 GUI 测试、自动截图对比、自动生成运维脚本那单次调用就不够了。你需要一个稳定的长期方案。TaoToken 的 Coding Plan 就是为这种场景设计的地址是 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 。Coding Plan 的核心优势是它把 API 调用打包成订阅制适合高频、长时间的 Agent 工作流。你可以把 Codex 的 Goal 模式任务挂到 Coding Plan 下让它每天定时跑比如每天早上 9 点自动打开测试环境、跑一遍 GUI 回归测试、截图存档、生成报告。如果测试失败Codex 会自动把错误日志和截图发到你的邮箱。配置方法很简单在 Codex 的配置文件里把 API 端点指向 Coding Plan 的专属地址然后在 TaoToken 控制台里设置好额度上限和告警阈值。这样即使 Codex 跑了一整夜你也不用担心费用失控。如果你只是想先验证模型能力可以打开模型对话页面 https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel-chatutm_campaignrewrite 直接和模型对话测试它对 Computer Use 指令的理解程度。确认没问题后再接入 Codex CLI 跑真实任务。最后说一个我踩过的坑Codex 的 Computer Use 在 macOS 上对多显示器的支持还不完美。如果你外接了显示器Codex 可能会在主显示器和外接显示器之间“迷路”。解决办法是在跑 Computer Use 任务时把目标应用拖到主显示器上或者干脆合上笔记本只用外接显示器。这个细节在官方文档里没写但实测有效。