跳到主要内容

Codex Linux 使用指南

推荐

建议使用 CC-Switch 可视化管理工具进行配置，无需手动编辑配置文件，一键完成 ByteCatCode 接入。

前置准备

请先完成 Node.js 环境安装，再继续以下步骤。

一、安装 Codex​

打开终端，运行以下命令：

npm i -g @openai/codex@latest

如果遇到权限问题，可以使用 sudo：

sudo npm i -g @openai/codex@latest

验证 Codex 安装​

安装完成后，输入以下命令检查是否安装成功：

codex --version

如果显示版本号，恭喜你！Codex 已经成功安装了。

二、配置 Codex​

方法一（推荐）：通过配置文件设置​

在 ~/.codex 目录下创建配置文件（如果目录不存在则创建）。

创建 config.toml 文件，添加以下内容：

disable_response_storage = true
model = "gpt-5.2"
model_reasoning_effort = "high"
model_provider = "bytecatcode"

[model_providers.bytecatcode]
base_url = "https://bytecat.lamclod.cn/v1"
name = "bytecatcode"
requires_openai_auth = true
wire_api = "responses"
备选地址

如首选地址不可用，可替换 base_url 为以下备选地址：

  • https://codecdn.bytecatcode.org/v1（国内可直连）
  • https://www.bytecatcode.org/v1（优选CF，可直连，也可挂代理）
  • https://code.bytecatcode.org/v1（需挂代理访问）

创建 auth.json 文件，添加以下内容：

{
  "OPENAI_API_KEY": "你的API密钥"
}

方法二：通过环境变量设置​

临时设置（当前会话）

export OPENAI_BASE_URL="https://bytecat.lamclod.cn/v1"
export OPENAI_API_KEY="你的API密钥"

永久设置

对于 bash（默认）：

echo 'export OPENAI_BASE_URL="https://bytecat.lamclod.cn/v1"' >> ~/.bashrc
echo 'export OPENAI_API_KEY="你的API密钥"' >> ~/.bashrc
source ~/.bashrc

对于 zsh：

echo 'export OPENAI_BASE_URL="https://bytecat.lamclod.cn/v1"' >> ~/.zshrc
echo 'export OPENAI_API_KEY="你的API密钥"' >> ~/.zshrc
source ~/.zshrc

验证环境变量​

echo $OPENAI_BASE_URL
echo $OPENAI_API_KEY

三、开始使用 Codex​

启动 Codex​

配置完成后，在终端中输入以下命令启动 Codex：

codex

首次启动时，Codex 会进行初始化配置。

基本使用​

  • 交互模式：直接输入 codex 进入交互式对话
  • 指定项目：在项目目录下运行 codex，Codex 会自动识别项目上下文
  • 退出程序：输入 exit 或按 Ctrl+C 退出

(四) 常见问题解决​

1. 命令未找到错误​

问题：运行 codex 时提示 "command not found"

解决方法：

npm config get prefix

echo $PATH

echo 'export PATH="/usr/local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

echo 'export PATH="/usr/local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

2. 权限问题​

问题：安装时提示权限不足

解决方法：

sudo npm install -g @openai/codex

mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

npm install -g @openai/codex

3. API 连接失败​

问题：Codex 无法连接到 API 服务

解决方法：

echo $OPENAI_BASE_URL
echo $OPENAI_API_KEY

curl -I https://www.bytecatcode.org

export OPENAI_BASE_URL="https://bytecat.lamclod.cn/v1"
export OPENAI_API_KEY="你的API密钥"

4. 更新 Codex​

问题：如何更新到最新版本

解决方法：

npm i -g @openai/codex@latest

5. Node.js 版本过低​

问题：提示 Node.js 版本不兼容

解决方法：

curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash -
sudo apt-get install -y nodejs

sudo dnf module install nodejs:lts

node --version

6. 依赖缺失问题​

问题：运行时提示缺少依赖

解决方法：

sudo apt-get install build-essential

sudo dnf groupinstall "Development Tools"

npm install -g @openai/codex