Codex CLI实战：接入DeepSeek与Ollama并批量运行

终端里能直接改代码的 AI 智能体，这两年出了不少，但真正把“读仓库、改文件、跑命令、自己看报错再改”这一整套流程跑通的并不多。OpenAI 开源的 Codex CLI 就是其中一个完成度比较高的：它是一个跑在本地终端里的编码智能体，不是网页对话框，也不是 IDE 插件，你 cd 到项目目录敲一个 codex，它就能看到你整个仓库的文件结构，按你的指令去改代码、执行测试、根据报错继续修。

这篇文章要聊的重点，不是“AI 写代码有多神”，而是三件更实际的事：第一，它到底怎么装、怎么启动；第二，怎么把它从“只能用官方账号”改成“接任意 OpenAI 兼容接口”，包括国内可直接访问的 DeepSeek，以及完全零成本的本地 Ollama 方案；第三，怎么把它塞进脚本和批量任务里，让它在 CI 或者一堆仓库上跑起来。

先说明一个前提：标题里出现的“ChatGPT5.6”目前并不存在公开版本，任何以此为卖点的教程都要打个问号。本文只讨论真实存在的 Codex CLI，以及它支持的第三方兼容接口配置方式。另外，“免费算力”这件事要拆开看——厂商的新用户额度、开源模型的本地推理，都属于合理路径；而共享账号、绕过计费这类做法不在讨论范围内，也建议不要碰，账号风险远大于省下的那点钱。

下面的内容按“能跑起来 → 能改对代码 → 能批量跑 → 能省钱”这个顺序展开，每一步都给可复制的命令和配置。如果你手上正好有一个中等规模的仓库，想试试让 AI 接手那些重复的样板代码修改，这套流程可以直接照抄。

1. Codex CLI 核心能力速览

先把关键信息摆出来，方便你判断值不值得花时间。Codex CLI 的定位是“终端内的编码智能体”，它和 Copilot 那类补全工具的本质区别在于：补全工具只在你光标附近猜下一行，而 Codex 是在仓库级别做任务——你给它一句“把 utils 目录下所有 fetch 调用换成新的请求封装”，它会自己去找文件、读上下文、生成补丁、执行、验证。

这里要特别强调“本地算力占用极低”这一点。很多人一听“本地跑 AI 编程”就以为要 16G 显存起步，其实 Codex CLI 本身只是一个 Node 程序，真正跑推理的是你配置的那个 API 端点。默认走云端时，你的机器只负责发请求和落地文件修改，8G 内存的老笔记本都能跑。只有当你选择用 Ollama 之类在本地起模型时，才需要关心显存——那部分是模型的事，不是 Codex 的事。

另一个容易被忽略的点是沙箱与审批机制。Codex 默认不会无脑执行命令，涉及写文件、跑 shell、联网这些动作时，它会按配置的审批策略来问你，或者在一个受限沙箱里执行。这个设计对新手很友好，因为你能亲眼看到它准备干什么再决定放不放行；但也意味着如果你想要全自动批处理，得先把审批策略调好，否则脚本会卡在等待确认那一步。

2. 适用场景与使用边界

Codex CLI 最适合的场景，是那些“逻辑上不复杂、但要翻很多文件”的活儿。比如项目从旧版本框架升级，几十个文件里的 API 调用签名都变了；比如要给一批接口补上统一的参数校验；比如某个模块完全没有测试，需要按现有风格生成一批用例。这类任务人写起来枯燥、容易漏，交给智能体反而合适，因为它不会烦，也不会改到第八个文件就忘了前面的规范。

反过来，有几类活儿不建议一上来就交给它。第一是核心业务逻辑的重写，尤其是涉及金额计算、权限判定、状态机流转的地方，模型给出来的代码看着对，但边界条件经常想不全，必须人工逐行过。第二是涉及数据库迁移、生产配置变更的操作，一旦它理解错表结构，改出来的 SQL 可能直接把数据搞坏。第三是跨仓库的大范围改动，单次任务的文件数量一多，上下文窗口就吃紧，它容易在中途“忘记”最初的要求。

