上周有位同事在群里发了一张终端截图，满屏红字，最扎眼的是接口返回 404，说找不到/responses这个路径。他为了把 Codex 跑起来折腾了整整两天，中间重装过 Node，换过三个模型，最后发现只是配置文件里少写了一行。这件事让我意识到，Codex 下载与本地部署这件事的难点从来不在"装软件"本身，而在于一堆散落的细节：版本要求、镜像源、接口协议、沙箱权限、上下文长度，任何一环对不上，结果就是启动即报错。
这篇内容我想把这条链路完整走一遍。Codex在这里指的是一款跑在终端里的命令行 AI 编码助手，它能读你的工程目录、改文件、执行命令、补测试，把"聊天窗口里复制粘贴"变成"直接落在代码库里"。而本地部署有两层含义：一是把 Codex 这个工具本身装在你自己的机器上，二是把背后的模型换成跑在本地的推理服务，让代码和数据不出内网。安装和下载这两个环节看似最简单，实际是新手翻车率最高的地方，所以我会把踩坑记录写得很细。
这篇适合三类人看：手里有台还算像样的电脑、想用 AI 写代码但介意代码上传的开发者；想省下按量计费成本、愿意折腾本地模型的学生和个人开发者；以及想搞清楚 AI 编码工具底层工作流、准备自己搭一套的内部工具维护者。全文按"环境准备—下载安装—模型接入—跑通闭环—报错排查"的顺序推进，你可以从头跟着做，也可以直接跳到对应章节抄配置。
1. 先搞清楚 Codex 是什么，它为什么值得装在本地
动手之前先花五分钟建立正确的心理模型，比直接敲命令省事得多。很多人对 Codex 的印象还停留在"网页里帮你补全代码的模型"，那是上一代形态；现在这套命令行工具的本质是一个带工具调用能力的执行体，它把"读文件、改文件、跑 shell、看报错"这些动作串成一个循环，模型在其中负责决策，工具负责落地。理解这一点，你才能明白为什么配置文件里会有沙箱和审批这两个看起来和 AI 无关的东西。
1.1 三种使用形态，别选错方向
目前围绕这套工具的能力大致有三条路：命令行客户端、编辑器插件、以及托管在服务端的任务队列。命令行客户端最灵活，能直接跑在服务器上、能写进脚本、能接自定义模型服务，是本地部署场景里唯一值得投入时间的方向。编辑器插件胜在界面顺手，但通常绑定官方账号体系，想换成自己本地的模型服务往往力不从心。服务端任务队列适合团队协作和长任务，对个人开发者来说属于过度设计。
我自己的判断标准很简单：如果你希望"AI 直接改我本地的仓库，并且我能用自己部署的模型"，那只有命令行这条路。剩下的形态要么改不了模型，要么改不了工作目录。所以后面所有内容都围绕命令行客户端展开，其他形态只在必要处提一句。
1.2 本地部署真正解决的三个问题
第一个是数据边界。代码是有价值的资产，尤其是还没公开的业务逻辑。走本地模型推理，请求不出机器，这一点在很多团队里是硬性要求，不是偏好问题。
第二个是成本可控。云端接口按 token 计费，一次复杂重构动辄消耗几十万 token，长期用下来是笔不小的开支。本地跑一个 7B 到 14B 的代码模型，电费和硬件折旧是唯一成本，用得越多越划算。
第三个是可调试性。当模型行为不符合预期时，本地部署让你能看到完整的请求内容、能在服务端日志里读到原始 prompt、能随意更换模型版本做对比。云端接口这些东西全是黑盒，出问题只能靠猜。
注意：本地部署不等于"完全离线"。Codex 在启动时会做一些版本检查类的网络请求，模型推理虽然在本机，但工具本身仍然需要能访问到你配置的服务地址。如果你所在的网络环境受限，优先考虑用本地模型服务，把接口地址指向
127.0.0.1。
1.3 开工前的硬件与软件清单
先照下面这张表自查一遍，缺什么补什么，不要抱着"装到哪算哪"的心态。
| 项目 | 最低要求 | 推荐配置 | 说明 |
|---|---|---|---|
| 操作系统 | Windows 10 1909+ / macOS 12+ / 主流 Linux 发行版 | Windows 11 + WSL2 | Windows 原生可用，但 WSL2 上少踩一半坑 |
| Node.js | 20 LTS | 22 LTS | 低于 20 会在安装阶段直接失败 |
| 内存 | 16GB | 32GB 及以上 | 本地跑 7B 模型至少要留出 8GB 余量 |
| 显存 | 4GB（跑 3B 小模型） | 12GB 以上 | 显存决定你能跑多大的模型 |
| 磁盘 | 20GB 空闲 | 100GB 以上 | 单个 7B 模型量化后约 4-5GB，多版本叠加很快吃满 |
| 必备工具 | Git 2.30+、Python 3.10+ | 加上 conda 管理环境 | 部分扩展能力依赖 Python 运行时 |
关于显卡我要多说一句：如果你只有核显，本地跑代码模型会非常吃力，7B 模型在纯 CPU 上生成速度可能只有每秒两三个 token，改一个函数要等一分钟。这种情况下我的建议是混合方案——工具装在本地，模型走云端兼容接口。后面第 4 章两种方案都会给出完整配置，你按自己的硬件挑一条。
2. 环境准备：地基没打牢，后面全是玄学问题
我见过太多"Codex 装不上"的求助，最后定位下来根本不是 Codex 的问题，而是 Node 版本不对、PATH 没配好、或者 npm 默认源在特定网络下超时。环境准备这一章看起来枯燥，但它决定了你后面是顺利跑通还是一路报错。我的经验是，把这一章的三件事做扎实，安装环节的失败率能降一大半。
2.1 Node.js 与 npm：版本和源是两大关键
Node.js 是运行基础，用官方安装包或者版本管理工具装都行。我个人偏好用版本管理工具，因为切换版本方便——今天跑 A 项目要求 Node 18，明天跑 Codex 要求 Node 20，手动装卸很痛苦。Windows 上可以用 nvm-windows，macOS 和 Linux 上可以用 nvm 或 fnm。
装完第一件事是验证版本：
node -v npm -vnode -v输出如果是 v20 以下，别犹豫，直接升。第二件事是换源。npm 默认源在部分网络环境下下载速度极慢甚至超时，把源指向国内镜像能省掉大量等待：
npm config set registry https://registry.npmmirror.com npm config get registry第二条命令用来确认设置生效，输出应该是你刚设的那个地址。如果你在公司内网，可能有自己的私有源，那就问一下运维同学拿地址，别硬套公共源。
注意：换源之后如果后面某次安装出现包完整性校验失败，先把源切回官方地址试一次，确认不是镜像同步延迟导致的。这个排查思路能帮你省下不少怀疑人生的时间。
2.2 Git、Python 和那些"看起来可选"的工具
Git 是必须的。Codex 在你的仓库里干活，改动能不能回退、能不能对比差异，全靠 Git 兜底。建议在动手之前先确认你的项目目录是干净的：
git status如果输出一堆未提交的改动，先提交或者 stash 掉。让 AI 在一个本身就脏兮兮的工作区里改代码，出问题你根本分不清是谁改的。Git 的基础配置也顺手做了，用户名和邮箱配好，避免提交时各种报错：
git config --global user.name "你的名字" git config --global user.email "你的邮箱"Python 不是运行 Codex 的必需品，但很多扩展能力（比如接一些本地的工具服务）依赖它，建议装上 3.10 以上的版本。再配一个虚拟环境管理工具，避免把系统 Python 装得乱七八糟。
至于虚拟机，我的态度是可选但有用。如果你打算让 AI 执行命令，又担心它在真实系统上误删文件，把它关在一个虚拟机里跑是最省心的方案。虚拟机里装一套干净的 Linux，装好 Node 和 Git，把代码通过共享目录挂进去，即使模型发疯执行了破坏性命令，损失也仅限于虚拟机内部。
2.3 Windows 用户的三条路，我推荐第二条
Windows 上跑这套工具，有三条路可选：原生 PowerShell、WSL2、完整虚拟机。
原生 PowerShell 最直接，装完就能用，但你会遇到路径分隔符、执行策略、长路径限制这些零碎问题。WSL2 是我最推荐的方案，它给你一个真实的 Linux 环境，和 macOS、Linux 用户的体验完全一致，网上的大部分教程和配置可以直接照抄，文件系统性能对代码场景也够用。完整虚拟机适合企业环境或者你想做严格隔离的场景，代价是资源占用高、文件同步麻烦一点。
如果你选 WSL2，装好之后记得到 Linux 子系统里重新装一遍 Node 和 Git，别指望 Windows 侧装好的能直接用。很多人卡在这里，在 Windows 里装了 Node，进 WSL 一敲node -v提示找不到命令，然后开始怀疑人生。
2.4 目录规划和终端习惯
两个小习惯，长期收益很大。第一，把工作目录定清楚。我会在用户目录下建一个统一的代码根目录，所有项目放里面，Codex 启动时永远从这个根目录的子目录进入，避免它意外扫描到整个硬盘。第二，固化终端的工作目录，别在C:\Windows\System32或者用户根目录下随手启动，否则模型可能会去读一些你完全不想让它读的文件。
还有一件事值得提前做：给你的项目加一个忽略文件，把密钥文件、环境变量文件、模型缓存目录排除掉。这既是为了防止误提交，也是为了减少模型读取无关内容的概率，间接省下上下文开销。
3. Codex 下载与安装全流程
到这一步，我们正式进入"下载"和"安装"环节。这里我把几条安装路径摊开对比，然后给出一条我实测最省事的主线，最后把 Windows 上"安装未完成"这个高频问题拆开讲。
3.1 三种安装方式，先选对再动手
| 安装方式 | 命令形式 | 优点 | 缺点 | 适合人群 |
|---|---|---|---|---|
| 包管理器全局安装 | npm install -g | 升级方便，一条命令搞定 | 依赖 Node 环境，偶尔受源影响 | 绝大多数人，推荐 |
| 官方预编译二进制 | 下载可执行文件 | 不依赖 Node，体积小启动快 | 手动管理版本，需自己配 PATH | 不想装 Node、追求启动速度的人 |
| 源码编译 | 从仓库拉取后构建 | 可定制、能用最新特性 | 需要 Rust 工具链，编译耗时长 | 想改源码、做二次开发的工程师 |
对九成以上的人来说，第一种就够了。第二种适合那种"我机器上就是不想装 Node"的洁癖型用户，或者需要在没有 Node 环境的服务器上部署的场景。第三种我不建议普通用户碰，编译一次十几分钟起步，中间任何一个依赖缺失都够你查半天。
3.2 主线操作：全局安装与版本验证
确认 Node 版本达标、源已切好之后，执行安装：
npm install -g @openai/codex这条命令会从镜像源拉取包并安装到全局目录。正常情况下几十秒完成，如果卡在某个包上超过两分钟，按 Ctrl+C 中断，执行npm cache clean --force清缓存后重试。
装完立刻验证：
codex --version codex --help第一条确认安装成功，第二条把可用参数列出来。强烈建议你认真读一遍--help的输出，因为不同版本的参数名会有差异，网上教程里写的选项在你这个版本上可能已经改名了。以自己终端里的输出为准，这是最可靠的信息源。
如果提示command not found或者 Windows 上提示"不是内部或外部命令"，八成是全局安装目录不在 PATH 里。查看全局目录：
npm config get prefix把这个路径（Windows 上通常是%APPDATA%\npm，macOS 和 Linux 上是/usr/local或者用户目录下的某个路径）加进系统环境变量，重启终端再试。这个问题我在三台不同的机器上遇到过三次，属于必踩之坑。
3.3 首次启动：认证方式和配置目录
第一次运行codex会引导你做认证。官方托管服务支持账号登录，如果你打算接自己的本地模型或者第三方兼容接口，可以在配置文件里指定服务地址和密钥环境变量，登录这一步就能跳过。
配置文件的位置记一下，后面所有改动都在这里：macOS 和 Linux 是~/.codex/config.toml，Windows 是C:\Users\你的用户名\.codex\config.toml。如果目录不存在，手动创建即可。这个文件用 TOML 格式，比 JSON 好写，支持注释，改坏了也容易恢复。
注意：配置文件里永远不要直接写明文密钥。正确做法是把密钥放进环境变量，配置里只写变量名。你在第 4 章会看到具体写法。把密钥写进配置文件的第一大风险是某天不小心把
.codex目录提交到了仓库里。
3.4 Windows 上"安装未完成"的四类原因
这是搜索量很高的一个报错，我把它拆成四类，你可以对号入座。
第一类是网络下载中断。表现为安装命令跑了很久最后报超时。解决方式是换镜像源、清缓存、重试；如果反复失败，改用预编译二进制，直接下载可执行文件绕开包管理器。
第二类是权限不足。Windows 上全局安装需要写系统目录，普通权限会失败。解决办法是用管理员身份打开终端，或者把 npm 的全局目录改到用户目录下，避免每次都要提权。
第三类是杀毒软件拦截。部分安全软件会把新下载的可执行文件当成可疑程序直接隔离，导致安装"完成"了但文件不见了。遇到这种情况，去安全软件的隔离区看看，或者给安装目录加个白名单。这个坑很隐蔽，因为安装过程本身不报错。
第四类是残留文件冲突。之前装过一半、卸载不干净，导致新版装不上。先卸载再清缓存，然后重新安装：
npm uninstall -g @openai/codex npm cache clean --force npm install -g @openai/codex如果这四招都试过还是不行，直接把报错信息完整复制出来搜，别只搜"安装失败"这四个字。报错里那个具体的模块名或错误码，才是定位问题的钥匙。
4. 模型接入：本地部署和云端接口，两条路都给你
工具装好了，接下来是让它真正"有脑子"。这一章是整篇内容的核心，我会把本地模型部署、配置文件的每一行、以及云端兼容接口的接法都讲清楚。你可以只选一条路走，但两条路的配置思路建议都看一眼，理解了才知道怎么排查问题。
4.1 用 Ollama 在本地跑一个代码模型
本地模型服务我最常用的方案是 Ollama，它把模型下载、量化、服务化三件事打包成了一条命令，几乎没有学习成本。装好之后先确认服务在跑：
ollama --version ollama listlist会列出现有模型。刚装好时是空的，拉一个代码专精的模型下来：
ollama pull qwen2.5-coder:7b这个命令会下载约 4 到 5GB 的文件，具体大小取决于量化版本。下载完成后验证接口是否可用：
curl http://localhost:11434/v1/models能返回模型列表就说明本地服务已经对外提供 OpenAI 兼容接口了，Codex 可以直接对接。如果这条命令连不上，先确认服务进程在运行，再检查端口有没有被占用。
4.2 显存怎么算，选多大模型不翻车
选模型不能凭感觉，按下面的算法估一下。权重大小的粗略公式是：
权重占用（GB）≈ 参数量（B）× 量化位数 ÷ 8
以 7B 模型 Q4 量化为例，7 × 4 ÷ 8 ≈ 3.5GB，加上量化元数据和框架开销，实际落在 4 到 5GB。除此之外还要给上下文缓存留空间，上下文越长占用越大，7B 模型在 32K 上下文下大约还要吃掉 2 到 3GB。所以最终结论是：8GB 显存跑 7B Q4 配 16K 上下文比较舒服。
| 模型规模 | 推荐量化 | 权重占用 | 建议显存 | 上下文建议 | 实际体验 |
|---|---|---|---|---|---|
| 1.5B - 3B | Q4 | 1 - 2GB | 4GB | 8K | 补全和小改动够用 |
| 7B - 8B | Q4_K_M | 4 - 5GB | 8 - 10GB | 16K | 日常改代码的主力档位 |
| 14B | Q4_K_M | 8 - 9GB | 12 - 16GB | 32K | 复杂重构能接住 |
| 32B | Q4_K_M | 18 - 20GB | 24GB+ | 32K+ | 接近云端体验，但慢 |
显存不够时的第一个动作不是换小模型，而是降上下文长度。把 32K 降到 8K，往往就能把原本爆显存的配置救回来，代价是模型一次能看到的代码变少，需要你更明确地告诉它看哪些文件。
4.3 配置文件逐行讲清楚
打开~/.codex/config.toml，把下面这段写进去：
model = "qwen2.5-coder:7b" model_provider = "ollama" model_context_window = 32768 model_max_output_tokens = 8192 [model_providers.ollama] name = "Ollama Local" base_url = "http://localhost:11434/v1" wire_api = "chat"逐行解释一下。model是模型名，必须和ollama list里显示的名字完全一致，包括冒号后面的标签，写成qwen2.5-coder少个标签就可能报找不到模型。model_provider指向下面那张表的名字。model_context_window告诉工具模型能接受多长的上下文，这个值设大了超出模型能力会报错，设小了浪费能力，按你拉取的模型规格填。model_max_output_tokens限制单次输出长度，代码生成场景给 8K 比较合理。
[model_providers.ollama]这一段定义服务来源。base_url是接口根地址，注意结尾的/v1不能少，这是 OpenAI 兼容接口的约定路径。wire_api指定协议类型，本地 Ollama 用chat协议。
注意：部分版本在连接本地服务时会要求提供密钥字段，即使是本地服务也需要一个占位值。如果启动时报缺少认证信息，在配置文件里加一行
env_key = "OLLAMA_API_KEY"，然后在系统里把这个环境变量设成任意字符串即可，本地服务不会校验它的真实性。
4.4 接云端兼容接口：以 DeepSeek 为例
如果你硬件不够或者想要更好的推理质量，可以接云端兼容接口。关键点是先确认对方的接口协议和路径，这一步搞错就是无限 404。配置写法：
model = "deepseek-chat" model_provider = "deepseek" model_reasoning_effort = "medium" [model_providers.deepseek] name = "DeepSeek" base_url = "https://api.deepseek.com/v1" env_key = "DEEPSEEK_API_KEY" wire_api = "chat"env_key写的是环境变量名，不是密钥本身。密钥要设到系统环境变量里：
export DEEPSEEK_API_KEY="你的密钥"Windows 上用setx DEEPSEEK_API_KEY "你的密钥"，设完要重开终端才生效。这一步做完，启动 Codex 它就会自动读取这个变量去认证。
这里有个极其关键的坑：不同服务商支持的协议不一样。有的只支持chat协议，你配成responses就会一直报 404，因为对方根本没有那个路径。反过来也一样。判断方法很直接——去看服务商的接口文档里列出的路径，文档里写的是/v1/chat/completions就填chat，写的是别的就对应调整。这个判断逻辑能解决掉一大半的接口类报错。
4.5 用配置档在多个模型之间切换
同时用本地模型和云端模型的人，肯定会嫌改来改去麻烦。TOML 支持配置档，写法如下：
[profiles.local] model = "qwen2.5-coder:7b" model_provider = "ollama" [profiles.cloud] model = "deepseek-chat" model_provider = "deepseek"启动时指定档位即可：
codex --profile local codex --profile cloud我的习惯是默认用本地档位做日常小改动，遇到复杂重构再切云端。这样既能控制成本，又不会在关键任务上被本地小模型的能力拖后腿。你可以在 shell 里给这两条命令起别名，切换成本几乎为零。
5. 跑通全流程：从第一个任务到融入日常工作
配置写完了，接下来是验证它真的能干活。这一章我按"第一次启动—权限设置—第一个真实任务—非交互模式"的顺序走一遍，每一步都说明为什么这么做。
5.1 第一次启动，先做三件确认
进入你的项目目录再启动，不要在无关目录下运行：
cd ~/projects/your-repo codex启动后先做三件确认。第一，看看界面顶部显示的模型名是不是你配的那个，如果还是默认型号，说明配置文件没被读到，检查路径和拼写。第二，输入一个斜杠，看看弹出的命令列表，熟悉一下可用操作，不同版本命令会有差异，以你终端里显示的为准。第三，让它做一个只读操作，比如"列出这个项目的目录结构并说明各模块职责"，这个任务不需要写文件，用来验证读取链路是否正常。
如果这一步能正常返回，说明工具、配置、模型三者的链路已经打通了。这一步失败的话，别急着往下走，先按第 6 章排查。
5.2 沙箱和审批模式，安全的第一道闸
这套工具默认不会随便动你的文件，它有一套权限体系。常见的有三种审批级别：最严格的是每个动作都要你确认，最宽松的是全自动执行不打断。我建议新手从中间档位开始：
approval_policy = "on-request" sandbox_mode = "workspace-write"这两行的含义是：默认在当前工作区可写，但涉及越界操作时会向你请求确认。这样既不会每改一行都问你，也不会出现它悄悄动了工作区之外的文件。
注意：存在一种完全放开权限的模式，能读写任意路径、能访问网络。这个模式只在你完全清楚风险、且处在隔离环境（比如专门的虚拟机）里才考虑使用。在主力开发机上开这个模式，等于把系统交给一个会犯错的概率模型管理，风险不对等。
5.3 用一个真实小任务验证闭环
接下来给它一个真正有产出的任务，我通常用"补单元测试"作为验证任务，因为它有明确的对错、改动范围可控、又确实需要读代码。指令可以这样写：
"读一下 src/utils/format.js，为其中的日期格式化函数补一组单元测试，覆盖空值、非法输入和跨时区三种情况，测试文件放在同目录下。"
这个任务的好处是：它会读文件、写新文件、可能需要跑测试命令，完整地走一遍工具调用循环。执行过程中注意观察它每一步的决策，你会看到它先读文件、理解函数签名、再决定测试怎么写。这个观察过程非常有价值，能让你理解后面该怎么给它提要求。
执行完做两件事：用git diff看它改了什么，然后跑一遍测试。如果测试通过，恭喜你，整条链路彻底跑通了。如果失败，把失败信息原样贴回对话里让它修，这本身就是它最擅长的事。
5.4 项目级约定和非交互模式
两个能显著提升日常效率的用法。第一个是项目级的约定文件，在仓库根目录放一个说明文件，写清楚代码规范、目录约定、构建命令、不要碰哪些目录。这样每次启动它都会自动读取，省掉重复解释。内容不用写得很正式，像给新同事看的交接文档那样就行：
- 提交信息使用中文，格式为：类型: 描述 - 测试命令：npm run test - 不要修改 vendor 目录下的任何文件 - 新增依赖前先说明理由第二个是非交互模式，适合接进自动化流程：
codex exec "为最近一次提交新增的函数补充文档注释"这个模式不加交互界面，直接执行并输出结果，可以写进脚本或者提交钩子里。不过要注意，自动化场景下权限要开得更保守，避免无人值守时出现意外改动。
6. 报错排查实录：那些让我熬夜的坑
这一章是我自己踩过和帮别人解决过的真实问题汇总。你会发现一个规律：大多数报错不是工具坏了，而是配置和服务端的约定对不上。
6.1 接口路径不匹配导致的 404
这是被我遇到最多的报错，报错信息里通常会带上一个路径名，说这个端点不存在。原因基本只有两种：一是协议类型填错了，服务端只有 chat 协议的路径，你却让它去访问另一种协议的路径；二是base_url拼错了，多一个斜杠少一个/v1都会出问题。
排查顺序是这样：先用 curl 直接打服务端，看看到底有哪些路径存在：
curl -s http://localhost:11434/v1/models curl -s https://api.deepseek.com/v1/models -H "Authorization: Bearer $DEEPSEEK_API_KEY"如果 curl 能通而 Codex 报错，问题一定在协议类型或 base_url 上。如果 curl 也不通，那就是服务本身或网络的问题，先把服务跑起来再说。
6.2 模型名和上下文长度类报错
模型名报错的特征是提示找不到指定模型。这时候别猜，直接列出来对照：
ollama list注意名字里的标签部分，qwen2.5-coder:7b和qwen2.5-coder:latest是两个不同的东西。云端接口同理，模型名要和文档里写的完全一致，大小写都别改。
上下文超限的报错会明确提示 token 数量超标。解决办法有两个：把model_context_window调小到模型实际支持的值，或者在提问时缩小范围，明确指定只看哪几个文件，别让它去扫描整个仓库。
6.3 权限、写入和文件系统类问题
写入失败通常有三种原因：沙箱权限不够、目标文件所在目录不在可写范围内、文件被其他进程占用。第一种改配置解决，第二种要么把目录加进可写根目录列表，要么换个工作目录，第三种关掉占用文件的编辑器或进程。
还有一种很隐蔽的情况：在 WSL2 里操作 Windows 侧的挂载目录时，文件权限映射有问题，导致看起来能读不能写。我的做法是把代码仓库放在 Linux 文件系统内部，通过其他方式同步到 Windows，而不是直接在挂载目录上干活。这样性能也更好。
6.4 排查速查表
| 现象 | 最可能原因 | 第一步动作 | 验证方式 |
|---|---|---|---|
| 提示找不到命令 | 全局安装目录不在 PATH | 查npm config get prefix | 重启终端后再试 |
| 安装超时或中断 | 源太慢或网络不稳 | 换镜像源并清缓存 | 重新执行安装 |
| 接口 404 | 协议类型或 base_url 写错 | 用 curl 探测服务端路径 | 对照服务商文档 |
| 找不到模型 | 模型名或标签不一致 | 列出本地或云端模型清单 | 复制粘贴名字 |
| 上下文超限 | 窗口值大于模型能力 | 调小配置里的窗口值 | 重新发起简单任务 |
| 写入被拒 | 沙箱或目录权限 | 检查审批级别与可写范围 | 换到工作区内文件测试 |
| 启动后模型不对 | 配置文件没被读取 | 确认文件路径和档位参数 | 看界面显示的模型名 |
7. 实操心得：让这套东西长期好用的几个习惯
前面讲的是"怎么跑通"，这一章讲"怎么用得住"。这些经验没有写在任何官方说明里，都是我在日常使用中一点点攒下来的。
7.1 控制上下文成本，别让开销失控
先说个粗算方法。一段代码平均每行大约 12 到 18 个 token，一个 3000 行的模块折合 4 万到 5 万 token。如果一次任务涉及跨 8 个文件的改动，输入很容易冲到 15 万 token 以上。搞清楚这个量级，你就知道为什么"把整个仓库丢给它"是不现实的。
我的做法是主动缩小范围。提问时明确说清楚看哪几个文件、哪个函数、什么现象，而不是笼统地说"这个项目有问题"。这个习惯能让单次任务的 token 消耗降一个数量级。另外，长会话聊到后半段会越来越慢，因为历史消息一直在累积，该开新会话的时候就开新的，别一个会话用一整天。
7.2 本地小模型的提示词写法不一样
这是个容易被忽略的差异。强模型能理解模糊表达，你说"优化一下这个函数"它就能猜到你想干什么；本地 7B 级别的模型不行，它需要你把话说明白。所以用本地模型时，指令要写成"输入是什么、期望输出是什么、边界条件有哪些"，越具体越好。
还有一点，本地小模型在多轮对话里容易"忘记"前面的上下文，尤其是会话较长时。解决办法是重要约束在每次提问里重复一遍，或者写进项目约定文件里，让它每次都重新读到。这不算优雅，但很有效。
7.3 升级、备份和密钥管理
工具和模型都会更新，建议固定一个升级节奏而不是看到新版就升。我的习惯是每月检查一次，升级前先把配置文件备份一份：
cp ~/.codex/config.toml ~/.codex/config.toml.bak升级后如果出现新问题，用备份回退，几分钟就能恢复工作状态。模型方面，本地模型的版本可以并存，新版本先用两三天，确认在某些典型任务上表现更好再删旧的，别急着清理。
密钥管理上，我坚持三个原则：密钥只存在环境变量里、不同服务用不同的密钥、定期轮换。如果你在团队里共享配置，把密钥部分抽出来单独管理，配置文件可以进仓库，密钥文件绝对不进。见过太多因为一个.env文件误提交而紧急改密码的事故。
最后分享一个我自己的小技巧。我会在项目根目录放一个笔记文件，记录"这套配置在这台机器上跑通过的具体版本组合"——Node 版本、Codex 版本、模型名和标签、配置文件关键项。半年后重新在另一台机器上部署时，照着这份记录抄，基本可以一次跑通。这套组合信息比任何教程都准，因为它是你自己环境里验证过的结果。
