> ## Documentation Index
> Fetch the complete documentation index at: https://docs.aioagi.tech/llms.txt
> Use this file to discover all available pages before exploring further.

# Linux

> 在 Linux 上安装 Codex CLI，并通过 AIOAGI 的 OpenAI 兼容接口接入 Codex。

Codex 可以直接运行在 Linux 服务器或本地 Linux 环境中。你可以安装 Codex CLI，配置 AIOAGI API Key 和 OpenAI 兼容端点，再通过终端或 VS Code Remote SSH 使用 Codex 辅助开发。

<Info>
  Codex 版本、VS Code 扩展界面、模型名、端点和支持策略可能变化。请以控制台、开发者指南和 OpenAI Codex 官方文档的最新说明为准。
</Info>

## 准备条件

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

<CardGroup cols={2}>
  <Card title="OpenAI Codex 配置文档" href="https://developers.openai.com/codex/config-basic">
    查看 `config.toml`、模型和 Provider 配置方式。
  </Card>

  <Card title="OpenAI Codex IDE 扩展" href="https://developers.openai.com/codex/ide">
    查看 Codex 与编辑器集成的官方说明。
  </Card>

  <Card title="AIOAGI API Key 指南" href="/api-key-guide">
    如果你还没有创建 API Key，可以先完成控制台配置。
  </Card>

  <Card title="开发者指南" href="https://aiearthdev.apifox.cn/">
    核对当前端点、模型和 OpenAI 兼容接口说明。
  </Card>
</CardGroup>

## 安装步骤

<Steps>
  <Step title="准备 Linux 用户环境">
    使用普通用户登录系统。后续命令默认在该用户的 shell 中执行。

    ```bash theme={null}
    whoami
    pwd
    ```
  </Step>

  <Step title="安装 Node.js 和 Git">
    Ubuntu 或 Debian 可以使用：

    ```bash theme={null}
    sudo apt update
    sudo apt install -y nodejs npm git
    ```

    RHEL、CentOS、Rocky Linux 或 AlmaLinux 可以使用：

    ```bash theme={null}
    sudo dnf install -y nodejs npm git
    ```

    如果系统包里的 Node.js 版本过旧，建议改用 Node.js 官网二进制包或 `nvm` 安装 LTS 版本。
  </Step>

  <Step title="验证基础命令">
    确认 Node.js、npm 和 Git 已可用：

    ```bash theme={null}
    node --version
    npm --version
    git --version
    ```
  </Step>

  <Step title="安装 Codex CLI">
    使用 `npm` 安装 Codex CLI：

    ```bash theme={null}
    npm install -g @openai/codex
    ```

    安装后验证：

    ```bash theme={null}
    codex --version
    ```
  </Step>

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

  <Step title="配置 Codex">
    在当前 Linux 用户目录下创建或更新 `~/.codex/config.toml`，把 Codex 指向 AIOAGI 的 OpenAI 兼容接口。
  </Step>
</Steps>

## AIOAGI 接入配置

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

如果你使用 `bash`，把 API Key 写入 `~/.bashrc`：

```bash theme={null}
echo 'export OPENAI_API_KEY="sk-your-aioagi-api-key"' >> ~/.bashrc
source ~/.bashrc
```

如果你使用 `zsh`，把上面的 `~/.bashrc` 改成 `~/.zshrc`。

然后创建 Codex 配置目录和配置文件：

```bash theme={null}
mkdir -p ~/.codex
nano ~/.codex/config.toml
```

在 `config.toml` 中写入下面的内容：

```toml theme={null}
model_provider = "aioagi"
model = "gpt-5.1-codex"
model_reasoning_effort = "high"

[model_providers.aioagi]
name = "AIOAGI"
base_url = "https://api.aiearth.dev/v1"
env_key = "OPENAI_API_KEY"
wire_api = "responses"
```

如果你的网络更适合 CDN 加速线路，也可以把 `base_url` 改成：

```toml theme={null}
base_url = "https://api.aiearth.vip/v1"
```

<Warning>
  `gpt-5.1-codex` 仅作为配置示例。模型 ID、可用模型和调用策略可能变化，请先在控制台或开发者指南中确认后再配置。
</Warning>

### 是否需要 `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`：

```toml theme={null}
model_provider = "openai"
model = "gpt-5.1-codex"
openai_base_url = "https://api.aiearth.dev/v1"
```

这种方式仍需要保留 `OPENAI_API_KEY`。不要把 `OPENAI_BASE_URL` 和 `[model_providers.aioagi].base_url` 当作两项必填配置同时维护。