使用边界上还有几条硬线要划清楚。代码版权方面，如果你让模型参考的仓库本身有 License 限制，生成结果的使用要自己确认；商业项目里引入 AI 生成的代码，最好在提交记录里标注来源，方便后续审计。数据隐私方面，把公司内部仓库丢给第三方 API 端点，等于把源码发出去了，这一点必须先过合规，敏感项目老老实实用本地模型或者干脆不用。服务商条款方面，各家对“免费额度”的使用范围都有明确规定，拿免费额度去跑商业批量任务，被封号是小事，影响业务交付才是大事。

还有一条经常被忽视：Codex 会执行 shell 命令。这意味着它能 rm、能 git push、能装依赖。默认的沙箱和审批就是为这个设计的，别为了图省事把它关掉，尤其是在有生产凭证的环境里。

3. 环境准备与前置条件

Codex CLI 是 Node 写的，所以第一件事是把 Node 环境弄好。版本上建议 Node 18 起步，实际用 20 或 22 会更稳，因为部分依赖对老版本 Node 的兼容性一般。检查命令很简单，先看版本再动手：

bash复制node -v
npm -v
git --version

三个都有输出且 Node 主版本号不低于 18，就可以继续。如果 Node 版本太低，别硬装，用 nvm 切一个干净版本更省事：

bash复制# 安装并切换到 Node 20（nvm 需提前装好）
nvm install 20
nvm use 20
node -v

操作系统方面，macOS 和 Linux 是原生支持，Windows 用户强烈建议走 WSL2，直接在 PowerShell 里跑会遇到路径分隔符和 shell 差异的问题，排查起来很痛苦。WSL2 里就是一个标准 Ubuntu 环境，和 Linux 用法完全一致。

其他前置条件清单：

• Git 仓库：Codex 的很多能力依赖 git 来感知改动，非 git 目录也能用，但 diff 相关功能会受限。建议在真实仓库里测试。
• 终端环境：需要一个支持交互式输入的终端，Windows Terminal、iTerm2、GNOME Terminal 都行。注意有些 IDE 内置终端对 TUI 渲染支持不好，遇到界面错乱先换系统终端。
• 网络：默认走官方接口时需要能访问对应端点；接 DeepSeek 这类国内服务则直连即可。这里只讨论正常网络环境下的配置。
• 磁盘空间：CLI 本体加依赖大概几百 MB，真正占空间的是它可能帮你装的 npm 包，建议在容器或独立目录里测试。
• API Key：如果用第三方接口，提前去服务商控制台创建一个，注意别把 Key 写进仓库文件。
• 端口占用检查：CLI 本身不占端口，但如果你同时跑本地模型服务（比如 Ollama 默认 11434），要确认端口没被别的进程占用。

bash复制# 检查本地模型服务端口是否被占用（Linux/macOS）
lsof -i :11434

4. 安装部署与首次启动

安装方式有两种，按你的习惯选。npm 全局安装最通用：

bash复制npm install -g @openai/codex
codex --version

macOS 用户也可以用 Homebrew，升级管理更方便：

bash复制brew install codex
codex --version

装完之后，在任意 git 仓库根目录执行 codex，就会进入交互界面。首次启动会让你选择登录方式，通常有两条路：一是用官方账号走浏览器授权，二是直接配置 API Key。如果你打算接第三方接口，第二种更直接，因为整个流程不依赖官方账号。

交互模式下的基本操作记住几个就够用了：

• 直接输入自然语言指令，回车发送。
• 用 @ 引用具体文件，避免它在大仓库里瞎找。
• 输入 / 调出内置命令，比如切换模型、查看状态、清理上下文。
• Ctrl+C 中断当前任务，Ctrl+D 退出。

第一次跑建议做一件很保守的事：在一个测试仓库里让它“只读”。也就是问它“这个项目的入口文件是哪个，依赖关系是怎样的”，看它能不能正确读出结构。这一步能验证三件事：模型接口通不通、仓库上下文读得对不对、权限审批流程是否符合预期。比一上来就让它改代码安全得多。

