Linux服务器使用Codex CLI:安装、认证与自动化
Codex CLI 在终端中读取项目、修改代码并调用本机工具。通过 SSH 登录 Linux 服务器后运行 Codex,文件操作和命令执行发生在服务器,模型请求也由服务器发出。
本文使用普通 Linux 账户和 Bash,示例项目位于 ~/projects/demo。远程连接与整体工作流见 AI Coding指南;Claude Code 与 cc-switch 的配置见 Linux服务器安装Claude Code教程。
1 运行前需要准备什么
服务器需要能够访问安装文件、认证服务与模型接口。PC 浏览器能够联网,并不代表服务器上的命令行工具已经具备相同的访问条件。
使用官方模型服务时,不需要在服务器上下载模型权重,也不要求本机 GPU 用于模型推理。项目中的测试、数据处理和训练仍会占用服务器资源。
在服务器终端检查基础工具:
1 | hostname |
如果依赖代理,应先准备服务器可达的网络出口,再启动 Codex。代理原理与配置见 Linux服务器代理联网配置。安装报错中的架构、系统库和网络问题需要分别处理。
2 无 sudo 安装 Codex CLI
官方提供 macOS/Linux 独立安装脚本,无需先安装 Node.js。下面将脚本下载到个人缓存目录,再查看内容:
1 | mkdir -p "$HOME/.cache/codex-install" |
确认下载成功后,less 中按 q 返回终端,执行安装:
1 | sh "$HOME/.cache/codex-install/install.sh" |
默认的命令目录是 ~/.local/bin,独立程序缓存位于 ~/.codex/packages/standalone。这些路径属于当前用户,不需要向系统目录写入。安装方式和目录定义见 Codex CLI 官方说明与 Codex 环境变量说明。
为当前 Shell 添加命令搜索路径:
1 | export PATH="$HOME/.local/bin:$PATH" |
若需要在后续 Bash 终端中使用,在 ~/.bashrc 中添加一次以下内容:
1 | export PATH="$HOME/.local/bin:$PATH" |
保存后执行 source ~/.bashrc。文件中已经包含同样设置时,无需重复添加。更新时可重新下载安装脚本并执行,再用 codex --version 检查结果。
若出现 codex: command not found,先确认安装是否成功,以及 ~/.local/bin 是否在 PATH 中;若出现架构或动态库错误,则需要检查服务器兼容性,修改 PATH 无法解决这类问题。
3 在无图形界面的服务器上认证
3.1 使用 ChatGPT 账户
账户具有相应 Codex 使用权限时,可使用设备码认证:
1 | codex login --device-auth |
在 PC 浏览器打开终端给出的地址,输入一次性验证码并完成登录。此流程不要求服务器运行浏览器,但服务器仍需访问认证服务。
设备码登录需要在个人账户安全设置或工作区权限中启用。若当前账户不支持该方式,可按 官方认证文档使用 SSH 转发登录回调等替代方法。
3.2 使用 OpenAI API Key
在服务器 Bash 中隐藏输入密钥,再通过标准输入交给 Codex:
1 | read -rsp 'OpenAI API Key: ' codex_api_key |
这里使用临时 Shell 变量,避免把 Key 字面值写进命令历史;unset 清除该变量,但不会撤销已保存的登录信息。
ChatGPT 登录使用账户对应的 Codex 权益;API Key 登录通过 OpenAI API 账户按相应规则计费。两者的额度与账单不同。第三方服务的 Key 还涉及服务地址、协议与模型兼容性,不能直接视作官方 Key。
3.3 检查登录与凭据位置
1 | codex login status |
退出已保存的登录使用 codex logout。凭据可能保存在 ~/.codex/auth.json,也可能交给操作系统凭据存储,具体取决于配置。该认证文件不属于项目源代码,不应进入 Git 仓库。存储方式见 认证与凭据说明。
4 从明确的项目目录启动
以下假设项目已经存在且使用 Git 管理:
1 | cd ~/projects/demo |
如果目录没有使用 Git,应先按项目要求建立版本管理;不要为了跳过检查,在主目录或数据根目录随意初始化仓库。开始任务前记录现有修改,可以避免把原本存在的差异误认为 AI 本轮修改。
先以只读模式了解项目:
1 | codex --sandbox read-only --ask-for-approval on-request |
任务可以描述为:
1 | 阅读当前仓库的 README、训练入口和配置文件,说明运行流程与已有测试。 |
需要实际修改代码时,启动允许工作区写入的会话:
1 | codex --sandbox workspace-write --ask-for-approval on-request |
每轮修改后,用 git status --short 检查新增文件,再用 git diff --stat 和 git diff 查看已跟踪文件的差异。仅看 git diff 会漏掉尚未跟踪的新文件。
5 沙箱与审批各自控制什么
沙箱控制命令能够访问和修改的范围,审批策略控制何时需要进一步授权。 二者不是同一个开关。
read-only用于读取和分析;需要写文件、缓存或构建产物的命令可能被阻止。workspace-write允许在工作区内写入,适合修改代码并运行必要检查。on-request表示由 Agent 在需要时请求审批,并不意味着每条命令都要确认。
工作区沙箱默认限制命令联网。这里说的是 Codex 调用的命令及其子进程,Codex 自身与模型服务的通信仍需要网络。下载依赖、访问外部服务等操作可能触发额外审批。
在交互界面中可用 /permissions 查看或调整权限。具体模式见 Codex 沙箱与审批说明。
权限范围也不等于资源预算。允许执行 Python,并不表示一次完整训练在时间、显存或数据访问方面都适合运行。任务中应明确样本范围、允许执行的检查和需要保留的输出。
6 配置文件与项目指令
6.1 配置作用域
个人配置位于 ~/.codex/config.toml,项目配置可以放在仓库内的 .codex/config.toml。项目配置只有在相应项目受信任时才会加载。
例如,在个人配置文件中合并以下字段,可设置日常交互默认值:
1 | sandbox_mode = "workspace-write" |
已有文件应保留其他配置,避免重复定义同一个键。命令行参数通常覆盖配置文件,受信任项目的配置又可覆盖个人默认值;组织强制策略仍可能限制可选值。完整优先级见 Codex 配置说明。
模型可在交互会话中通过 /model 选择账户当前可用的选项。使用特定模型前,应确认它对当前认证方式可用。
6.2 用 AGENTS.md 保存项目约定
反复使用的项目说明可以放在仓库根目录的 AGENTS.md。以下示例假设仓库确实包含 src/、configs/、tests/,且已有可运行的 pytest 测试:
1 | # 项目约定 |
这是一份供 Agent 读取的说明,不是操作系统强制执行的权限规则,也不会自动创建测试或配置环境。
Codex 启动时会读取用户级与项目中的相关指令;从项目根目录到当前目录,更近的指令可以补充或覆盖较上层约定。修改后重新启动会话,可重新加载指令。查找规则见 AGENTS.md 官方说明。
7 使用 codex exec 整理实验记录
codex exec 用于非交互执行,适合重复的代码检查、日志归纳和文档整理。默认要求工作目录位于 Git 仓库内。
下面假设仓库根目录已有 logs/,其中保存真实实验日志。没有这些文件时,应先替换输入路径;示例不启动训练,也不生成虚构指标。
1 | cd ~/projects/demo |
--output-last-message 由 CLI 将最终回答保存到指定文件,区别于让 Agent 在沙箱中编辑项目。上例中的 mkdir 也由当前 Shell 提前执行。重复使用同一个输出路径会覆盖上次报告,需要保留历史时可更换文件名。
默认情况下,过程信息输出到标准错误,最终回答输出到标准输出。需要机器处理完整事件流时,可使用 --json;仅保存结论时,--output-last-message 更直接。
执行失败、输入日志不完整或指标定义不一致时,报告不应当作有效实验结论。流程中涉及数值汇总的部分,可由已经验证的脚本完成,再让 Codex 解释脚本输出。
非交互执行复用已有认证。定时任务或 CI 中的密钥应来自受控凭据存储,避免写入仓库脚本;权限应在调用时明确设置。参数及自动化认证说明见 Codex 非交互模式。
8 断线与常见问题
需要保持终端会话时,可先在服务器创建 tmux 会话,再进入项目启动 Codex:
1 | tmux new -s coding |
tmux 需要事先安装。按 Ctrl+B,松开后按 d,可离开会话;重新 SSH 登录后用 tmux attach -t coding 接回。完整操作见 Linux服务器使用tmux管理长任务。
tmux 保留远端进程,但不能保证模型接口一直可用,也不会替代待处理的审批。若代理出口来自 PC 的 SSH 转发,PC 断线后代理也会失效;长时间调用 API 需要稳定的服务器网络出口。
常见问题可按发生阶段定位:
- 安装或更新失败:检查下载地址连通性、磁盘空间和 CPU 架构,保留完整报错。
- 认证失败:检查当前认证方式、账户权限和认证服务网络;程序已安装不代表已经登录。
- 能聊天但无法运行命令:查看沙箱拒绝原因,区分目录权限、网络权限和项目依赖缺失。
- 找不到 Python 或导入失败:在启动 Codex 的终端检查解释器与项目环境,见 Linux服务器Python环境管理。
- 工作目录不对:退出并切换到目标仓库重新启动,避免把个人主目录当成整个项目工作区。





