Skip to main content
Codex 可以直接运行在 Linux 服务器或本地 Linux 环境中。你可以安装 Codex CLI，配置 AIOAGI API Key 和 OpenAI 兼容端点，再通过终端或 VS Code Remote SSH 使用 Codex 辅助开发。
Codex 版本、VS Code 扩展界面、模型名、端点和支持策略可能变化。请以控制台、开发者指南和 OpenAI Codex 官方文档的最新说明为准。

​
准备条件

  • Linux 服务器、本地 Linux 或 WSL 环境
  • 一个普通 Linux 用户账号，不建议使用 root 用户安装和运行 Codex
  • Node.js LTS 版本
  • Git
  • 可用的 AIOAGI API Key
  • 一个本地或服务器端代码项目，用于验证 Codex 是否可正常读取仓库

OpenAI Codex 配置文档

查看 config.toml、模型和 Provider 配置方式。

OpenAI Codex IDE 扩展

查看 Codex 与编辑器集成的官方说明。

AIOAGI API Key 指南

如果你还没有创建 API Key，可以先完成控制台配置。

开发者指南

核对当前端点、模型和 OpenAI 兼容接口说明。

​
安装步骤

1

准备 Linux 用户环境

使用普通用户登录系统。后续命令默认在该用户的 shell 中执行。
2

安装 Node.js 和 Git

Ubuntu 或 Debian 可以使用：
RHEL、CentOS、Rocky Linux 或 AlmaLinux 可以使用：
如果系统包里的 Node.js 版本过旧，建议改用 Node.js 官网二进制包或 nvm 安装 LTS 版本。
3

验证基础命令

确认 Node.js、npm 和 Git 已可用：
4

安装 Codex CLI

使用 npm 安装 Codex CLI：
安装后验证：
5

创建 AIOAGI API Key

登录 AIOAGI 控制台，在 令牌管理 中创建 API Key。建议为 Codex 单独创建一个 Token 组，便于统计用量和控制额度。
6

配置 Codex

在当前 Linux 用户目录下创建或更新 ~/.codex/config.toml，把 Codex 指向 AIOAGI 的 OpenAI 兼容接口。

​
AIOAGI 接入配置

​
推荐方式：使用用户环境变量

如果你使用 bash，把 API Key 写入 ~/.bashrc：
如果你使用 zsh，把上面的 ~/.bashrc 改成 ~/.zshrc。 然后创建 Codex 配置目录和配置文件：
在 config.toml 中写入下面的内容：
如果你的网络更适合 CDN 加速线路，也可以把 base_url 改成：
gpt-5.1-codex 仅作为配置示例。模型 ID、可用模型和调用策略可能变化，请先在控制台或开发者指南中确认后再配置。

​
是否需要 OPENAI_BASE_URL

如果你按上面的 config.toml 配置了 [model_providers.aioagi].base_url，不需要再设置 OPENAI_BASE_URL。Codex 会从 config.toml 读取 AIOAGI 的 base URL，OPENAI_API_KEY 只负责提供密钥。 如果你不定义 AIOAGI Provider，而是改用 Codex 内置 openai Provider 的代理方式，请在用户级 config.toml 中配置 openai_base_url：
这种方式仍需要保留 OPENAI_API_KEY。不要把 OPENAI_BASE_URL 和 [model_providers.aioagi].base_url 当作两项必填配置同时维护。

​
兼容方式：使用 auth.json

如果你不想把 API Key 写入 shell 配置，也可以在 ~/.codex 下创建 auth.json：
写入：
此时 config.toml 仍保留 AIOAGI Provider 配置：
不要把包含真实 API Key 的 ~/.bashrc、auth.json、config.toml 截图或终端输出提交到公开仓库。

​
启动和验证

进入你的代码项目目录后，执行：
你可以先用下面这类提示词验证接入是否成功：
如果 Codex 能正常读取仓库并返回结果，说明 CLI 安装、配置文件和 API Key 已基本可用。

​
VS Code Remote SSH 使用

如果 Codex 安装在远程 Linux 服务器上，可以通过 VS Code Remote SSH 使用。
1

安装 Remote SSH

在本地 VS Code 中点击 Extensions，搜索并安装 Remote - SSH。
2

连接服务器

使用 Remote-SSH: Connect to Host 连接目标 Linux 主机，并打开服务器上的项目目录。
3

安装 Codex 扩展

连接到远程服务器后，在远程扩展环境中搜索 Codex，安装 OpenAI 官方 Codex 扩展。
4

验证远程终端

打开 VS Code 远程终端，执行 node --version、npm --version、git --version 和 codex --version，确认命令读取的是服务器端环境。

​
常见问题

先执行 npm prefix -g，确认全局安装路径是否加入 PATH。如果你使用 nvm，请确认当前终端已经加载 nvm 配置。
不建议直接切换到 root 运行 Codex。优先使用 nvm 安装 Node.js，或配置用户级 npm 全局目录后再重新安装 @openai/codex。
远程 VS Code 终端可能没有加载完整 shell 配置。检查 PATH、~/.bashrc、~/.profile 或 ~/.zshrc，并重新加载远程窗口。
检查 OPENAI_API_KEY 是否完整复制。再确认 Token 组额度、模型权限、base_url 和网络代理设置。你也可以参考 常见问题 中的 Codex 排障条目。
如果配置后仍未生效，或仍返回 OpenAI 官方接口的认证、验证错误，请先重新打开本地终端、远程 shell 和 VS Code Remote SSH 窗口。再执行 codex 重新测试。如果仍不生效，请重启对应服务器或主机后再测试。问题仍存在时，可以通过微信或 QQ 联系平台管理员协助排查。
到控制台确认当前 API Key 可访问的模型列表，并核对 model 是否与模型 ID 完全一致。如果平台近期调整了模型别名或支持策略，请以控制台和开发者指南最新信息为准。

​
使用建议

  • 为 Codex 单独创建 API Key，便于统计开发工具用量
  • 先用小额度 Token 组完成连通性测试，再切换到正式额度
  • 多人共用服务器时，建议按 Linux 用户隔离 API Key 和 ~/.codex 配置
  • 使用 VS Code Remote SSH 时，确认扩展安装在远程服务器环境，而不是只安装在本地
  • 模型名、价格和支持策略可能变化，请以控制台和开发者指南为准

​
相关文档