一、文档概述

1.1 编写目的

本文档旨在为在国产信创环境下部署 OpenAI Codex CLI 提供完整、可操作的安装与适配指南。文档涵盖环境准备、系统配置、安装方式、依赖处理、配置文件设置、验证测试及常见问题排查等全流程技术细节，适用于党政机关、国有企业、金融机构等关键领域的开发团队及信创适配工程师参考使用。

1.2 适用范围

• 国产操作系统：银河麒麟 V10、统信 UOS、openEuler、Anolis 等
• 国产硬件平台：海光 x86_64、鲲鹏 ARM64、飞腾 ARM64、龙芯 LoongArch 等
• 软件对象：OpenAI Codex CLI（v0.130.0+）

1.3 适配核心准则

信创环境对软件适配有明确的核心要求：所有落地软件必须满足架构兼容、依赖国产化、无国外闭源高危组件、运行稳定安全四大标准。Codex 国产化适配需重点关注以下要点：

• 适配 ARM、LoongArch 等非 x86 架构
• 替换国外闭源依赖库
• 适配国产系统内核规范
• 符合信创安全权限管控策略

1.4 术语说明

术语	说明
Codex CLI	OpenAI 开发的终端 AI 编程智能体，基于 Rust 实现，Apache-2.0 开源协议，可在终端中读取文件、执行命令、自主修改代码库
信创	信息技术应用创新，核心目标是构建自主可控、安全可靠的国产化 IT 生态体系
openai_base_url	Codex CLI 配置文件中的 API 端点地址，用于替换默认的 api.openai.com

二、环境准备

2.1 硬件环境要求

信创环境的 CPU 架构多样，不同架构的适配策略有所差异。需首先确认硬件平台信息：

（1）海光 CPU（x86_64）

海光 CPU 是国内唯一获得 x86 指令集永久授权的国产处理器，具有极强的生态兼容性，是目前信创场景下适配 Codex 最便捷的硬件平台。由于 Codex 官方预编译包直接支持 x86_64 架构，安装过程与标准 Linux 环境基本一致。

（2）鲲鹏 / 飞腾 CPU（ARM64/aarch64）

鲲鹏 920 和飞腾 FT-2000+ 等 ARM64 架构处理器在信创环境中广泛使用。Codex 官方提供 aarch64 预编译包，但部分深度学习依赖库（如 PyTorch）需要使用 ARM64 原生编译版本。

（3）龙芯 CPU（LoongArch64）

龙芯使用完全自主的 LoongArch 指令集。由于 Codex 官方目前不提供 LoongArch 架构的预编译二进制包，不能简单套用 x86_64 或 aarch64 的安装方式。建议采用以下替代方案之一：

• 在同网段部署一台 x86_64/ARM64 开发机作为 Codex 工作机，通过 SSH 使用
• 使用支持对应架构的容器或远程开发环境
• 等待官方提供 LoongArch 架构包后再做原生安装

注意：本文以海光 x86_64 和鲲鹏/飞腾 ARM64 为主要适配对象，LoongArch 架构原生部署不在本文详细讨论范围内。

2.2 操作系统要求

• 银河麒麟 V10（SP1/SP3）
• 统信 UOS Server 20 / 桌面版
• openEuler 22.03 LTS / 24.03 LTS
• Anolis OS 23 / 8.x

说明：上述国产操作系统均基于 Linux 内核深度定制，部分系统调用指令、动态链接库与标准 Linux 存在差异，安装过程中可能需要微调内核兼容参数或替换系统自带的通用动态库。

2.3 基础依赖要求

安装前需确保以下基础软件已正确安装：

依赖项	最低版本	说明
Node.js	v18+	npm 安装方式必需（推荐方式）
npm	v9+	随 Node.js 一起安装
Python	3.9+	部分扩展功能依赖
GCC	9.3+	源码编译场景需要
Git	2.30+	版本控制与仓库克隆
CMake	3.22+	编译依赖库场景需要