如果你确实要用官方账号，登录流程会拉起浏览器完成授权，终端里会显示授权码。这个流程对网络环境有要求，配置不通时会一直卡在等待回调，遇到这种情况就别死磕，直接切到 API Key 模式。

5. 接入 DeepSeek 与本地模型的配置方法

这部分是整篇文章的核心。Codex CLI 支持在配置文件里声明多个 model_provider，只要目标服务兼容 OpenAI 的 Chat Completions 协议，就能接进来。DeepSeek 的接口就是兼容的，所以配置起来很直接。

配置文件默认在 ~/.codex/config.toml，没有就新建一个。下面是接 DeepSeek 的完整示例：

toml复制# ~/.codex/config.toml
model = "deepseek-chat"
model_provider = "deepseek"

# 审批策略：on-request 表示由模型主动请求时才询问
approval_policy = "on-request"

[model_providers.deepseek]
name = "DeepSeek"
base_url = "https://api.deepseek.com/v1"
env_key = "DEEPSEEK_API_KEY"
wire_api = "chat"

几个字段解释一下。base_url 要写到 /v1 这一级，很多接入失败都是因为少写了这段路径。env_key 指定从哪个环境变量读 Key，这样配置文件本身可以提交到 dotfiles 仓库而不会泄露密钥。wire_api 指定协议类型，第三方兼容接口一般用 chat，官方模型才用 responses。

然后设置环境变量，注意别写进 .bash_history 里被翻出来：

bash复制# 临时生效，仅当前终端会话
export DEEPSEEK_API_KEY="你的Key"

# 或者写进 shell 配置文件（注意文件权限）
echo 'export DEEPSEEK_API_KEY="你的Key"' >> ~/.bashrc
chmod 600 ~/.bashrc
source ~/.bashrc

如果是推理类模型，可以把 model 改成对应的 reasoner 版本，或者在启动时用参数覆盖：

bash复制codex --model deepseek-chat

完全零成本的本地方案：如果你连 API 费用都不想出，可以用 Ollama 在本地起一个编码模型，然后让 Codex 指向本机端点。这条路的好处是数据不出机器，坏处是对硬件有要求，7B 级别的模型在 8G 显存上能跑但效果一般，32B 级别的模型建议 24G 显存起步。配置大概长这样：

toml复制# 本地 Ollama 方案，需先 ollama pull 对应模型
model = "qwen2.5-coder:7b"
model_provider = "ollama"

[model_providers.ollama]
name = "Ollama Local"
base_url = "http://127.0.0.1:11434/v1"
wire_api = "chat"

先确认本地服务活着，再启动 Codex：

bash复制ollama list
curl http://127.0.0.1:11434/v1/models

需要提醒的是，Codex 的配置字段在不同版本间有过调整，model_providers 的具体键名以你安装版本的 README 为准。如果照抄配置后提示字段不识别，先用 codex --help 看看当前版本支持哪些参数，比盲目搜索快。

6. 功能测试与效果验证

配置通了不代表能用，还得跑几组测试看实际效果。下面四组是我建议按顺序做的，从只读到写入，风险逐步升高。

6.1 仓库理解测试

目的是验证它能不能正确读取项目结构。在一个中等规模的仓库里，问一个需要跨文件才能回答的问题，比如“这个项目的鉴权逻辑分布在哪些文件里，调用链是怎样的”。

判断成功的标准有三条：能不能准确定位到文件路径、能不能说出关键函数名、有没有编造不存在的文件。第三条最重要，模型胡编文件路径是常见问题，一旦出现说明上下文读取有问题，先检查是不是在仓库根目录启动的。

6.2 单文件修改测试

挑一个边缘文件，比如工具函数或者测试文件，让它做一个小改动：“把这个文件里所有的 console.log 换成统一的日志封装”。

这一步重点观察它给出的 diff。合格的输出应该是精确的最小改动，而不是把整个文件重写一遍。如果它大段重写，说明提示词给得不够具体，加上“只改必要的行，保持其余代码不变”会好很多。

6.3 多文件重构测试

选一个模块目录，让它做统一改造，比如“把这个目录下所有回调风格的函数改成 async/await”。

