最近把开发环境从老 Mac 整体搬迁到 Linux 工作机折腾到半夜的一项就是 OpenAI Codex CLI。Codex 是跑在终端里的编程智能体能在你的项目上下文里直接改代码、执行命令、读日志登录之后整个工作流非常顺手。但它安装、登录、迁移这三步里Linux 上的坑比预想多不少尤其是登录凭证的迁移、模型服务商的切换、还有那些报错信息背后的真实原因。这篇就是一份从零到能用的记录给同样准备在 Linux 工作机上铺开 Codex 的人做参考。1. 为什么偏偏要在 Linux 工作机上折腾 Codex1.1 Codex 到底是什么它解决了什么问题Codex 是 OpenAI 开源的命令行 AI 编程工具本质上是一个跑在终端里的 agent。和你在编辑器里用 AI 补全代码不同Codex 能直接感知当前目录下的代码仓库结构自己读文件、自己执行命令、自己根据运行结果修 Bug。你只需要在终端里打开某个项目目录跑一句codex进入交互模式剩下的活儿它可以一路干下去从解释报错到生成测试用例再到批量替换代码逻辑体验非常接近“请了一个能操作终端的实习生”。我自己的主力使用场景有三类一是让它在陌生的老项目里快速定位问题它能把代码一层层翻下去复制报错上下文比人肉 grep 高效得多二是处理批量重构比如把一个模块的接口调用方式全部改掉这类工作人工做容易漏Codex 会先盘点调用点再动手三是作为终端里的“答疑机”写脚本时遇到不熟悉的系统调用直接问它它给出的答案通常还附带当前目录的代码上下文比单独问通用聊天工具要准。1.2 为什么网上教程很多却仍然容易翻车Codex 的官方 README 和网上各种教程安装部分写得都不复杂无非是 Node 装一下、npm 装一下、跑一句codex login。但真正落到“一台全新的 Linux 工作机”上你会发现事情没那么顺利。Linux 发行版五花八门Node 版本参差不齐全局 npm 目录权限、系统自带的旧版本 Python 干扰、终端环境变量不干净都会让安装或登录莫名其妙失败。更隐蔽的是迁移场景。很多人是先在主力机上用了一段时间 Codex积累了登录态、配置文件、甚至自定义的模型服务商配置然后换到另一台 Linux 机器时以为只要重新装一遍再登录就行。实际上只要把正确的文件搬过去压根不需要重新授权也不需要重新配模型能省很多事。但搬文件这一步本身也有坑文件权限不对、目录用户不对、环境变量没跟着迁都会让新机器上显示“未登录”或者说“配置不存在”。所以这篇不仅讲怎么安装登录更把迁移和排查串在一起写。毕竟按现在的趋势Linux 工作机包括各类国产发行版会越来越多Codex 这类终端 agent 也几乎成了开发者的标配工具尽早把这些坑趟平后面换机器就是十分钟的事。2. 安装前的环境核对Node 版本、npm 权限与终端要求2.1 Node 版本是第一道坎Codex CLI 是 npm 包所以第一步是装 Node.js。如果你在 Linux 上用系统自带的包管理器安装很可能装到一个非常老的版本。比如某些服务器版的 CentOS默认源里的 Node 还停留在 6.x 或 8.x那装 Codex 会直接报语法错误甚至依赖解析失败。我建议先跑一句node -v看看现有版本。Codex 对 Node 版本的要求是 18 以上的 LTS 版本但 18 以下基本不用考虑20 和 22 我都实测过都能正常工作。如果版本太低别用系统的包管理器去升而是直接用 nvm 管理这样和系统自带环境隔离也方便以后切换。# 安装 nvm也可以用你熟悉的任何节点版本管理器 curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash # 重新加载 shell 配置 source ~/.bashrc # 安装并使用 Node 20 LTS nvm install 20 nvm use 20 # 确认版本 node -v npm -v注意nvm 的安装脚本会往~/.bashrc里追加环境变量如果你用的是 zsh记得手动把对应的配置加到~/.zshrc否则新开的终端窗口找不到 nvm。这是 Linux 上最容易踩的第一个“环境没生效”问题。2.2 npm 全局安装权限别急着 sudo装完 Node 之后安装 Codex 本身很简单npm install -g openai/codex但很多 Linux 用户在跑这句时会遇到EACCES权限报错因为系统级的全局 node_modules 目录默认归 root 所有。这时候最常见的冲动是加 sudo 重跑一遍我也这么干过但强烈不建议。用 sudo 安装的全局包运行时的文件属主是 root等你切到普通用户想读取配置时容易碰到各种权限不一致的怪问题。正确做法是给 npm 设置一个当前用户有权限的全局安装目录mkdir -p ~/.npm-global npm config set prefix ~/.npm-global然后在~/.bashrc或~/.zshrc里加一行export PATH~/.npm-global/bin:$PATH保存后重新加载配置再执行 npm 全局安装就不需要 sudo 了。安装完成后用codex --version验证能输出版本号就说明环境已经打通。2.3 其他容易忽略的 Linux 环境细节除了 NodeCodex 运行还需要系统能正常发起 HTTPS 请求后续登录和拉取模型都要走网络。我建议第一遍尝试时尽量在干净、能够直连外网的环境里操作不要在复杂网络出口后面测试否则一旦报错很难分清是工具问题还是链路问题。终端方面虽然 Codex 在普通终端也能跑但交互式界面里有很多光标控制、颜色输出和类似 TUI 的组件建议用支持 ANSI 转义序列的现代终端比如 GNOME Terminal、Konsole、Windows Terminal 连接 WSL 都行。另外如果你的 Linux 工作机是带桌面环境的直接开终端操作就行如果是纯服务器用 SSH 连接时也要确保终端类型是xterm-256color否则显示可能会乱。还有一个容易被忽略的是 glibc 版本。Codex 的某些依赖在编译后对系统 libc 版本有最低要求太老的发行版比如 CentOS 7 默认的 glibc 2.17可能在启动时直接报GLIBC_2.28 not found。遇到这种情况要么升级系统要么用官方提供的二进制安装方式代替 npm 方式后者往往静态链接会更好一些。不过对主流的 Ubuntu 20.04 以上、Debian 11 以上的系统npm 安装就很稳。3. 登录认证全流程以及 auth.json 是怎么生成的3.1 codex login 的交互流程安装完成并跑通版本号之后下一步就是登录。多数教程会直接告诉你跑codex login但当时我第一次跑的时候看到终端里输出一大段授权地址和设备代码还以为卡住了后来才搞明白交互逻辑。实际过程是这样的运行codex login后工具会先在本地生成一个临时授权请求然后在终端打印一个形如https://chatgpt.com/authorize/device?user_codeXXXX-XXXX的链接同时尝试调用系统默认浏览器打开它。如果你是在无桌面的服务器上 SSH 登录的浏览器不会自动打开但你可以手动把链接复制到任何一台有浏览器的机器上访问。在浏览器里完成 ChatGPT 账号登录并点击授权之后终端里的 codex 会自动检测到授权完成然后下载所需的模型元数据最终出现一个简单的确认信息表示登录成功。整条链路走到这里Codex 才会真正开始可用。3.2 登录成功和失败怎么判断一个很容易让新手困惑的地方是codex login成功后终端里并没有特别醒目的提示有时候只是一句类似 “Successfully logged in” 的话然后马上回到提示符。很多人以为没装上转头又跑了一遍登录其实没必要。判断是否登录成功最直接的方法是找到生成的凭证文件。登录成功之后Codex 会在当前用户的 home 目录下创建一个.codex文件夹里面有一个auth.json文件内容长这样{ OPENAI_API_KEY: sk-..., tokens: { id_token: ..., access_token: ..., refresh_token: ... }, last_refresh: 2025-... }如果你的~/.codex/auth.json长这样说明登录确实成功了。这个文件就是 Codex 后续和 OpenAI 服务端通信的凭证依据也是我们后面迁移时要重点照顾的东西。如果你跑了codex login之后终端长期不出现授权链接或者浏览器打开后页面报错大概率是网络链路问题如果浏览器完成授权后终端迟迟没反应则可能是本地进程没能访问到回调地址或者系统时间偏差导致令牌校验失败。先检查系统时间date再用浏览器访问授权链接时注意是否能打开页面就可以逐层缩小范围。3.3 用 API Key 认证的另一种方式除了 ChatGPT 账号 OAuth 登录Codex 也支持直接用 API Key 认证。这种方式更适合团队内部共享的开发机或者你本来就是在 OpenAI 开放平台上用 API 的开发者。方式也很简单在~/.codex/auth.json里手动写入或者通过环境变量设置export OPENAI_API_KEYsk-你的key设置好之后运行codex时工具会优先读取auth.json如果没有账号 token就尝试环境变量里的 API Key。我自己在服务器环境里更常用这种方式因为不需要在服务器上走浏览器授权流程只要运维在配置管理里下发一个环境变量就行。这里有个小提醒API Key 很容易被自己“手滑”打印到 shell 历史记录里尤其是用交互模式在终端里临时 export 的。建议把 export 语句写进~/.bashrc然后chmod 600 ~/.bashrc或者用 direnv 按目录管理别直接用 echo 之类的命令临时设置。4. 工作机迁移搬走这 4 个文件新机器直接续用4.1 ~/.codex 目录到底存了什么很多人以为换机器就得重新登录其实 Codex 的登录态和其他工具的 token 一样都是可以迁移的。前提是你得知道配置到底存在哪里。Linux 上Codex 的所有用户级数据都放在~/.codex/目录下主要有这么几类路径作用是否需要迁移~/.codex/auth.json登录凭证OAuth token 或 API Key必须要~/.codex/config.toml模型、model provider、个性化参数配置必须要~/.codex/sessions/历史会话记录按项目和时间分目录可选~/.codex/log/Codex 运行日志不必要~/.codex/下的缓存文件模型元数据等缓存不必要会自动重建所以最小迁移清单其实就是两个文件auth.json和config.toml。如果你是重度用户想把之前的会话记录也带过去那就把sessions/目录一起打包不过它会占点空间而且如果会话特别多复制的时候会慢一些。4.2 最小搬迁步骤我实际验证过的迁移流程按顺序做五分钟内能完成大部分工作。第一在旧机器上把配置文件打包cd ~/.codex tar czf codex-config.tar.gz auth.json config.toml sessions optional第二把压缩包传到新机器上。有内网就用 scp没有就随便走你团队习惯的文件传输方式。传完之后解压mkdir -p ~/.codex tar xzf codex-config.tar.gz -C ~/.codex第三也是最容易忽视的一步检查文件权限chmod 600 ~/.codex/auth.json chmod 644 ~/.codex/config.tomlauth.json里面是敏感凭证权限必须是 600仅当前用户可读写。如果从另一台机器复制过来后权限被设成了全局可读某些版本的 Codex 会直接拒绝读取或者在日志里提示不安全权限。第四直接跑codex验证。如果新机器网络正常它会直接加载auth.json里的凭证不需要重新走授权流程。你可以先跑一个简单的codex exec say hello之类的小命令看能不能正常返回结果。4.3 文件权限和用户所有者的坑在 Linux 上迁移时比权限数字更容易踩的坑是“文件属主”。比如你原来在服务器上是 root 用户跑的 Codex~/.codex整个目录的属主是 root现在切到普通用户 devops 下即使把文件复制过去了devops 用户也不一定读得了 key或者 Codex 运行时没有权限写sessions/目录。迁完之后务必检查一遍目录属主ls -la ~/.codex/如果所有者和当前登录用户不一致执行sudo chown -R $(whoami):$(whoami) ~/.codex否则你会在运行 codex 时遇到莫名的 IO 报错或者在保存会话时静默失败。这个“静默失败”最坑因为表面上看工具能跑但历史记录就是存不进去排查一圈才发现是写入权限的问题。4.4 环境变量和 shell 配置也要一起迁还有一个迁移盲区就是环境变量。如果你之前在~/.bashrc、~/.zshrc、~/.profile或/etc/environment里设置过这些变量它们并不会写在~/.codex/config.toml里而是存在于 shell 配置中OPENAI_API_KEYAPI Key 认证方式下必备自定义模型服务商对应的 Key比如后面要讲的接入 DeepSeek可能会用DEEPSEEK_API_KEY一些自定义的 base URL 环境变量如果配置过也需要同步迁移完 Codex 本身的文件后记得在新机器的 shell 配置里搜索一下有没有这些 export 语句。没有的话补上然后重新加载配置source ~/.bashrc echo $DEEPSEEK_API_KEY如果你是在服务器上运维可能还需要考虑把环境变量放到 systemd service 或 tmux 会话对应的环境里这个就看个人习惯了。5. 接入 DeepSeek 等第三方模型的 config.toml 写法5.1 为什么要自己改 model_providers默认情况下Codex 是绑定 OpenAI 自家模型服务的登录也是走 ChatGPT 账号授权。但在实际开发中不少人会因为账号地区限制、团队预算、或者单纯想对比不同模型的代码能力希望把它切换成其他兼容 OpenAI API 格式的模型服务商。Codex 自带的config.toml里支持一个model_providers配置段就是专门干这个用的。只要目标服务商提供 OpenAI 兼容的 REST API理论上都可以接进来。DeepSeek 是这几个方案里配置最简单、社区反馈也最多的一种我就以它为例。5.2 配置示例逐字段讲打开~/.codex/config.toml如果没有就新建一个。只改模型服务商一个最小配置长这样model deepseek-chat model_provider deepseek [model_providers.deepseek] name DeepSeek base_url https://api.deepseek.com/v1 env_key DEEPSEEK_API_KEY wire_api chat逐行解释一下这些字段是什么意思。model是全局默认模型名model_provider则告诉 Codex 用哪个 provider。如果你只接了一个第三方服务这两个值配好就行如果还想保留 OpenAI 的配置也可以不设全局 model而是在运行时用--model provider/model临时指定。[model_providers.deepseek]这一段是核心。name只是一个展示名可以随便写base_url是 API 地址必须是服务商文档里给的完整路径DeepSeek 的 OpenAI 兼容接口地址是https://api.deepseek.com/v1这里注意不能漏掉后面的/v1漏了的话请求会打到不存在的路由上env_key指定从哪个环境变量读取 API Key而不是直接把 key 明文写在 toml 里这样更安全也更方便迁移wire_api表示接口风格DeepSeek 兼容的是 chat/completions 这一套所以写chat。配好之后在 shell 里设置环境变量export DEEPSEEK_API_KEYsk-你的deepseek密钥然后运行codex它就会使用 DeepSeek 的模型来处理请求。5.3 切换后的验证配置完成后建议先跑一次非交互的小任务确认整条链路是通的codex exec --model deepseek-chat 介绍一下当前目录如果工具能正常返回内容说明 base_url、env_key、模型名三者的组合没问题。如果返回401基本是 API Key 配错了返回404就要检查 base_url 是不是少了/v1路径返回模型不存在之类的错误则多半是模型名要改成服务商文档里的别名比如 DeepSeek 有时也叫deepseek-reasoner。我第一次配置时就栽在模型名上因为想当然把deepseek-coder当成默认模型填进去结果 DeepSeek 官方的 OpenAI 兼容接口并不认这个旧名字。查了文档才发现要用deepseek-chat或deepseek-reasoner换上之后立刻通了。5.4 第三方模型配置和迁移的关系接好了第三方模型之后config.toml的迁移价值就体现出来了。你在旧机器上把 DeepSeek 的 provider 和模型名都调好新机器上做完最小迁移后这些配置跟着就过去了唯一要补的就是环境变量里那个 key。所以更完整的迁移清单其实是三部分~/.codex/下的配置文件、shell 里的环境变量、以及系统网络出口。前两者都是文件级的操作第三部分在新机器第一次运行时就该确认好。这样你换一台 Linux 工作机不需要重新登录、不需要重新找配置模板十分钟内就能恢复完全一样的 Codex 使用体验。6. 我实际踩过的坑从“等待授权”到“endpoint 报错”6.1 登录卡在“等待授权”的排查链路先说最让人崩溃的场景跑codex login输出了授权链接浏览器里也点过授权了但终端一直停在那句等待授权的提示上死也不往下走。我当时照着“常见问题”里的建议把 Codex 卸载重装了一遍没用。后来逐步排查才定位到系统时间。那台工作机 CMOS 电池老化系统时间慢了几分钟而 OAuth 授权流程对时间偏差极其敏感回调时要用本地时间比对令牌签发时间偏差一多就校验失败。解决办法很简单同步一下时间sudo timedatectl set-ntp true顺便说一下排查顺序以后遇到这种情况不要先重装按这个链路走确认终端里有没有打印出完整的授权链接以及设备码。在另一台机器上手动打开链接看页面是否正常弹出授权界面。检查系统时间date偏差超过一分钟就同步。检查~/.codex目录能否正常写入。看~/.codex/log/下的日志文件错误信息通常比终端提示具体得多。Codex 日志是排查问题的富矿很多终端没有展示的底层错误比如证书问题、超时问题、JSON 解析问题都会记录在里面。我后来的习惯是一遇到诡异现象先tail -n 50 ~/.codex/log/*.log比网上反复搜索靠谱得多。6.2 迁移后提示未登录的根因迁移完auth.json后在新机器上跑 codex结果提示未登录这也是我真实碰到过的。当时拷文件时用的是scp传完之后也没仔细看属主结果auth.json的属主还是旧机器上的 uid 对应的数字我旧机器上 uid 是 501新机器上当前用户是 1000虽然内容没问题但系统判定当前用户不能读那个文件。用ls -la ~/.codex/一看就明白了属主显示的是数字而不是用户名。解决办法就是前面提到的sudo chown -R $(whoami):$(whoami) ~/.codex还有一种情况是你之前设过CODEX_HOME或者OPENAI_BASE_URL环境变量导致 Codex 没去读默认路径。处理方式也很简单检查一下 shell 环境里有没有多余的相关变量用env | grep -i codex或env | grep -i openai看看。6.3 codex exec 拉模型元数据超时还有一种很隐蔽的坑我在迁移后第一次跑真实任务时碰到codex exec进去了但长时间没有反应既不输出内容也不报错。看日志发现它在尝试拉取模型元数据列表而这个请求一直超时。这种问题一般不在 Codex 本身而在网络出口。Codex 启动时会向服务端拉取可用的模型列表和相关参数如果这个请求被卡住后面所有对话都没法开始。有些自定义的模型服务商接口响应比较慢也会造成类似现象。我的处理方式是分两步先curl -I一下 base_url 对应的地址确认网络链路和服务端响应速度然后给 Codex 的请求路径加一个更合理的 endpoint或者直接在config.toml里把model_providers的地址指向更为稳定的接口地址。6.4 一个小习惯换机器后先跑最小验证任务最后分享一个让我后面省了很多事的习惯。不管是在新机器上完成安装、登录、迁移还是修改完config.toml切换模型我都会先跑一个最小的非交互验证确保整条链路是通的再开始干正活。codex exec 只回复OK两个字如果连这个都返回异常那说明环境还有问题趁早排查。如果返回了正常内容基本上安装、认证、模型链路都 OK后面就放心用了。别看这个动作简单它能帮你把“环境问题”和“任务问题”快速隔离开来不用等到真正写代码的时候才发现工具不可用然后一脸懵地开始翻日志。从我个人的使用体验来说Codex 在 Linux 工作机上最别扭的阶段就是前 30 分钟装环境、过登录、搬配置每一步都藏着小坑。但只要把~/.codex/底下的家底摸清了把环境变量和目录权限理顺了后面用起来就真的是一路顺畅。尤其是迁移这事理解了它其实只是“证书文件 两个配置文件 环境变量”的组合之后换机器再也不是什么大工程也就十分钟的事。