2.4 环境验证命令

在开始安装之前，执行以下命令确认当前系统环境信息：

# 查看 CPU 架构
uname -m
# 常见输出：x86_64（海光/兆芯/Intel/AMD）、aarch64（飞腾/鲲鹏）、loongarch64（龙芯新平台）

# 查看操作系统版本
cat /etc/os-release

# 查看 Node.js 版本
node -v

# 查看 npm 版本
npm -v

# 查看 Python 版本
python3 --version

# 查看 Git 版本
git --version

根据 uname -m 输出结果判断架构类型：

• x86_64：海光、兆芯、Intel、AMD 平台
• aarch64：飞腾、鲲鹏、部分 ARM 服务器平台
• loongarch64：龙芯新平台

三、安装方式选择

Codex CLI 支持三种安装方式，在信创环境下可根据网络条件和架构兼容性灵活选择。

3.1 方式一：npm 全局安装（推荐）

适用于 Node.js 18+ 环境且 npm 可正常访问网络（或已配置国内镜像源）的场景。

npm install -g @openai/codex

安装完成后验证：

codex --version
# 预期输出示例：codex 0.131.0

3.2 方式二：GitHub Release 二进制包安装

适用于网络受限、无法访问 npm 仓库，或需要离线部署的场景。从 GitHub Release 下载对应 Linux 架构的预编译二进制包，解压后放置到系统路径即可。

3.2.1 x86_64 架构（海光/兆芯平台）

# 下载 x86_64 musl 静态链接版本（不依赖系统 glibc，推荐）
curl -L https://github.com/openai/codex/releases/download/rust-v0.131.0/codex-x86_64-unknown-linux-musl.tar.gz | tar -xz
sudo mv codex-x86_64-unknown-linux-musl codex
sudo mv codex /usr/local/bin/
chmod +x /usr/local/bin/codex
codex --version

3.2.2 ARM64 架构（鲲鹏/飞腾平台）

# 下载 aarch64 版本
curl -L https://github.com/openai/codex/releases/download/rust-v0.131.0/codex-aarch64-unknown-linux-musl.tar.gz | tar -xz
sudo mv codex-aarch64-unknown-linux-musl codex
sudo mv codex /usr/local/bin/
chmod +x /usr/local/bin/codex
codex --version

说明：musl 静态链接版本不依赖系统 glibc 版本，可最大程度避免因国产系统 glibc 版本较旧导致的兼容性问题，在信创环境下推荐优先使用。

3.2.3 离线场景部署

若目标机器完全无法访问外网，可通过以下步骤离线部署：

1. 在联网机器上下载对应架构的 .tar.gz 包
2. 通过 U 盘或内网文件传输将压缩包拷贝至目标机器
3. 在目标机器上执行解压和安装命令（同上）

3.3 方式三：源码编译安装（高级用户）

当预编译包不可用或需要针对特定架构优化时，可从源码编译 Codex CLI。Codex CLI 使用 Rust 构建。

前提条件：

• 安装 Rust 工具链：curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
• 确保 Rust 工具链支持目标架构

编译步骤：

# 克隆仓库
git clone https://github.com/openai/codex.git
cd codex

# 编译（Rust 项目，使用 Cargo）
cargo build --release

# 安装
sudo cp target/release/codex /usr/local/bin/
codex --version

注意：源码编译对系统依赖（GCC、CMake、OpenSSL 等）要求较高，在信创环境下可能遇到依赖库缺失或版本不兼容问题，建议优先使用预编译二进制包。ARM64 架构下编译需要额外注意交叉编译链的配置。

四、信创环境专项配置

4.1 国产系统软件源配置

4.1.1 麒麟 V10 系统源配置

麒麟 V10 基于 Debian 系包管理（apt），默认软件源可能缺少部分依赖包。配置官方软件源：