这类任务最容易暴露上下文窗口的瓶颈。文件数量超过十个之后，注意观察它是不是改到后面就忘了前面的规范。判断标准是改动的一致性——如果前三个文件用了一种写法，后三个又换了一种，说明它在长上下文里丢失了约束，这时候应该拆成小批次跑。

6.4 测试执行与自我修正

这是 Codex 相比普通代码生成最有价值的能力。给它一个明确目标：“跑一下这个模块的单元测试，把失败的全部修好”。

完整流程应该是：执行测试命令 → 读报错 → 定位文件 → 修改 → 重新执行 → 直到通过。如果它只改了一次就停下来不问结果，说明审批策略或者提示词需要调整，可以在指令里明确要求“修改后必须重新运行测试验证”。

7. 非交互模式、脚本化与批量任务

交互模式适合探索，但真正提效的是非交互模式。codex exec 接收一条指令，跑完就退出，输出可以直接被脚本消费，这是接 CI 的关键。

bash复制# 基础用法：执行一条任务后退出
codex exec "为 src/utils 目录下每个文件补充缺失的 JSDoc 注释，不要改变任何逻辑"

# 指定模型和审批策略，适合无人值守场景
codex exec --model deepseek-chat "运行 npm test，修复所有失败的用例"

批量任务最简单的做法是用 shell 循环，把任务清单写进文件，一行一个仓库或者一行一个文件：

bash复制#!/usr/bin/env bash
# batch_run.sh：对多个仓库依次执行同一类任务
set -u

TASK="检查这个仓库里是否有硬编码的密钥字符串，有的话列出来但不要修改"
LOG_DIR="./logs"
mkdir -p "$LOG_DIR"

while IFS= read -r repo; do
  [ -z "$repo" ] && continue
  name=$(basename "$repo")
  echo "=== 处理 $repo ==="
  (
    cd "$repo" || exit 1
    codex exec "$TASK"
  ) > "$LOG_DIR/$name.log" 2>&1
  echo "退出码: $? 日志: $LOG_DIR/$name.log"
done < repos.txt

这个脚本有三个细节值得注意。set -u 防止变量为空时误执行；每个仓库在子 shell 里跑，cd 不会污染外层环境；日志单独落盘，出问题能回溯。实际用的时候建议再加一层超时控制，避免某个仓库卡住拖垮整个批次。

如果要更细的控制，用 Python 包一层更灵活，可以做重试、可以做结果聚合：

python复制import subprocess
from pathlib import Path

REPOS = [p for p in Path("./projects").iterdir() if p.is_dir()]
TASK = "列出这个项目使用的所有第三方依赖，输出为 JSON"

def run_one(repo: Path, retries: int = 2) -> dict:
    for attempt in range(retries + 1):
        try:
            result = subprocess.run(
                ["codex", "exec", TASK],
                cwd=repo,
                capture_output=True,
                text=True,
                timeout=600,
            )
            if result.returncode == 0:
                return {"repo": repo.name, "ok": True, "out": result.stdout}
        except subprocess.TimeoutExpired:
            continue
    return {"repo": repo.name, "ok": False, "out": ""}

if __name__ == "__main__":
    results = [run_one(r) for r in REPOS]
    ok = sum(1 for r in results if r["ok"])
    print(f"成功 {ok} / {len(results)}")
    for r in results:
        if not r["ok"]:
            print("失败:", r["repo"])

批量任务最容易踩的坑是“第一个成功之后信心爆棚，直接跑全量”。建议先跑三个仓库，看日志质量再决定是否全量。另外，批量场景下务必关掉需要人工确认的审批项，否则脚本会一直挂着等输入，表现出来就是“卡住了”。

8. 资源占用与成本观察

前面说过，Codex CLI 本身几乎不吃本地资源，真正需要盯的是两样东西：本地模型方案的显存占用，以及云端方案的 token 消耗。

本地模型方案的显存观察：在 Linux 上直接看显卡状态最准：

bash复制# 每秒刷新一次显存占用
watch -n 1 nvidia-smi

# 只取显存那一行
nvidia-smi --query-gpu=memory.used,memory.total --format=csv