### 兼容方式：使用 auth.json

如果你不想把 API Key 写入 shell 配置，也可以在 `~/.codex` 下创建 `auth.json`：

```bash theme={null}
mkdir -p ~/.codex
nano ~/.codex/auth.json
```

写入：

```json theme={null}
{
  "OPENAI_API_KEY": "sk-your-aioagi-api-key"
}
```

此时 `config.toml` 仍保留 AIOAGI Provider 配置：

```toml theme={null}
model_provider = "aioagi"
model = "gpt-5.1-codex"
model_reasoning_effort = "high"

[model_providers.aioagi]
name = "AIOAGI"
base_url = "https://api.aiearth.dev/v1"
env_key = "OPENAI_API_KEY"
wire_api = "responses"
```

不要把包含真实 API Key 的 `~/.bashrc`、`auth.json`、`config.toml` 截图或终端输出提交到公开仓库。

## 启动和验证

进入你的代码项目目录后，执行：

```bash theme={null}
codex
```

你可以先用下面这类提示词验证接入是否成功：

```text theme={null}
请先阅读当前仓库结构，再总结主要目录和入口文件。
```

如果 Codex 能正常读取仓库并返回结果，说明 CLI 安装、配置文件和 API Key 已基本可用。

## VS Code Remote SSH 使用

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

<Steps>
  <Step title="安装 Remote SSH">
    在本地 VS Code 中点击 **Extensions**，搜索并安装 `Remote - SSH`。
  </Step>

  <Step title="连接服务器">
    使用 **Remote-SSH: Connect to Host** 连接目标 Linux 主机，并打开服务器上的项目目录。
  </Step>

  <Step title="安装 Codex 扩展">
    连接到远程服务器后，在远程扩展环境中搜索 `Codex`，安装 OpenAI 官方 Codex 扩展。
  </Step>

  <Step title="验证远程终端">
    打开 VS Code 远程终端，执行 `node --version`、`npm --version`、`git --version` 和 `codex --version`，确认命令读取的是服务器端环境。
  </Step>
</Steps>

## 常见问题

<AccordionGroup>
  <Accordion title="执行 `codex` 提示命令不存在" icon="terminal">
    先执行 `npm prefix -g`，确认全局安装路径是否加入 `PATH`。如果你使用 `nvm`，请确认当前终端已经加载 `nvm` 配置。
  </Accordion>

  <Accordion title="`npm install -g` 权限不足" icon="lock">
    不建议直接切换到 `root` 运行 Codex。优先使用 `nvm` 安装 Node.js，或配置用户级 npm 全局目录后再重新安装 `@openai/codex`。
  </Accordion>

  <Accordion title="VS Code Remote SSH 里找不到 `codex`" icon="plug">
    远程 VS Code 终端可能没有加载完整 shell 配置。检查 `PATH`、`~/.bashrc`、`~/.profile` 或 `~/.zshrc`，并重新加载远程窗口。
  </Accordion>

  <Accordion title="认证失败或返回 401 / 403" icon="key">
    检查 `OPENAI_API_KEY` 是否完整复制。再确认 Token 组额度、模型权限、`base_url` 和网络代理设置。你也可以参考 [常见问题](/faq) 中的 Codex 排障条目。
  </Accordion>

  <Accordion title="配置后仍未生效" icon="gear">
    如果配置后仍未生效，或仍返回 OpenAI 官方接口的认证、验证错误，请先重新打开本地终端、远程 shell 和 VS Code Remote SSH 窗口。再执行 `codex` 重新测试。如果仍不生效，请重启对应服务器或主机后再测试。问题仍存在时，可以通过微信或 QQ 联系平台管理员协助排查。
  </Accordion>

  <Accordion title="模型不存在或不可用" icon="sparkles">
    到控制台确认当前 API Key 可访问的模型列表，并核对 `model` 是否与模型 ID 完全一致。如果平台近期调整了模型别名或支持策略，请以控制台和开发者指南最新信息为准。
  </Accordion>
</AccordionGroup>

## 使用建议

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

## 相关文档

* [OpenAI Codex configuration](https://developers.openai.com/codex/config-basic)
* [OpenAI Codex IDE extension](https://developers.openai.com/codex/ide)
* [VS Code: Remote SSH](https://code.visualstudio.com/docs/remote/ssh)
* [AIOAGI 开发者指南](https://aiearthdev.apifox.cn/)