# 备份原始源
sudo cp /etc/apt/sources.list /etc/apt/sources.list.bak

# 编辑源配置
sudo vim /etc/apt/sources.list

建议添加麒麟官方源及国内镜像源：

deb http://archive.kylinos.cn/kylin/KYLIN-ALL 10.1 main restricted universe multiverse
deb https://mirrors.aliyun.com/ubuntu/ focal main restricted universe multiverse

4.1.2 统信 UOS 系统源配置

# UOS 通常使用深度定制的源
sudo vim /etc/apt/sources.list

若遇到软件包签名验证失败，需开启开发者模式：

进入“控制中心 → 通用 → 开发者模式 → 在线开启”

4.1.3 openEuler / Anolis 系统源配置

openEuler 和 Anolis 基于 RPM 系（yum/dnf），默认软件源相对完整，但建议配置国内镜像加速：

# openEuler
sudo sed -i 's|repo.openeuler.org|mirrors.aliyun.com/openeuler|g' /etc/yum.repos.d/openEuler.repo

# Anolis
sudo sed -i 's|repo.anolis.org|mirrors.aliyun.com/anolis|g' /etc/yum.repos.d/AnolisOS.repo

4.2 系统依赖库安装

在国产系统上安装 Codex 所需基础依赖：

Debian/Ubuntu 系（麒麟、UOS） ：

sudo apt update
sudo apt install -y curl wget ca-certificates gnupg lsb-release \
    build-essential libssl-dev zlib1g-dev libbz2-dev \
    libreadline-dev libsqlite3-dev libncursesw5-dev \
    xz-utils tk-dev libxml2-dev libxmlsec1-dev libffi-dev liblzma-dev

RPM 系（openEuler、Anolis） ：

sudo dnf update -y
sudo dnf install -y curl wget ca-certificates gnupg2 \
    gcc gcc-c++ make openssl-devel zlib-devel bzip2-devel \
    readline-devel sqlite-devel ncurses-devel \
    xz-devel tk-devel libxml2-devel libxmlsec1-devel libffi-devel xz-devel

4.3 Node.js 在国产系统上的安装

4.3.1 方式一：二进制包安装（推荐，避免编译问题）

# 下载 Node.js 18 LTS 二进制包（根据架构选择）
# x86_64
wget https://npmmirror.com/mirrors/node/v18.20.0/node-v18.20.0-linux-x64.tar.xz
tar -xf node-v18.20.0-linux-x64.tar.xz
sudo mv node-v18.20.0-linux-x64 /usr/local/nodejs
# 配置环境变量
echo 'export PATH=/usr/local/nodejs/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

# aarch64（鲲鹏/飞腾）
wget https://npmmirror.com/mirrors/node/v18.20.0/node-v18.20.0-linux-arm64.tar.xz
tar -xf node-v18.20.0-linux-arm64.tar.xz
sudo mv node-v18.20.0-linux-arm64 /usr/local/nodejs
echo 'export PATH=/usr/local/nodejs/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

4.3.2 方式二：使用包管理器安装

麒麟 V10 / 统信 UOS：

# 添加 NodeSource 仓库
curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
sudo apt install -y nodejs

openEuler / Anolis：

# 使用 dnf 模块安装
sudo dnf module install nodejs:18

4.3.3 安装后验证

node -v    # 预期输出：v18.20.0 或更高
npm -v     # 预期输出：9.x.x 或更高

4.4 npm 镜像源配置

信创环境下，外网 npm 仓库可能不可达或速度极慢，建议配置国内镜像源：

# 设置淘宝镜像
npm config set registry https://registry.npmmirror.com

# 验证配置
npm config get registry

若企业有自建 npm 私有仓库，则配置为企业内部仓库地址：

npm config set registry https://npm.your-company.com/repository/npm-public/

4.5 网络代理与证书配置

4.5.1 代理配置

在需要通过代理服务器访问外网的企业内网环境中，需配置 npm 和终端的代理：

