波仔
🛠️ 第3章 第一次任务：跑通一条闭环
📄 一句话概括

装完不算装好，能跑出 --version 才算；登进去不算登好，能读到一个仓库才算。 装之前先体检依赖——这一步跟具体哪个工具无关，是通用动作。 第一条命令一定要只读——「能不能干活」还没验证，先让它干最没有破坏性的事。

📝 本章和前面几章的关系

从这一节开始，正式进入「怎么用」。前面两章讲的是「它是什么、边界在哪」， 这一章讲「第一次怎么跑通」。 跑通这件事比看起来重要——因为大部分人的卡点不在「不会用」，在「装不上、登不进」。 沙箱里没有装 Codex（Demo 里真跑了一遍，报「没有这个命令」）， 所以这一节的命令一律只贴不跑，但「体检」那个动作是真跑的。 装的三条路径、凭据落点、配置文件的形状都照官方文档写。 这一节值得认真读的理由： 装错的成本很高——版本不对、权限不够、装完跑不起来， 而这些问题的排查方法，换任何工具都用得上。

一、三条安装路径

官方一般给三条路，按平台和习惯选一条。 不要三条都试——装重了之后「到底在用哪个」会变成新的问题。

路径 适合谁 代价
npm 全局装 本机已有 Node，习惯命令行 升级要再跑一次命令
包管理器（brew 等） macOS，想要统一升级 版本可能落后一点
官网下载安装包 不想碰命令行 升级要手动

怎么选？看你怎么管工具。 如果你用 brew upgrade 统一升级所有命令行工具，就走 brew；如果你项目里就是用 npm，就走 npm。 别为了装一个工具引入一套新的包管理。 装完必须验证。 --version 能跑出东西，才算装好——这一步不能靠「看到提示说 installed」来判断， 因为 PATH 没配好时，装了也是「找不到命令」。

二、登录与凭据落在哪

登录会往用户目录写一个凭据文件。 这个文件有几个特性要记住： 它在用户目录里（不在项目里）、它是明文或可解的（不是加密的）、 它能代表你操作（所以等于密码）。 三条推论，每条都对应一个真实事故： ① 它不该进版本库——项目里的 .gitignore 要覆盖它，而且不要在项目目录里跑登录； ② 它不该贴给别人——包括贴给 AI；③ 换机器要重新登——它不是可移植的配置。 还有一条容易被忽略：登出要真的删掉那个文件。 很多工具的「登出」只是清了内存里的状态，文件还在。 换电脑、卖旧机器之前，手动确认那个文件不在了。 配置文件是另一回事，它不含凭据。 模型、审批策略、沙箱模式、MCP 服务器都写在配置里—— 这些是可以共享的，也是团队统一的关键（第 13 章讲）。

三、第一条验证命令

装好、登进去之后，第一条命令该干什么？ 不是「帮我改个 bug」，是「列一下目录结构，不要修改任何文件」。 为什么？因为它一次验证三件事： ① 能启动（命令不报错）、② 能读到仓库（能列出真实文件）、③ 能听懂「不要修改」（只读指令被遵守）。 三件事都过了，才谈得上「让它动手」。 这一步的另一个作用是「建立基线」。 你看到了它眼里的仓库长什么样—— 如果它列出来的东西不对（少了目录、多了临时文件），说明它的视野有问题， 后面所有的判断都会带偏。 顺带说一句：第一条命令别用中文标点混着写。 「列出目录结构，不要修改文件」这句话里，「，」是全角还是半角，对它没影响， 但对你排查「它为什么没听懂」有影响——先排除掉变量，再怀疑它。

四、动手 Demo：装之前先把环境查一遍

这个 Demo 做两件事：真跑一遍环境体检，然后把官方的安装与配置原码贴出来。 体检部分是真的——node、git、python 三个都在，codex 不在， 它老老实实报「本机没有这个命令」，退出码 127。 后面贴原码的部分标了「本沙箱不执行」，那些命令你在自己机器上跑，路径与字段以官方文档为准。

def sh(cmd):
    for name in (cmd[0], cmd[0] + ".cmd", cmd[0] + ".exe"):
        try:
            r = subprocess.run([name] + cmd[1:], capture_output=True)
            return r.returncode, r.stdout.decode().strip()
        except FileNotFoundError:
            continue
    return 127, "（本机没有这个命令）"

for name, cmd in (("node", ["node", "--version"]),
                  ("git", ["git", "--version"]),
                  ("codex", ["codex", "--version"])):
    rc, out = sh(cmd)
    print(pad(name, 8) + pad(out, 38) + ("✓" if rc == 0 else "✗"))

实跑输出：

