拓冰网站定制 
简介Open Codex 是一款完全开源的命令行 AI 助手灵感来自 OpenAI Codex定位于在终端中运行的轻量级编码代理。它重点支持本地语言模型并与 Ollama 深度集成适合希望离线使用智能编码辅助、保护代码隐私的开发者也可用于自动化补全、代码示例生成与项目协作等场景。压缩包内共 15 个文件以 8 个 Python 脚本为核心实现辅助以 pyproject.toml、锁文件、版本配置和 Markdown 说明文档另附演示动图可快速了解界面与用法整体仅 1.68MB轻量易部署包内目录结构清晰核心模块与配置分离便于按需修改。目前已有 1512 人学习下载。通过这份源码包读者可获得完整的命令行工具实现、依赖管理与运行配置既能直接接入 Ollama 使用也可基于开源代码二次开发深入理解本地 AI 编码助手的工作机制。1. Open Codex 是什么一个让本地模型替你写代码的终端助手Open Codex 是一个完全开源的命令行 AI 助手灵感直接来自 OpenAI 的 Codex CLI但把模型层换成了本地推理并与 Ollama 完全集成。启动后不用登录任何云账号在终端里敲一句自然语言它就能替你读代码、改文件、跑命令像一个待在 shell 里的轻量级编码助手。它解决的是三件事私有代码不出内网、不再为 token 付费、完全掌控模型和上下文。适合手上有一块能跑模型的显卡、或者团队想统一管理私有化模型的开发者。下面把选型、安装、参数和踩坑按实际路径过一遍。2. 为什么是 OllamaOpen Codex 的本地模型选型逻辑2.1 从 OpenAI Codex CLI 到 Open Codex差的是一层云端用过 OpenAI Codex CLI 的人对它俩的关系很好理解原版启动时会打出 WELCOME TO CODEX 横幅然后引导用户用 ChatGPT 账号登录之后所有的理解和补全都发生在云端。Open Codex 保留了这套终端交互的骨架把“登录云端”整步拿掉换成连接本机的模型服务。这不是换了个皮肤而是把整个数据链路搬回了本地。这类编码智能体的工作方式是一个循环先读你的需求列一个执行计划然后反复调用三类动作——读文件、改文件、执行 shell 命令每完成一步都把输出拿回来判断下一步。这个循环对延迟和隐私都很敏感。云端方案里每一次往返都要把上下文打成请求发出去仓库稍大一点开销和等待都成倍增长本地方案里模型就在旁边往返时间可以忽略代码内容也全程不离开机器。我一般把 Open Codex 当“本地沙箱里的结对程序员”用。它没有 IDE 那么重入口就是一个 shell 命令行适合已经习惯用 git 命令行提交代码、在 vim 或 VS Code 终端里干活的人。对团队来说它最大的价值是私有仓库不用出内网模型可以换成内部微调过的版本。2.2 Ollama 在这条链路里做了什么Ollama 的角色是本地模型运行时负责三件事拉模型、跑推理、把推理封装成 OpenAI 兼容的 HTTP API。Open Codex 不直接解析 GGUF 模型文件它只认 API默认就是 localhost:11434 上的那个服务。# 先确认 Ollama 的模型服务真的活着 curl http://localhost:11434/v1/chat/completions \ -H Content-Type: application/json \ -d {model:qwen2.5-coder:7b,messages:[{role:user,content:ping}]}这段 curl 值得存着它是整个项目排查的起点。Open Codex 出问题时先 curl 一下这个接口能通就说明模型侧没毛病问题出在 CLI 配置。参数上model 要和 ollama list 里显示的模型名完全一致messages 走标准 chat 格式。很多 FastAPI 项目、Dify 这类编排平台调 Ollama 也走同一套接口所以这条排查链路以后写别的工具照样用得上。为什么选 Ollama 而不选 vLLM、sglang 或 LM StudiovLLM 和 sglang 吞吐确实高但要先配 Python 环境、装依赖是给正式服务端准备的LM Studio 有图形界面鼠标点一点很方便但自动化、脚本化能力弱。Ollama 单个二进制、几乎零配置、能注册成服务自启对 Open Codex 这种终端工具来说是最省事的本地部署私有大模型的方案。Ollama 的几个环境变量也在这里一并说清OLLAMA_MODELS 控制模型存放目录OLLAMA_HOST 控制监听地址OLLAMA_KEEP_ALIVE 控制模型在内存里的驻留时间。还有一个容易忽略的点是上下文长度——Ollama 默认按模型元数据来编码智能体干活时建议把它顶到模型支持的上限常见做法是在 Modelfile 里写 num_ctx 参数或者用 OLLAMA_CONTEXT_LENGTH 环境变量统一改。改完用 ollama run 实测一下上下文不够时模型会答非所问这个现象后面避坑章还会碰到。2.3 给 Open Codex 选模型的三个标准代码能力得是专门做过代码预训练的模型。通用聊天模型写注释可以让它动业务逻辑经常翻车。上下文窗口编码会话增长很快文件内容、命令输出全往里面塞小于 16k 的模型干到一半基本就失忆。工具调用可靠性最容易忽略的一条。编码智能体靠结构化输出来决定调哪个工具、传什么参数模型如果不按格式输出AI 就只会答话不会动手。模型参数规模上下文我拿它干什么qwen2.5-coder7b / 14b / 32b以 ollama show 实测为准日常主力7b 快、14b 稳deepseek-coder-v216b中等偏长老机器 CPU 推理也能跑codellama7b / 13b较短兼容性测试、老项目复现选型口诀显存够就 14b 起步补测试、写模板这类重复活 7b 就够真要改业务逻辑小模型经常给一个“看起来对”但一编译就报错的答案。上下文和工具调用这两个指标直接决定了编码智能体能用多久、多听话。另外别迷信参数越大越好模型在本地跑不动一切都是白搭先用 ollama run 加载实测一轮比看榜单有用得多。3. 从零跑通Open Codex 与 Ollama 的安装和最小启动3.1 先装 Ollama两条路径和模型存放位置Linux 和 macOS 用官方安装脚本一条命令结束# 官方安装脚本装完会注册成系统服务 curl -fsSL https://ollama.com/install.sh | sh # 验证能看到列表就说明服务在跑 ollama listWindows 直接下载官方安装包装完 Ollama 自动注册成开机自启服务。装好后第一件事是确认模型存放位置模型文件动辄几个 GB默认丢在系统盘很快会被吃满。常见做法是把模型目录挪到数据盘# Linux先用环境变量指定模型目录再重启服务 mkdir -p /data/ollama/models export OLLAMA_MODELS/data/ollama/models ollama serveexport 只对当前 shell 生效想永久生效需要把环境变量写进系统服务配置。我的习惯是改 /etc/systemd/system/ollama.service 里的 Environment 行或者用 systemctl edit ollama.service 追加 EnvironmentOLLAMA_MODELS/data/ollama/models改完 systemctl daemon-reload systemctl restart ollama。Windows 上做法是设置用户环境变量 OLLAMA_MODELS 指向其他盘重启 Ollama 服务或注销重登。改完再用 ollama list 确认路径没生效的话列表会变空。这个步骤很多人跳过等 C 盘飘红再折腾就晚了算是血泪经验。如果 ollama serve 报端口占用多半是 11434 被旧进程占着先 lsof -i:11434 找到进程清掉再启动别图省事换端口后面 Open Codex 默认配置对着 11434 写换端口要两头改。3.2 装 Open Codex CLInpm 与 Node 版本检查Open Codex 走 npm 分发下载安装只需要一条命令。先确认 Node 环境node -v # 一般要求 18 以上具体以项目 README 为准 npm -v # 顺便确认 npm 本身可用然后全局安装。包名以官方 README 为准这里是 open-codexnpm install -g open-codex codex --version # 能输出版本号说明 CLI 装好了如果 npm 安装很慢先把默认 registry 切到国内镜像再装装完可切回npm config set registry https://registry.npmmirror.com这个镜像只影响 npm 拉包速度不动任何网络链路放心用。装完 codex --version 能输出版本号就说明 CLI 本身没问题。很多新手在这里卡住其实 node -v 和 npm -v 先各敲一遍能定位掉八成的装包问题剩下的多半是网络超时切镜像重装就能解决。卸载也简单npm uninstall -g open-codex 一条命令清干净不留残留。3.3 最小启动拉模型、起服务、跑第一个任务先把编码模型拉下来这里用 qwen2.5-coder:14b 做例子ollama pull qwen2.5-coder:14b ollama list # 确认模型已经到位 ollama serve # 前台跑看到 Listening on 11434 即可ollama serve 前台跑比较直观适合验证日常用建议交给服务方式管理系统重启后自动拉起。接下来进入测试项目目录启动 Open Codexcd ~/work/demo codex --model ollama/qwen2.5-coder:14b模型标识的写法以 Open Codex 文档为准常见格式是 ollama/模型名:标签。启动后先让它干一件小事验证整条链路codex 把当前目录下所有 TODO 注释列出来并按文件分组能正确列出来说明 CLI、Ollama、模型三方都通了。第一次跑会多花几秒做模型预热属正常。如果命令不存在先检查 Node 的全局 bin 目录是否在 PATH 里Windows 上装完一定要新开终端窗口再试。交互模式下会在用户目录生成会话文件方便 /resume 恢复这类会话文件占空间不大但积累久了也会乱定期清掉历史会话是个好习惯。提示先 curl 一次 11434 接口再开 Open Codex能省一半的排错时间。模型没起来时Open Codex 的报错往往很含糊容易让人误判成配置问题。4. 让 Open Codex 真正干活常用命令、必调参数与 Git 节奏4.1 终端里的高频命令速查交互模式下最常用的三个斜杠命令对应三种典型场景命令作用什么时候用/compact压缩会话历史上下文快满、模型开始答非所问时/model热切换模型想从小模型换成大模型重新跑一遍/resume恢复上次会话终端关了、会话没结束回来接着聊我用得最多的是 /compact。本地模型上下文窗口有限编码会话里夹着大量文件内容和命令输出几轮下来历史就很长。压缩后任务主线还在但细节会丢一些所以压缩完我会让它复述一遍当前计划确认没跑偏。/resume 适合跨天工作晚上关机前不用特意保存第二天回来恢复会话接着推进比重新描述一遍任务省事得多。非交互的一次性任务用 exec 子命令适合脚本和自动化场景# 一次性任务跑完直接退出适合批量处理 codex exec 给 utils/date.ts 补一个格式化成 YYYY-MM-DD 的函数并加单元测试exec 模式和交互模式共用同一份配置和模型区别只是不给你中途打断的机会。批量场景下我会先小步试跑一个任务验证输出格式再放开批量避免一次生成一堆不合预期的文件。4.2 必调的三个参数model、temperature 与 max_tokensOpen Codex 的配置以当前版本 README 为准一般在用户目录 .codex 下的 JSON 或 TOML 文件里。我最常动三个字段model ollama/qwen2.5-coder:14b model_provider ollama temperature 0.2 max_tokens 4096temperature 是最值得调的一个。代码任务要的是可复现0.2 是保守起点超过 0.5模型就开始自由发挥输出莫名其妙的重构和多余的“优化”。max_tokens 控制单次输出上限4096 能覆盖大多数单文件修改太小会导致长补丁被截断模型以为改完了其实没写完。model_provider 指向 ollama 时CLI 默认走 localhost:11434。参数我的常用值作用与注意temperature0.2越低越保守代码任务别超过 0.5max_tokens4096控制单次输出长度太小会截断补丁sandbox_modeworkspace-write限制可写目录危险命令先确认sandbox_mode 是另一个重要开关。编码智能体要执行命令默认会限制在指定工作区里跑危险操作需要你确认。我习惯开着只读任务用只读模式要改文件了再切写模式相当于给 AI 加了一道确认闸门。如果想让同一台 GPU 机器被局域网里的几台电脑共用可以在宿主机设 OLLAMA_HOST0.0.0.0把监听地址放开然后各机器把 API 地址指向它。注意两点别把这个端口裸奔到公网并发任务别开太多显存会被迅速吃满。4.3 和 Git 配合的日常节奏先看 diff 再提交Open Codex 本质是个会改文件的程序唯一安全的接入方式是让它活在 git 工作区里。我的固定流程git checkout -b feat/codex-xxx # 先开分支别在主分支上直接跑 codex 把登录接口的超时时间做成可配置项默认 30 秒 git diff # 逐行看它改了什么 git add -A git commit -m feat: 登录超时可配置关键动作是中间那步 git diff。AI 改代码模型再强也要人肉确认三件事有没有改到无关文件、有没有删掉不该删的逻辑、有没有留下调试残留。我见过它把两个相似函数当重复代码合并diff 上看着人畜无害跑测试才发现行为变了。跑完再决定要不要提交而不是让它自动 commit。这一步多花两分钟能省掉后面几个小时的排错。老手和新手的区别不在会不会用工具而在敢不敢让工具碰 git 历史。另外要清楚它的边界跨模块的大重构、涉及数据迁移的改动我不太会交给它。它的强项是局部修改——补测试、修 bug、加配置、写脚本。把任务拆到“一个任务动一块”的粒度输出质量会明显上一个台阶。5. 避坑Open Codex 本地化最容易翻车的 5 个问题5.1 npm 装包卡死或报平台依赖缺失现象npm install 卡在 downloading 半天不动或者装完启动时报一堆 missing optional dependency for platform 的错误提示 reinstall。原因默认 registry 连接质量一般大包容易超时这类 CLI 往往带着平台相关的二进制包安装中断后 node_modules 里的对应文件没落全。解决先切国内 npm 镜像再装报平台依赖缺失就删掉全局包重装一遍别手动往 node_modules 里塞文件。这类平台二进制缺失的问题重装比修依赖快得多别跟玄学较劲。装完一定执行 codex --version 验证能输出版本才算完。5.2 Ollama 拉模型下到一半不动现象进度条卡在某个百分比重试还是老位置几 GB 的模型下到深夜都没完。原因模型文件体量大官方源带宽有限长连接容易被掐断。解决走官方文档里的离线导入路径——先把 GGUF 文件下载到本地写一个 Modelfile 指向它再 ollama create 导入# 离线导入FROM 一行指向本地 GGUF然后 create 进 Ollama echo FROM /data/models/qwen2.5-coder-14b-q4_K_M.gguf Modelfile ollama create qwen2.5-coder-offline -f Modelfile导入前顺手校验 sha256文件损坏不会报错但跑起来推理会乱这个校验别省。5.3 上下文一长模型就“失忆”现象改到一半开始重复读同一个文件或者把早先确认过的结论推翻重来。原因本地模型上下文窗口有限对话历史、文件内容、命令输出累加后真正可用的空间被挤没了。解决把大任务拆成小步每步只让它动一个文件上下文吃紧时用 /compact 压缩历史选模型优先挑长上下文版本。带思考模式的模型会额外吐出大量中间推理纯浪费上下文。Gemma 这类带 thinking 开关的模型可以在请求参数里显式关掉思考或者干脆选不带思考的代码模型。5.4 模型编造命令和文件名现象输出里出现项目里根本不存在的路径或者执行了一个看着合理但没安装的命令。原因小参数模型的工具调用格式易出错在“决定调用哪个工具、传什么参数”这一步产生幻觉。解决换 14b 以上模型temperature 调到 0.2 以下打开沙箱模式让它只能在工作区里执行命令危险操作先确认。遇到反复横跳的模型最实际的办法是换模型别靠改提示词硬调。5.5 Windows 下 PowerShell 不让跑脚本现象启动时报“无法加载文件因为在此系统上禁止运行脚本”CLI 根本没机会跑起来。原因PowerShell 默认执行策略是 Restricted。解决以当前用户放开执行策略然后重开终端Set-ExecutionPolicy -Scope CurrentUser RemoteSignedWindows 上装完 Ollama 和 Open Codex 都要新开终端窗口PATH 才会刷新。如果 ollama serve 崩溃退出先敲 nvidia-smi 看显卡驱动和显存占用确认没被别的进程占满再试 CPU 推理做对照能快速区分是 GPU 问题还是服务本身问题。6. 进阶会话压缩、输出验证与一个长期习惯Open Codex 用久了会发现真正决定产出质量的是“验证”而不是“生成”。我给自己定的三个验证手段git diff 逐行审、让 agent 跑测试、改完让它写一段改动说明对比预期。测试通过不代表逻辑对但测试都过不了一定有问题。还有一个习惯值得长期坚持每次开新任务前先把上一个任务收尾干净。终端里挂着一堆未提交的代码智能体读目录时把这些残留当上下文轻则答非所问重则把旧改动一起打包进新任务。我的做法是任务结束立刻提交或回滚保持工作区干净再喊它干活。会话管理上长任务我会主动在关键节点 /compact 一次并把压缩后的计划念给它听确认主线没丢。Ollama 侧的 OLLAMA_KEEP_ALIVE 也值得看一眼默认模型会驻留内存机器上多个项目切来切去时把驻留时间调短可以省显存。验证手段配合干净工作区这套组合跑下来Open Codex 的输出质量已经能持续达到“人工审一遍就能提交”的状态。希望帮到你。本文还有配套的精品资源点击获取 Open Codex 实战：用 Ollama 打造本地终端 AI 编码助手
简介Open Codex 是一款完全开源的命令行 AI 助手灵感来自 OpenAI Codex定位于在终端中运行的轻量级编码代理。它重点支持本地语言模型并与 Ollama 深度集成适合希望离线使用智能编码辅助、保护代码隐私的开发者也可用于自动化补全、代码示例生成与项目协作等场景。压缩包内共 15 个文件以 8 个 Python 脚本为核心实现辅助以 pyproject.toml、锁文件、版本配置和 Markdown 说明文档另附演示动图可快速了解界面与用法整体仅 1.68MB轻量易部署包内目录结构清晰核心模块与配置分离便于按需修改。目前已有 1512 人学习下载。通过这份源码包读者可获得完整的命令行工具实现、依赖管理与运行配置既能直接接入 Ollama 使用也可基于开源代码二次开发深入理解本地 AI 编码助手的工作机制。1. Open Codex 是什么一个让本地模型替你写代码的终端助手Open Codex 是一个完全开源的命令行 AI 助手灵感直接来自 OpenAI 的 Codex CLI但把模型层换成了本地推理并与 Ollama 完全集成。启动后不用登录任何云账号在终端里敲一句自然语言它就能替你读代码、改文件、跑命令像一个待在 shell 里的轻量级编码助手。它解决的是三件事私有代码不出内网、不再为 token 付费、完全掌控模型和上下文。适合手上有一块能跑模型的显卡、或者团队想统一管理私有化模型的开发者。下面把选型、安装、参数和踩坑按实际路径过一遍。2. 为什么是 OllamaOpen Codex 的本地模型选型逻辑2.1 从 OpenAI Codex CLI 到 Open Codex差的是一层云端用过 OpenAI Codex CLI 的人对它俩的关系很好理解原版启动时会打出 WELCOME TO CODEX 横幅然后引导用户用 ChatGPT 账号登录之后所有的理解和补全都发生在云端。Open Codex 保留了这套终端交互的骨架把“登录云端”整步拿掉换成连接本机的模型服务。这不是换了个皮肤而是把整个数据链路搬回了本地。这类编码智能体的工作方式是一个循环先读你的需求列一个执行计划然后反复调用三类动作——读文件、改文件、执行 shell 命令每完成一步都把输出拿回来判断下一步。这个循环对延迟和隐私都很敏感。云端方案里每一次往返都要把上下文打成请求发出去仓库稍大一点开销和等待都成倍增长本地方案里模型就在旁边往返时间可以忽略代码内容也全程不离开机器。我一般把 Open Codex 当“本地沙箱里的结对程序员”用。它没有 IDE 那么重入口就是一个 shell 命令行适合已经习惯用 git 命令行提交代码、在 vim 或 VS Code 终端里干活的人。对团队来说它最大的价值是私有仓库不用出内网模型可以换成内部微调过的版本。2.2 Ollama 在这条链路里做了什么Ollama 的角色是本地模型运行时负责三件事拉模型、跑推理、把推理封装成 OpenAI 兼容的 HTTP API。Open Codex 不直接解析 GGUF 模型文件它只认 API默认就是 localhost:11434 上的那个服务。# 先确认 Ollama 的模型服务真的活着 curl http://localhost:11434/v1/chat/completions \ -H Content-Type: application/json \ -d {model:qwen2.5-coder:7b,messages:[{role:user,content:ping}]}这段 curl 值得存着它是整个项目排查的起点。Open Codex 出问题时先 curl 一下这个接口能通就说明模型侧没毛病问题出在 CLI 配置。参数上model 要和 ollama list 里显示的模型名完全一致messages 走标准 chat 格式。很多 FastAPI 项目、Dify 这类编排平台调 Ollama 也走同一套接口所以这条排查链路以后写别的工具照样用得上。为什么选 Ollama 而不选 vLLM、sglang 或 LM StudiovLLM 和 sglang 吞吐确实高但要先配 Python 环境、装依赖是给正式服务端准备的LM Studio 有图形界面鼠标点一点很方便但自动化、脚本化能力弱。Ollama 单个二进制、几乎零配置、能注册成服务自启对 Open Codex 这种终端工具来说是最省事的本地部署私有大模型的方案。Ollama 的几个环境变量也在这里一并说清OLLAMA_MODELS 控制模型存放目录OLLAMA_HOST 控制监听地址OLLAMA_KEEP_ALIVE 控制模型在内存里的驻留时间。还有一个容易忽略的点是上下文长度——Ollama 默认按模型元数据来编码智能体干活时建议把它顶到模型支持的上限常见做法是在 Modelfile 里写 num_ctx 参数或者用 OLLAMA_CONTEXT_LENGTH 环境变量统一改。改完用 ollama run 实测一下上下文不够时模型会答非所问这个现象后面避坑章还会碰到。2.3 给 Open Codex 选模型的三个标准代码能力得是专门做过代码预训练的模型。通用聊天模型写注释可以让它动业务逻辑经常翻车。上下文窗口编码会话增长很快文件内容、命令输出全往里面塞小于 16k 的模型干到一半基本就失忆。工具调用可靠性最容易忽略的一条。编码智能体靠结构化输出来决定调哪个工具、传什么参数模型如果不按格式输出AI 就只会答话不会动手。模型参数规模上下文我拿它干什么qwen2.5-coder7b / 14b / 32b以 ollama show 实测为准日常主力7b 快、14b 稳deepseek-coder-v216b中等偏长老机器 CPU 推理也能跑codellama7b / 13b较短兼容性测试、老项目复现选型口诀显存够就 14b 起步补测试、写模板这类重复活 7b 就够真要改业务逻辑小模型经常给一个“看起来对”但一编译就报错的答案。上下文和工具调用这两个指标直接决定了编码智能体能用多久、多听话。另外别迷信参数越大越好模型在本地跑不动一切都是白搭先用 ollama run 加载实测一轮比看榜单有用得多。3. 从零跑通Open Codex 与 Ollama 的安装和最小启动3.1 先装 Ollama两条路径和模型存放位置Linux 和 macOS 用官方安装脚本一条命令结束# 官方安装脚本装完会注册成系统服务 curl -fsSL https://ollama.com/install.sh | sh # 验证能看到列表就说明服务在跑 ollama listWindows 直接下载官方安装包装完 Ollama 自动注册成开机自启服务。装好后第一件事是确认模型存放位置模型文件动辄几个 GB默认丢在系统盘很快会被吃满。常见做法是把模型目录挪到数据盘# Linux先用环境变量指定模型目录再重启服务 mkdir -p /data/ollama/models export OLLAMA_MODELS/data/ollama/models ollama serveexport 只对当前 shell 生效想永久生效需要把环境变量写进系统服务配置。我的习惯是改 /etc/systemd/system/ollama.service 里的 Environment 行或者用 systemctl edit ollama.service 追加 EnvironmentOLLAMA_MODELS/data/ollama/models改完 systemctl daemon-reload systemctl restart ollama。Windows 上做法是设置用户环境变量 OLLAMA_MODELS 指向其他盘重启 Ollama 服务或注销重登。改完再用 ollama list 确认路径没生效的话列表会变空。这个步骤很多人跳过等 C 盘飘红再折腾就晚了算是血泪经验。如果 ollama serve 报端口占用多半是 11434 被旧进程占着先 lsof -i:11434 找到进程清掉再启动别图省事换端口后面 Open Codex 默认配置对着 11434 写换端口要两头改。3.2 装 Open Codex CLInpm 与 Node 版本检查Open Codex 走 npm 分发下载安装只需要一条命令。先确认 Node 环境node -v # 一般要求 18 以上具体以项目 README 为准 npm -v # 顺便确认 npm 本身可用然后全局安装。包名以官方 README 为准这里是 open-codexnpm install -g open-codex codex --version # 能输出版本号说明 CLI 装好了如果 npm 安装很慢先把默认 registry 切到国内镜像再装装完可切回npm config set registry https://registry.npmmirror.com这个镜像只影响 npm 拉包速度不动任何网络链路放心用。装完 codex --version 能输出版本号就说明 CLI 本身没问题。很多新手在这里卡住其实 node -v 和 npm -v 先各敲一遍能定位掉八成的装包问题剩下的多半是网络超时切镜像重装就能解决。卸载也简单npm uninstall -g open-codex 一条命令清干净不留残留。3.3 最小启动拉模型、起服务、跑第一个任务先把编码模型拉下来这里用 qwen2.5-coder:14b 做例子ollama pull qwen2.5-coder:14b ollama list # 确认模型已经到位 ollama serve # 前台跑看到 Listening on 11434 即可ollama serve 前台跑比较直观适合验证日常用建议交给服务方式管理系统重启后自动拉起。接下来进入测试项目目录启动 Open Codexcd ~/work/demo codex --model ollama/qwen2.5-coder:14b模型标识的写法以 Open Codex 文档为准常见格式是 ollama/模型名:标签。启动后先让它干一件小事验证整条链路codex 把当前目录下所有 TODO 注释列出来并按文件分组能正确列出来说明 CLI、Ollama、模型三方都通了。第一次跑会多花几秒做模型预热属正常。如果命令不存在先检查 Node 的全局 bin 目录是否在 PATH 里Windows 上装完一定要新开终端窗口再试。交互模式下会在用户目录生成会话文件方便 /resume 恢复这类会话文件占空间不大但积累久了也会乱定期清掉历史会话是个好习惯。提示先 curl 一次 11434 接口再开 Open Codex能省一半的排错时间。模型没起来时Open Codex 的报错往往很含糊容易让人误判成配置问题。4. 让 Open Codex 真正干活常用命令、必调参数与 Git 节奏4.1 终端里的高频命令速查交互模式下最常用的三个斜杠命令对应三种典型场景命令作用什么时候用/compact压缩会话历史上下文快满、模型开始答非所问时/model热切换模型想从小模型换成大模型重新跑一遍/resume恢复上次会话终端关了、会话没结束回来接着聊我用得最多的是 /compact。本地模型上下文窗口有限编码会话里夹着大量文件内容和命令输出几轮下来历史就很长。压缩后任务主线还在但细节会丢一些所以压缩完我会让它复述一遍当前计划确认没跑偏。/resume 适合跨天工作晚上关机前不用特意保存第二天回来恢复会话接着推进比重新描述一遍任务省事得多。非交互的一次性任务用 exec 子命令适合脚本和自动化场景# 一次性任务跑完直接退出适合批量处理 codex exec 给 utils/date.ts 补一个格式化成 YYYY-MM-DD 的函数并加单元测试exec 模式和交互模式共用同一份配置和模型区别只是不给你中途打断的机会。批量场景下我会先小步试跑一个任务验证输出格式再放开批量避免一次生成一堆不合预期的文件。4.2 必调的三个参数model、temperature 与 max_tokensOpen Codex 的配置以当前版本 README 为准一般在用户目录 .codex 下的 JSON 或 TOML 文件里。我最常动三个字段model ollama/qwen2.5-coder:14b model_provider ollama temperature 0.2 max_tokens 4096temperature 是最值得调的一个。代码任务要的是可复现0.2 是保守起点超过 0.5模型就开始自由发挥输出莫名其妙的重构和多余的“优化”。max_tokens 控制单次输出上限4096 能覆盖大多数单文件修改太小会导致长补丁被截断模型以为改完了其实没写完。model_provider 指向 ollama 时CLI 默认走 localhost:11434。参数我的常用值作用与注意temperature0.2越低越保守代码任务别超过 0.5max_tokens4096控制单次输出长度太小会截断补丁sandbox_modeworkspace-write限制可写目录危险命令先确认sandbox_mode 是另一个重要开关。编码智能体要执行命令默认会限制在指定工作区里跑危险操作需要你确认。我习惯开着只读任务用只读模式要改文件了再切写模式相当于给 AI 加了一道确认闸门。如果想让同一台 GPU 机器被局域网里的几台电脑共用可以在宿主机设 OLLAMA_HOST0.0.0.0把监听地址放开然后各机器把 API 地址指向它。注意两点别把这个端口裸奔到公网并发任务别开太多显存会被迅速吃满。4.3 和 Git 配合的日常节奏先看 diff 再提交Open Codex 本质是个会改文件的程序唯一安全的接入方式是让它活在 git 工作区里。我的固定流程git checkout -b feat/codex-xxx # 先开分支别在主分支上直接跑 codex 把登录接口的超时时间做成可配置项默认 30 秒 git diff # 逐行看它改了什么 git add -A git commit -m feat: 登录超时可配置关键动作是中间那步 git diff。AI 改代码模型再强也要人肉确认三件事有没有改到无关文件、有没有删掉不该删的逻辑、有没有留下调试残留。我见过它把两个相似函数当重复代码合并diff 上看着人畜无害跑测试才发现行为变了。跑完再决定要不要提交而不是让它自动 commit。这一步多花两分钟能省掉后面几个小时的排错。老手和新手的区别不在会不会用工具而在敢不敢让工具碰 git 历史。另外要清楚它的边界跨模块的大重构、涉及数据迁移的改动我不太会交给它。它的强项是局部修改——补测试、修 bug、加配置、写脚本。把任务拆到“一个任务动一块”的粒度输出质量会明显上一个台阶。5. 避坑Open Codex 本地化最容易翻车的 5 个问题5.1 npm 装包卡死或报平台依赖缺失现象npm install 卡在 downloading 半天不动或者装完启动时报一堆 missing optional dependency for platform 的错误提示 reinstall。原因默认 registry 连接质量一般大包容易超时这类 CLI 往往带着平台相关的二进制包安装中断后 node_modules 里的对应文件没落全。解决先切国内 npm 镜像再装报平台依赖缺失就删掉全局包重装一遍别手动往 node_modules 里塞文件。这类平台二进制缺失的问题重装比修依赖快得多别跟玄学较劲。装完一定执行 codex --version 验证能输出版本才算完。5.2 Ollama 拉模型下到一半不动现象进度条卡在某个百分比重试还是老位置几 GB 的模型下到深夜都没完。原因模型文件体量大官方源带宽有限长连接容易被掐断。解决走官方文档里的离线导入路径——先把 GGUF 文件下载到本地写一个 Modelfile 指向它再 ollama create 导入# 离线导入FROM 一行指向本地 GGUF然后 create 进 Ollama echo FROM /data/models/qwen2.5-coder-14b-q4_K_M.gguf Modelfile ollama create qwen2.5-coder-offline -f Modelfile导入前顺手校验 sha256文件损坏不会报错但跑起来推理会乱这个校验别省。5.3 上下文一长模型就“失忆”现象改到一半开始重复读同一个文件或者把早先确认过的结论推翻重来。原因本地模型上下文窗口有限对话历史、文件内容、命令输出累加后真正可用的空间被挤没了。解决把大任务拆成小步每步只让它动一个文件上下文吃紧时用 /compact 压缩历史选模型优先挑长上下文版本。带思考模式的模型会额外吐出大量中间推理纯浪费上下文。Gemma 这类带 thinking 开关的模型可以在请求参数里显式关掉思考或者干脆选不带思考的代码模型。5.4 模型编造命令和文件名现象输出里出现项目里根本不存在的路径或者执行了一个看着合理但没安装的命令。原因小参数模型的工具调用格式易出错在“决定调用哪个工具、传什么参数”这一步产生幻觉。解决换 14b 以上模型temperature 调到 0.2 以下打开沙箱模式让它只能在工作区里执行命令危险操作先确认。遇到反复横跳的模型最实际的办法是换模型别靠改提示词硬调。5.5 Windows 下 PowerShell 不让跑脚本现象启动时报“无法加载文件因为在此系统上禁止运行脚本”CLI 根本没机会跑起来。原因PowerShell 默认执行策略是 Restricted。解决以当前用户放开执行策略然后重开终端Set-ExecutionPolicy -Scope CurrentUser RemoteSignedWindows 上装完 Ollama 和 Open Codex 都要新开终端窗口PATH 才会刷新。如果 ollama serve 崩溃退出先敲 nvidia-smi 看显卡驱动和显存占用确认没被别的进程占满再试 CPU 推理做对照能快速区分是 GPU 问题还是服务本身问题。6. 进阶会话压缩、输出验证与一个长期习惯Open Codex 用久了会发现真正决定产出质量的是“验证”而不是“生成”。我给自己定的三个验证手段git diff 逐行审、让 agent 跑测试、改完让它写一段改动说明对比预期。测试通过不代表逻辑对但测试都过不了一定有问题。还有一个习惯值得长期坚持每次开新任务前先把上一个任务收尾干净。终端里挂着一堆未提交的代码智能体读目录时把这些残留当上下文轻则答非所问重则把旧改动一起打包进新任务。我的做法是任务结束立刻提交或回滚保持工作区干净再喊它干活。会话管理上长任务我会主动在关键节点 /compact 一次并把压缩后的计划念给它听确认主线没丢。Ollama 侧的 OLLAMA_KEEP_ALIVE 也值得看一眼默认模型会驻留内存机器上多个项目切来切去时把驻留时间调短可以省显存。验证手段配合干净工作区这套组合跑下来Open Codex 的输出质量已经能持续达到“人工审一遍就能提交”的状态。希望帮到你。本文还有配套的精品资源点击获取