# npm 代理配置
npm config set proxy http://proxy.your-company.com:8080
npm config set https-proxy http://proxy.your-company.com:8080

# 终端环境代理配置（临时）
export HTTP_PROXY=http://proxy.your-company.com:8080
export HTTPS_PROXY=http://proxy.your-company.com:8080

# 永久生效（写入 shell 配置文件）
echo 'export HTTP_PROXY=http://proxy.your-company.com:8080' >> ~/.bashrc
echo 'export HTTPS_PROXY=http://proxy.your-company.com:8080' >> ~/.bashrc
source ~/.bashrc

4.5.2 企业根证书配置

若企业网络存在 SSL/TLS 中间人检测，需将企业根证书导入系统信任链：

# 将企业 CA 证书复制到系统信任目录
sudo cp your-company-ca.crt /usr/local/share/ca-certificates/
sudo update-ca-certificates

# 配置 npm 使用系统证书
npm config set cafile /etc/ssl/certs/ca-certificates.crt

# 配置 Node.js 使用系统证书（设置环境变量）
export NODE_EXTRA_CA_CERTS=/etc/ssl/certs/ca-certificates.crt

五、Codex 配置文件设置

5.1 创建配置目录

mkdir -p ~/.codex

5.2 核心配置文件（config.toml）

Codex CLI 的配置文件位于 ~/.codex/config.toml，是国内信创环境适配的关键配置入口。

在信创环境下，Codex CLI 默认调用 api.openai.com，中国大陆无法直连。解决方案是将 openai_base_url 指向兼容 OpenAI 协议的国内 API 端点。

创建或编辑 ~/.codex/config.toml：

#:schema https://developers.openai.com/codex/config-schema.json

# ① 替换为国内兼容 API 端点（关键配置）
openai_base_url = "https://api.qnaigc.com/v1"

# ② 选择模型（以实际可用的模型名称为准）
model = "deepseek-v4-pro"

# ③ 沙盒模式：workspace-write 允许修改当前项目目录的文件
sandbox_mode = "workspace-write"

# ④ 关闭联网搜索（国内连接 Bing Search API 不稳定）
web_search = "disabled"

# ⑤ 审批策略：非破坏性命令自动执行，不确定时暂停确认
approval_policy = "on-request"

配置项说明：

配置项	说明
openai_base_url	API 代理端点地址，替换默认的 api.openai.com。可使用七牛云 AI、阿里云百炼、DeepSeek 等国内兼容 OpenAI 协议的 API 服务
model	使用的模型名称，以所选 API 提供商的模型广场实际名称为准。示例：deepseek-v4-pro、qwen3.6-plus 等
sandbox_mode	文件系统访问模式：read-only（仅读取）、workspace-write（允许修改）、danger-full-access（完全访问）
web_search	联网搜索功能开关。国内网络建议设为 disabled，减少连接超时
approval_policy	命令审批策略：on-request（不确定时暂停确认）、auto-approve（自动批准）

5.3 设置 API Key 环境变量

方式一：写入 Shell 配置文件（推荐）

# bash 用户
echo 'export OPENAI_API_KEY="你的API Key"' >> ~/.bashrc
source ~/.bashrc

# zsh 用户
echo 'export OPENAI_API_KEY="你的API Key"' >> ~/.zshrc
source ~/.zshrc

方式二：系统级环境变量（所有用户生效）

sudo sh -c 'echo "OPENAI_API_KEY=你的API Key" >> /etc/environment'

方式三：会话级临时变量

export OPENAI_API_KEY="你的API Key"

API Key 获取途径：

• 七牛云 AI：https://portal.qiniu.com/ai-inference/api-key（国内手机号注册，新用户有免费额度）
• 阿里云百炼：https://bailian.console.aliyun.com/
• 其他国内兼容 OpenAI 协议的 API 服务提供商均可使用

5.4 多 Provider 自定义配置（高级）