--------------------------------------------------------------------
装之前先把环境查一遍
--------------------------------------------------------------------


  ① 五条依赖，逐个体检
  --------------------------------------------------------------------
  node    v22.22.2                              ✓
  npm     10.9.7                                ✓
  git     git version 2.55.0.windows.3          ✓
  python  Python 3.13.14                        ✓
  codex   没有这个命令                          ✗
  五项里 4 项就位。

  ② 缺的那一项，报什么错
  --------------------------------------------------------------------
  退出码 127
  输出：（本机没有这个命令）
  这个沙箱里没装 Codex，所以从这一节开始，凡是 codex 命令一律只贴不跑。
  ! 但「装之前先体检」这个动作本身是真的——它跟具体哪个工具无关。

  ③ 官方原码：三条安装路径
  --------------------------------------------------------------------

  [官方原码 · 本沙箱不执行]
  | # 路径一：npm 全局装（最通用）
  | npm install -g @openai/codex
  | 
  | # 路径二：Homebrew（macOS）
  | brew install codex
  | 
  | # 路径三：下载安装包（官网）
  | # 装完验证
  | codex --version
  教材 3.1 的三条路径，按平台选一条；装完必须能跑出 --version 才算装好。


  ④ 登录：凭据落在哪
  --------------------------------------------------------------------
  登录之后凭据落在本地，不在仓库里。位置大致是用户目录下的配置目录。

  [官方原码 · 本沙箱不执行]
  | ~/.codex/auth.json        # 登录凭据（不要提交进仓库）
  | ~/.codex/config.toml      # 配置（模型、审批策略、MCP 服务器等）
  这两个文件的路径是本课约定，实际以官方文档为准。


  ⑤ 配置文件的形状
  --------------------------------------------------------------------
  | # ~/.codex/config.toml
  | model = "gpt-5-codex"
  | approval_policy = "on-request"       # untrusted / on-failure / on-request / never
  | sandbox_mode = "workspace-write"     # read-only / workspace-write / danger-full-access
  | 
  | [mcp_servers.docs]
  | command = "npx"
  | args = ["-y", "@some/docs-mcp"]
  三个键值得记：模型、审批策略、沙箱模式。
  审批策略决定「什么时候停下来问你」，沙箱模式决定「它能写到哪儿」——这两个是安全的主开关。

  ⑥ 装完的第一条验证命令
  --------------------------------------------------------------------
  不要一上来就让它改代码。第一条命令应该是「只读」的：

  [官方原码 · 本沙箱不执行]
  | codex "列出这个仓库的目录结构，不要修改任何文件"
  这条命令验证三件事：能启动、能读到仓库、能听懂「不要修改」。

  ! 第一条命令只读，是因为「它到底能不能干活」还没验证，先让它干最没有破坏性的事。

体检表里五项，四项就位，缺的那一项是 Codex 本身。 注意 codex 那一行的输出是「没有这个命令」，退出码 127—— 这个 127 就是「命令找不到」的标准退出码，脚本里可以直接判它。 为什么要写这个体检脚本，而不是一条条手敲？ 因为装完之后你会换机器、会重装系统、会给同事装。 脚本一次写好，后面每次都是零成本——这也是「把动作写成文件」的第一个例子，第 3.6 节会讲透。 第五节贴的配置文件里，三个键值得单独记： 模型（用哪个）、审批策略（什么时候停下来问你）、沙箱模式（它能写到哪儿）。 后两个是安全的主开关—— 「审批策略」管的是「动不动手前问你」，「沙箱模式」管的是「最多能碰到哪里」。 最后一段那个「第一条命令只读」，是从事故里学来的。 很多人的第一条命令是「帮我修一下这个 bug」—— 而那时候它能不能读文件、会不会乱写，都还没验证。 先只读，再动手，顺序不能反。

30 秒实验

  1. 给你的机器写一个五行的体检脚本（node、git、python、目标工具、包管理器）。 存成 doctor.py 放项目里，下次换机器直接跑。
  2. 打开你的 ~/.gitignore_global 或者项目 .gitignore，确认凭据目录被忽略了。 没忽略的话，现在加——一次忘了提交，就等于把钥匙公开了。
  3. 检查你的配置文件在哪、里面写了什么。 如果里面有密钥，把它挪到环境变量里——配置文件是要进版本库的。

常见误区

  1. 「提示说装好了就是装好了。」 PATH 没配的时候，装了也是「找不到命令」。 只有 --version 跑出东西才算装好。
  2. 「登进去就行了，凭据文件不用管。」 那个文件等于你的身份。 它进了版本库、贴进了聊天窗口，就等于把身份交出去了。 登出要确认文件真的没了，不是点了按钮就算。
  3. 「第一条命令当然是让它干活。」 第一条命令是验证环境，不是验证能力。 先只读地跑一条，确认它能看见仓库、能听懂限制—— 这一步省下的不是时间，是「它在没验证过的状态下乱改」的风险。
自测三问（点开对答案） 1. 为什么「--version 能跑」才算装好？ —— **因为「装了」和「能用」是两件事。** PATH 没配好时，文件在硬盘上但命令找不到。 **退出码 127 就是「命令不存在」。** 2. 凭据文件和配置文件，哪个能进版本库？ —— **配置文件能，凭据文件不能。**配置里是模型、审批策略、沙箱模式这些可共享的设置； **凭据等于密码，进版本库就等于公开。** 3. 第一条命令为什么选「只读」的？ —— **因为它一次验证三件事：能启动、能读到仓库、能听懂「不要修改」。** **三件事过了才谈得上让它动手。** 顺序反了，你就在没验证的状态下给了它写权限。

下一篇 3.2 讲第一个选择： 同一件事，是在你本机跑，还是扔到云端跑——判据只有三条，但判错会出真事故。

相关笔记