企业官网建设流程全解析

最近把开发环境从老 Mac 整体搬迁到 Linux 工作机，折腾到半夜的一项就是 OpenAI Codex CLI。Codex 是跑在终端里的编程智能体，能在你的项目上下文里直接改代码、执行命令、读日志，登录之后整个工作流非常顺手。但它安装、登录、迁移这三步里，Linux 上的坑比预想多不少，尤其是登录凭证的迁移、模型服务商的切换、还有那些报错信息背后的真实原因。这篇就是一份从零到能用的记录，给同样准备在 Linux 工作机上铺开 Codex 的人做参考。

1. 为什么偏偏要在 Linux 工作机上折腾 Codex

1.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 环境细节

除了 Node，Codex 运行还需要系统能正常发起 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_code=XXXX-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_KEY="sk-你的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/目录下，主要有这么几类：

所以，最小迁移清单其实就是两个文件：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.toml

auth.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_KEY：API 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_KEY="sk-你的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

顺便说一下排查顺序，以后遇到这种情况不要先重装，按这个链路走：

1. 确认终端里有没有打印出完整的授权链接，以及设备码。
2. 在另一台机器上手动打开链接，看页面是否正常弹出授权界面。
3. 检查系统时间date，偏差超过一分钟就同步。
4. 检查~/.codex目录能否正常写入。
5. 看~/.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/底下的家底摸清了，把环境变量和目录权限理顺了，后面用起来就真的是一路顺畅。尤其是迁移这事，理解了它其实只是“证书文件 + 两个配置文件 + 环境变量”的组合之后，换机器再也不是什么大工程，也就十分钟的事。