适合需要在多个国内 API 之间灵活切换的场景：

#:schema https://developers.openai.com/codex/config-schema.json

openai_base_url = "https://api.qnaigc.com/v1"
model = "deepseek-v4-pro"
sandbox_mode = "workspace-write"
web_search = "disabled"
approval_policy = "on-request"

# 自定义 Provider 列表（多模型切换）
[[model_providers]]
name = "qiniu"
base_url = "https://api.qnaigc.com/v1"
env_key = "QINIU_API_KEY"

[[model_providers]]
name = "aliyun"
base_url = "https://dashscope.aliyuncs.com/compatible-mode/v1"
env_key = "ALIYUN_API_KEY"

六、安装验证与测试

6.1 版本验证

codex --version
# 预期输出示例：codex 0.131.0

6.2 配置诊断（v0.130.0+）

Codex CLI 提供 codex doctor 命令用于诊断配置是否正确：

codex doctor

该命令会检查以下项目：

• 配置文件 ~/.codex/config.toml 是否存在且格式正确
• OPENAI_API_KEY 环境变量是否已设置
• API 端点是否可达
• 模型是否可用

预期输出示例：

✅ Config file found at ~/.codex/config.toml
✅ OPENAI_API_KEY is set
✅ API endpoint reachable at https://api.qnaigc.com/v1
✅ Model 'deepseek-v4-pro' is available

若出现 ❌ 标记，根据提示进行修正。

6.3 基本功能测试

# 进入测试项目目录
cd ~/test-project

# 启动 Codex 交互会话
codex

# 在 Codex 提示符下输入简单任务测试，例如：
# > 在当前目录创建一个 hello.py 文件，内容为打印 "Hello, Codex!"

6.4 API 连通性测试

# 使用 curl 测试 API 连通性
curl -X POST "https://api.qnaigc.com/v1/chat/completions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -d '{
    "model": "deepseek-v4-pro",
    "messages": [{"role": "user", "content": "Hello!"}]
  }'

七、常见问题与解决方案

7.1 网络与访问类问题

问题 1：codex 命令执行后提示网络连接超时

现象：执行 codex 后出现 connect ETIMEDOUT 或 Connection timeout 错误。

原因：Codex CLI 默认尝试连接 api.openai.com，在企业内网或未配置代理的情况下无法直连。

解决方案：

1. 确认 ~/.codex/config.toml 中已正确配置 openai_base_url 指向国内兼容端点
2. 使用 codex doctor 检查配置是否生效
3. 若需使用代理，在终端中设置 HTTPS_PROXY 环境变量

问题 2：npm 安装包下载缓慢或失败

原因：npm 默认仓库在国外，信创环境可能无法直接访问。

解决方案：

1. 配置 npm 国内镜像源：npm config set registry https://registry.npmmirror.com
2. 使用离线安装方式（下载二进制包手动部署）
3. 通过企业内部 npm 私有仓库安装

7.2 架构兼容性问题

问题 3：ARM64 架构下 Illegal instruction (core dumped) 错误

原因：部分依赖库在编译时启用了 x86_64 专属指令集（如 AVX2），在 ARM64 平台无法执行。

解决方案：

1. 确保使用 ARM64 原生编译的依赖库（而非 x86_64 版本通过二进制翻译运行）
2. 对于 Python 依赖库（如 PyTorch），安装 ARM64 专用版本：

   pip install torch --index-url https://download.pytorch.org/whl/cpu
   

3. 使用 musl 静态链接的 Codex 二进制包，避免 glibc 版本兼容问题

问题 4：龙芯 LoongArch64 平台无法运行预编译二进制包

原因：OpenAI 官方目前未提供 LoongArch 架构的预编译包。

解决方案：

1. 在同网段部署 x86_64/ARM64 开发机作为 Codex 工作机，通过 SSH 远程使用
2. 使用 Docker 容器运行 x86_64 版本的 Codex（通过 QEMU 模拟或二进制翻译）
3. 关注官方仓库更新，等待 LoongArch 架构包发布

