Codex CLI 在终端中读取项目、修改代码并调用本机工具。通过 SSH 登录 Linux 服务器后运行 Codex,文件操作和命令执行发生在服务器,模型请求也由服务器发出。

本文使用普通 Linux 账户和 Bash,示例项目位于 ~/projects/demo。远程连接与整体工作流见 AI Coding指南;Claude Code 与 cc-switch 的配置见 Linux服务器安装Claude Code教程。

1 运行前需要准备什么

服务器需要能够访问安装文件、认证服务与模型接口。PC 浏览器能够联网,并不代表服务器上的命令行工具已经具备相同的访问条件。

使用官方模型服务时,不需要在服务器上下载模型权重,也不要求本机 GPU 用于模型推理。项目中的测试、数据处理和训练仍会占用服务器资源。

在服务器终端检查基础工具:

1
2
3
4
5
hostname
command -v curl
command -v sh
git --version
uname -m

如果依赖代理,应先准备服务器可达的网络出口,再启动 Codex。代理原理与配置见 Linux服务器代理联网配置。安装报错中的架构、系统库和网络问题需要分别处理。

2 无 sudo 安装 Codex CLI

官方提供 macOS/Linux 独立安装脚本,无需先安装 Node.js。下面将脚本下载到个人缓存目录,再查看内容:

1
2
3
4
mkdir -p "$HOME/.cache/codex-install"
curl -fsSL https://chatgpt.com/codex/install.sh \
-o "$HOME/.cache/codex-install/install.sh"
less "$HOME/.cache/codex-install/install.sh"

确认下载成功后,less 中按 q 返回终端,执行安装:

1
sh "$HOME/.cache/codex-install/install.sh"

默认的命令目录是 ~/.local/bin,独立程序缓存位于 ~/.codex/packages/standalone。这些路径属于当前用户,不需要向系统目录写入。安装方式和目录定义见 Codex CLI 官方说明与 Codex 环境变量说明。

为当前 Shell 添加命令搜索路径:

1
2
3
export PATH="$HOME/.local/bin:$PATH"
command -v codex
codex --version

若需要在后续 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
2
3
4
read -rsp 'OpenAI API Key: ' codex_api_key
printf '\n'
printf '%s\n' "$codex_api_key" | codex login --with-api-key
unset 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
2
3
4
cd ~/projects/demo
pwd
git rev-parse --show-toplevel
git status --short

如果目录没有使用 Git,应先按项目要求建立版本管理;不要为了跳过检查,在主目录或数据根目录随意初始化仓库。开始任务前记录现有修改,可以避免把原本存在的差异误认为 AI 本轮修改。

先以只读模式了解项目:

1
codex --sandbox read-only --ask-for-approval on-request

任务可以描述为:

1
2
阅读当前仓库的 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
2
sandbox_mode = "workspace-write"
approval_policy = "on-request"

已有文件应保留其他配置,避免重复定义同一个键。命令行参数通常覆盖配置文件,受信任项目的配置又可覆盖个人默认值;组织强制策略仍可能限制可选值。完整优先级见 Codex 配置说明。

模型可在交互会话中通过 /model 选择账户当前可用的选项。使用特定模型前,应确认它对当前认证方式可用。

6.2 用 AGENTS.md 保存项目约定

反复使用的项目说明可以放在仓库根目录的 AGENTS.md。以下示例假设仓库确实包含 src/、configs/、tests/,且已有可运行的 pytest 测试:

1
2
3
4
5
6
7
8
# 项目约定

- 核心实现位于 src/,实验配置位于 configs/。
- 使用项目已有的 Python 环境,不修改系统环境。
- 修改后运行相关的 python -m pytest tests/ 测试。
- 测试缺失或无法执行时,说明具体原因,不声称已经通过。
- 不自动启动完整训练,不改写原始数据或已有实验输出。
- 实验结论必须给出日志或结果文件依据,缺失指标明确标为缺失。

这是一份供 Agent 读取的说明,不是操作系统强制执行的权限规则,也不会自动创建测试或配置环境。

Codex 启动时会读取用户级与项目中的相关指令;从项目根目录到当前目录,更近的指令可以补充或覆盖较上层约定。修改后重新启动会话,可重新加载指令。查找规则见 AGENTS.md 官方说明。

7 使用 codex exec 整理实验记录

codex exec 用于非交互执行,适合重复的代码检查、日志归纳和文档整理。默认要求工作目录位于 Git 仓库内。

下面假设仓库根目录已有 logs/,其中保存真实实验日志。没有这些文件时,应先替换输入路径;示例不启动训练,也不生成虚构指标。

1
2
3
4
5
6
7
cd ~/projects/demo
mkdir -p reports
codex exec --sandbox read-only \
--output-last-message reports/experiment-summary.md \
"读取 logs/ 下现有实验日志,按实验名整理日志中实际记录的指标和异常。
每项结论标注源文件;缺失指标写明缺失,不推测数值。
不要修改项目文件,不要启动训练,不要下载数据。"

--output-last-message 由 CLI 将最终回答保存到指定文件,区别于让 Agent 在沙箱中编辑项目。上例中的 mkdir 也由当前 Shell 提前执行。重复使用同一个输出路径会覆盖上次报告,需要保留历史时可更换文件名。

默认情况下,过程信息输出到标准错误,最终回答输出到标准输出。需要机器处理完整事件流时,可使用 --json;仅保存结论时,--output-last-message 更直接。

执行失败、输入日志不完整或指标定义不一致时,报告不应当作有效实验结论。流程中涉及数值汇总的部分,可由已经验证的脚本完成,再让 Codex 解释脚本输出。

非交互执行复用已有认证。定时任务或 CI 中的密钥应来自受控凭据存储,避免写入仓库脚本;权限应在调用时明确设置。参数及自动化认证说明见 Codex 非交互模式。

8 断线与常见问题

需要保持终端会话时,可先在服务器创建 tmux 会话,再进入项目启动 Codex:

1
2
3
tmux new -s coding
cd ~/projects/demo
codex --sandbox workspace-write --ask-for-approval on-request

tmux 需要事先安装。按 Ctrl+B,松开后按 d,可离开会话;重新 SSH 登录后用 tmux attach -t coding 接回。完整操作见 Linux服务器使用tmux管理长任务。

tmux 保留远端进程,但不能保证模型接口一直可用,也不会替代待处理的审批。若代理出口来自 PC 的 SSH 转发,PC 断线后代理也会失效;长时间调用 API 需要稳定的服务器网络出口。

常见问题可按发生阶段定位:

  • 安装或更新失败:检查下载地址连通性、磁盘空间和 CPU 架构,保留完整报错。
  • 认证失败:检查当前认证方式、账户权限和认证服务网络;程序已安装不代表已经登录。
  • 能聊天但无法运行命令:查看沙箱拒绝原因,区分目录权限、网络权限和项目依赖缺失。
  • 找不到 Python 或导入失败:在启动 Codex 的终端检查解释器与项目环境,见 Linux服务器Python环境管理。
  • 工作目录不对:退出并切换到目标仓库重新启动,避免把个人主目录当成整个项目工作区。