经验上，7B 级别的量化模型跑推理大概占用 5 到 8G 显存，具体取决于量化位数和上下文长度；14B 级别建议 12G 以上；32B 级别不要低于 24G。上下文越长，KV Cache 占的显存越多，所以同一个模型处理小文件和处理整个大仓库，占用能差出一截。如果爆显存，优先降低上下文长度、减少一次性的文件数量，其次是换更小的量化版本。

云端方案的 token 观察：这是主要成本来源，也是最容易失控的地方。几个控制手段：

• 交互模式里用 /status 看当前会话的 token 用量和上下文占用比例。
• 上下文快到上限时用 /compact 做压缩，比直接开新会话保留更多有效信息。
• 简单任务用小模型，复杂重构再切大模型，别所有活儿都上最强的。
• 重复跑同一类任务时，把常用规范写进 AGENTS.md 放在仓库根目录，Codex 会自动读取，省掉每次重复描述需求的 token。

成本量级上不好给具体数字，因为差异太大——一个只改三行代码的任务可能几千 token，一个跨二十个文件的重构轻松上几十万。更稳妥的做法是先在测试仓库跑几轮，看统计出来的消耗，再按你的实际项目规模估算。真要严格控制，可以在配置文件里设一个上限，或者按天分批跑。

还有一个隐形成本容易被忽略：网络往返时间。大批量任务里，每次请求的延迟累积起来很可观，尤其在处理几十个文件时。这种情况下把任务拆成“每批 5 个文件”，比一次性丢 50 个文件进去更快出结果，失败重试的成本也低。

9. 常见问题与排查方法

排查这类问题有个通用顺序，按这个来能省很多时间：先验证接口通不通（curl 直接打端点）、再验证配置读没读到（codex --help 看参数、配置文件路径是否正确）、最后才怀疑模型能力。绝大多数“模型不行”的情况，其实是配置没生效。

10. 最佳实践与落地建议

想把 Codex CLI 真正用起来，有几条经验值得提前采纳。

第一，从只读任务开始建立信任。新接入一个模型端点时，先让它做代码审查、依赖梳理、文档生成这类不改文件的事，观察输出质量再逐步放开写权限。这比一上来就让它重构核心模块稳妥得多。

第二，把项目规范沉淀成 AGENTS.md。在仓库根目录放一个说明文件，写清楚代码风格、目录约定、测试命令、禁止改动的区域，Codex 每次启动都会读。这一步的投入产出比极高，能显著减少“改出来不符合项目习惯”的情况。

第三，模型文件和输入输出分目录管理。批量任务场景下，projects/、logs/、patches/ 分开存放，出问题能快速定位是哪一批、哪个仓库、哪个文件出的错。日志一定要带时间戳和退出码，否则回溯全靠猜。

第四，接口服务要限制访问范围。如果你把 Codex 包装成内部服务给团队用，记得加鉴权、加配额、加审计日志。API Key 只能存在服务端，绝对不能下发给前端或者写进客户端配置。

第五，涉及版权和人脸、声音等生物特征素材的处理任务，必须先确认授权。Codex 能批量处理素材文件，但“能处理”和“有权处理”是两件事，商用前做好素材来源登记。

第六，发布或商用前留一道人工复核。AI 生成的代码在语法层面通常没问题，问题都在业务语义层面——边界条件、异常分支、并发安全。把 Codex 当成一个手很快但需要 review 的初级工程师，这个定位最准确。

最后说回“免费”这件事。真正的零成本路径只有一条：本地模型 + 你自己已有的硬件。第三方服务的免费额度是获客手段，政策随时会变，适合验证阶段，不适合长期依赖生产流程。与其花时间研究怎么薅额度，不如花时间把配置调好、把 AGENTS.md 写细、把批量脚本的容错加上——这些投入不会因为服务商改政策而失效。

如果你现在就想动手，建议的最小验证路径是：装好 CLI，接一个你手头已有 Key 的兼容端点，在一个测试仓库里跑“只读理解 + 单文件修改”这两个测试。这两个能过，剩下的多文件重构和批量任务才有意义。跑不通就先回头检查 base_url 和环境变量，八成问题都在这两处。