7.3 依赖与安装问题

问题 5：node: command not found 或 Node.js 版本过低

原因：国产系统自带的 Node.js 版本可能较旧（如 v12.x），不满足 Codex CLI 的 v18+ 要求。

解决方案：

1. 使用二进制包手动安装 Node.js 18+（参考 4.3 节）
2. 使用 nvm 管理多版本 Node.js：

   curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
   nvm install 18
   nvm use 18
   

问题 6：统信 UOS 提示“无有效签名”无法安装软件包

原因：统信 UOS 的安全机制限制了非官方签名的软件包安装。

解决方案：
进入“控制中心 → 通用 → 开发者模式 → 在线开启”即可解除限制。

问题 7：麒麟 V10 系统依赖包缺失或版本冲突

原因：麒麟 V10 基于较旧的 Ubuntu 基座，部分依赖库版本偏低。

解决方案：

1. 手动安装缺失依赖：sudo apt install -f
2. 从麒麟兼容适配页面下载所需 .deb 包手动安装
3. 对于不兼容的依赖，可考虑使用 Conda 创建独立虚拟环境

7.4 API 与模型问题

问题 8：codex doctor 提示 API Key 无效

解决方案：

1. 检查 OPENAI_API_KEY 环境变量是否正确设置：echo $OPENAI_API_KEY
2. 确认 API Key 未过期（登录提供商控制台检查）
3. 确认 API Key 有足够的调用额度

问题 9：模型调用返回 404 或模型不可用

原因：配置的模型名称与 API 提供商支持的名称不一致。

解决方案：

1. 以 API 提供商的模型广场实际名称为准更新 config.toml 中的 model 字段
2. 使用 codex doctor 检查可用模型列表
3. 联系 API 提供商确认模型状态

7.5 性能问题

问题 10：ARM64 平台推理速度偏慢

原因：ARM64 架构缺少类似 CUDA 的硬件加速支持。

解决方案：

1. 启用 CPU 多线程优化：设置 OMP_NUM_THREADS 和 MKL_NUM_THREADS 环境变量
2. 若配备昇腾 AI 芯片，可使用昇腾加速方案（需额外适配）
3. 在 config.toml 中选用更轻量的模型

八、安全合规建议

1. API Key 安全管理：避免将 API Key 硬编码在配置文件中，使用环境变量管理；定期轮换 API Key。
2. 数据安全审计：使用国内 API 端点时，确保数据传输加密（HTTPS），了解数据存储和处理政策。
3. 权限最小化：将 sandbox_mode 设置为 workspace-write 或 read-only，避免使用 danger-full-access 模式，限制 Codex 的文件系统访问范围。
4. 命令审批策略：将 approval_policy 设置为 on-request，确保破坏性操作（如 rm、git push --force）需人工确认后执行。
5. 版本持续更新：定期检查 Codex CLI 更新，及时应用安全补丁。
6. 信创安全合规：在信创安全权限管控策略下，确保 Codex 的文件操作权限、进程调度策略与国产系统的安全规范保持一致。

九、总结

本文档系统梳理了在国产信创环境下安装适配 OpenAI Codex CLI 的完整技术流程。核心适配要点总结如下：

适配环节	关键操作	适配说明
环境确认	uname -m 确认 CPU 架构	选择正确的安装包和依赖库版本
系统配置	配置国产系统软件源与系统依赖	解决依赖缺失和版本兼容问题
安装方式	优先使用 musl 静态链接二进制包	避免 glibc 版本兼容问题
网络适配	配置 openai_base_url 指向国内端点	解决 API 不可达的核心问题
依赖处理	配置 npm 镜像源、设置代理	确保安装过程顺畅
安全合规	API Key 安全管理、权限最小化	满足信创安全规范要求