Codex 教程：跑通第一个任务

这页带你在 Jarvis 里跑通第一个 Codex 编码任务。顺序是：先把 Jarvis 跑起来，再把 Codex 接进来，然后提交一个小任务，看着它在 Jarvis 里推进，最后确认结果。每一步都说明「做什么」和「应该看到什么」，卡住了看下面的「常见问题」。

Jarvis 给 Codex 用户带来什么

Jarvis 不替换你已经装好的 Codex CLI，也不接管它的账号。它加在 Codex 之上，让你用更少注意力做完同一件事：

会话不会丢：会话的状态和进展由 Jarvis 持续记录，刷新、重连或重启后还能接着看，不用翻终端历史。
一个入口做四件事：启动、观察、恢复、检查 Codex 会话都在同一个界面里完成。
只看到有用的进展：主聊天显示的是精简后的进展和关键汇报，不是满屏终端输出。
需要你时能看见：会话要澄清、要权限、要决策时，会明确问出来，你在同一处回复一次即可继续。
结果可回看：完成后能回到会话详情页，确认「做完了、做对了」。

开始之前

本机需要：

Git、Python 3.11+、Node.js 20.19+；
一个 ChatGPT 账号，用来登录 Codex。

你不需要预装 Jarvis，下面从源码开始。想了解更完整的源码启动说明，见快速开始。

第 1 步：把 Jarvis 跑起来

先在终端里准备好源码和依赖：

git clone https://github.com/CAKE-math/jarvis.git && cd jarvis
./scripts/bootstrap-source.sh
cp .env.example .env && printf '\nJARVIS_FORCE_HTTP=1\n' >> .env

依赖就绪后启动 Jarvis，并在另一个终端生成登录密钥：

./restart.sh                       # 或 ./dev.sh（更快，前端热更新）
.venv/bin/jarvis genkey -d "本地浏览器"

打开 http://127.0.0.1:8888，粘贴刚生成的密钥。

应该看到：浏览器进入已登录的 Jarvis 界面。

第 2 步：接入 Codex

Jarvis 不替你管理 Codex 账号，需要你本机安装并登录 Codex：

npm install -g @openai/codex
codex login                        # 打开浏览器，用 ChatGPT 账号授权

回到 Jarvis 的运行时状态页，确认 Codex 显示为可用。

应该看到：运行时状态页里 Codex 是可用状态，而不是「未找到」。

第 3 步：提交一个小任务

在 Jarvis 主聊天里：

在输入区选择 Codex 作为运行时。
发送一个容易验证的小任务，例如：在当前工作区创建 scratch.txt，并写一句话说明这是 Jarvis 运行时冒烟测试。

应该看到：聊天里出现与会话关联的回复，会话列表里多出一个新的 Codex 会话。

第 4 步：在 Jarvis 里看它推进

任务提交后，打开会话详情页观察进展，不需要额外操作。重点看：

主聊天里有没有出现精简的进展或会话更新；
详情页里有没有终端输出或事件记录。

应该看到：能看到会话在推进，而不是一片空白。

第 5 步：确认结果

任务完成后，确认结果：

回到会话详情页，回放时间线，确认关键步骤和最终结果可见；
检查任务产物，例如 scratch.txt 存在且内容正确；
确认会话状态已进入完成或等待下一步指令。

应该看到：不用翻原始终端输出，就能确认「做完了、做对了」。

常见问题

启动失败

端口被占用：换一个端口再启动。
依赖不完整：重新跑一次 ./scripts/bootstrap-source.sh，确认 Python 和 Node 版本满足要求。
粘贴密钥后仍未登录：重新生成一个密钥再试。

Codex 显示「未找到」

确认 codex 命令可用：在终端里跑 codex --version。
确认已经完成 codex login。

任务提交后没有进展

确认运行时选择器没有回退到 Auto，并且选择的是 Codex。
打开会话详情页看是否有错误；长时间没有状态更新通常是运行时或模型认证的问题。