前言
OpenAI Codex Desktop 是 OpenAI 推出的桌面端 AI 编程助手，提供强大的代码生成、理解和调试能力。然而官方仅提供了 macOS 和 Windows 版本，Linux 用户一直被排除在外。
好在开源社区从不让人失望——codex-desktop-linux 项目通过转换上游 macOS Codex.dmg，生成可在 Linux 上原生运行的 Electron 应用，完美填补了这个空白。
为了让国内用户更方便地获取最新安装包，我在 GitHub 上维护了一份 Fork，并在 Releases 页面 提供已经构建好的 .deb / .rpm / .pkg.tar.zst / AppImage 等格式的直接下载，省去自行构建的繁琐流程。
本文将详细介绍这个项目的使用方式，包括安装、配置、更新和故障排查。
项目概述
codex-desktop-linux 是一个非官方的 Linux 构建包装器，核心思路是：
将官方 macOS 版本的 Codex Desktop 安装包（
.dmg）通过自动化脚本转换为 Linux 可运行的 Electron 应用。
它支持构建多种 Linux 原生包格式：
| 格式 | 适用发行版 |
|---|---|
.deb | Debian, Ubuntu, Pop!_OS, Mint, Elementary |
.rpm | Fedora, openSUSE, RHEL 系 |
.pkg.tar.zst | Arch, Manjaro, EndeavourOS |
| AppImage | 所有 Linux 发行版（原子桌面/其他） |
| Nix flake | NixOS / Nix |
安装方式
方式一：从 GitHub Releases 下载安装（推荐）
这是最省时省力的方式，适用于大多数不想折腾构建环境的朋友。访问 Releases 页面，根据你的发行版选择对应包：
下载选择
| 发行版 | 下载文件 | 大小 |
|---|---|---|
| Debian / Ubuntu / Pop!_OS / Mint | codex-desktop_*.deb | ~328MB |
| Fedora / RHEL / openSUSE | codex-desktop-*.rpm | ~328MB |
| Arch / Manjaro / EndeavourOS | codex-desktop-*.pkg.tar.zst | ~328MB |
| 任何发行版 | codex-desktop-*.AppImage | ~328MB |
安装方法
# Debian/Ubuntu（替换 * 为实际版本号）
sudo dpkg -i codex-desktop_*.deb
sudo apt install -f # 如有依赖问题
# Fedora/RHEL
sudo rpm -ivh codex-desktop-*.rpm
# Arch Linux
sudo pacman -U codex-desktop-*.pkg.tar.zst
# AppImage（无需安装）
chmod +x codex-desktop-*.AppImage
./codex-desktop-*.AppImage安装后启动：
codex-desktop首次启动会提示安装 Codex CLI，按引导操作即可。
注意：预构建包可能与你的系统不完全兼容。如有问题，请从源码构建（见下方本地构建指南）。
方式二：一键原生安装
如果你希望从源码自行构建，可以克隆仓库后一键安装：
git clone https://github.com/appotry/codex-desktop-linux.git
cd codex-desktop-linux
make bootstrap-nativemake bootstrap-native 会帮你完成所有事情：
- 安装构建依赖
- 下载最新上游
Codex.dmg - 构建
codex-app/目录 - 为当前发行版打包
- 安装最新产物到
dist/
如果依赖已经安装过，可以跳过依赖安装步骤：
make install-native方式三：手动安装依赖后构建
某些发行版可能需要手动处理依赖。以 Fedora 为例：
# Fedora 41+
sudo dnf install python3 7zip curl unzip rpm-build @development-tools
# Fedora < 41
sudo dnf install python3 p7zip p7zip-plugins curl unzip rpm-build
sudo dnf groupinstall 'Development Tools'方式四：Nix flake
NixOS 用户或使用 Nix 包管理器的用户：
nix run github:appotry/codex-desktop-linux详情参见项目中的 Nix 文档。
方式五：AppImage（通用）
如果你使用原子桌面（如 Fedora Silverblue）或其他非主流发行版：
make build-app && make appimage这种方式是自包含构建，不包含自动更新管理器。
安装前须知
在开始之前，有几个关键点需要了解：
运行时依赖：生成的应用和原生包会捆绑托管的 Linux Node.js 运行时。正常安装、Browser Use、Codex CLI 安装/更新或本地自动更新重建不需要发行版自带的 nodejs / npm 包。
Codex CLI：运行时仍需 Codex CLI。首次启动可通过内置 npm 安装或更新 @openai/codex，也可自行管理 CLI。
显示协议：支持 X11 和 Wayland 会话。启动器在 Wayland 下优先使用 XWayland（以获得更好的 Electron 弹窗定位），然后回退到 Electron 的自动 Wayland 处理。
首次运行向导
项目提供了第一次运行的交互式向导：
make setup-native这个向导会引导你完成可选功能的配置，并检测系统环境。
功能矩阵
codex-desktop-linux 不仅还原了官方的 Codex Desktop 功能，还增加了大量 Linux 专属的增强特性：
| 功能 | 默认 | 说明 |
|---|---|---|
| 标准 Codex Desktop UI | 始终启用 | 完整的官方 UI 体验 |
| 托管的 Linux Node.js 运行时 | 始终启用 | 构建时自动捆绑，无需系统 Node |
| 原生包 | 始终启用 | .deb / .rpm / .pkg.tar.zst |
| 自动更新管理器 | 原生包包含 | systemd --user 服务，自动检查上游更新 |
| AppImage 自构建 | 手动 | 通用可执行格式 |
| Nix flake | 手动 | NixOS 原生支持 |
| Linux 文件管理器集成 | 始终启用 | 内置于核心 Linux 补丁 |
| Chrome 插件原生主机 | 始终启用 | 与浏览器插件通信 |
| 浏览器标注 | 始终启用 | 内置于修补后的 webview |
| 托盘和热启动切换 | 始终启用 | 系统托盘快速切换 |
| 多实例 | 可选 | --new-instance 参数 |
| Linux Computer Use 后端 | 捆绑 | MCP 后端默认注册 |
| Linux Computer Use UI | 可选 | 环境变量开启 |
可选的 Linux Feature
除了核心功能外，项目还提供了一套可插拔的 Linux Feature 系统，位于 linux-features/ 目录下。这些功能默认禁用，可以根据需要启用。
启用方式：
cp linux-features/features.example.json linux-features/features.json编辑 features.json：
{
"enabled": [
"read-aloud",
"zed-opener"
]
}可用 Feature 一览：
| Feature | 说明 |
|---|---|
conversation-mode | 对话模式 |
copilot-reasoning-effort | Copilot 推理努力值默认值 |
open-target-discovery | Open Target Discovery |
read-aloud | 朗读按钮 |
read-aloud-mcp | 朗读 MCP |
remote-control-ui | 远程控制 UI（实验性） |
remote-mobile-control | 远程移动控制（实验性） |
thorium-chrome-plugin | Thorium Chrome 插件支持 |
zed-opener | Zed 编辑器打开器 |
codex-wrapper-updater | Wrapper 更新按钮 |
agent-workspaces | Agent Workspaces |
appshots | Linux AppShots |
需要注意的是，由服务端控制的上游功能（如模型发布）由 OpenAI 按账户管理。重建此包装器不会解锁它们。
更新机制
自动更新
默认原生包会安装 codex-update-manager，这是一个 systemd --user 服务：
- 定期检查上游是否有新版
Codex.dmg - 自动下载并重建本地原生包
- 在 Codex Desktop 退出后自动安装
最终的安装操作使用 pkexec。如果你使用平铺窗口管理器，需要图形化的 polkit 认证代理来使用应用内安装按钮；否则更新器会准备好包并通过终端报告。
手动更新
# 不从远程拉取最新 DMG，手动指定
PACKAGE_WITH_UPDATER=0 make package
make install# 从可信签出手动完全重建
PACKAGE_WITH_UPDATER=0 make update-native禁用自动更新
如果不需要自动更新功能，可以在打包时指定：
PACKAGE_WITH_UPDATER=0 make packageAppImage 构建和仅仓库生成的应用不包含原生包更新器。
本地构建指南
如果你希望自行从源码构建，而不是使用预构建包，本节将详细介绍完整的构建流程。
构建流程概述
构建的本质是：将官方 macOS 版 Codex.dmg 解包，打上 Linux 补丁，重新打包为 Linux 原生包。
macOS Codex.dmg（497MB）
↓ 7z 解包
Electron 应用
↓ npm install + 编译原生模块
已修补的 Linux Electron 应用
↓ 打包
.deb / .rpm / .pkg.tar.zst / AppImage前置条件
系统依赖
# Ubuntu/Debian
sudo apt install p7zip-full curl unzip
# 如果从零构建（bootstrap-native），会自动安装依赖
# 如果已有环境（install-native），只需确保上述工具存在Rust 工具链
编译原生模块需要 Rust：
rustup default stable分步构建
快速构建（推荐，重用缓存）
如果你已经构建过一次，希望使用本地缓存加速：
cd ~/Work/codex-desktop-linux
# 设置环境变量，跳过网络下载（使用前确认本地缓存存在）
export CODEX_MANAGED_NODE_SOURCE="$HOME/.local/share/mise/installs/node/24.17.0"
export CODEX_ELECTRON_ZIP_SOURCE="$HOME/.cache/codex-desktop/electron/electron-v42.1.0-linux-x64.zip"
export ELECTRON_MIRROR="https://npmmirror.com/mirrors/electron/"
# 构建应用 + 打包 .deb
make build-app && make package完整构建（从零开始）
make install-native会依次执行：
build-app— 解包 DMG → 安装 npm 依赖 → 编译原生模块 → 打 Linux 补丁package— 打包为 .deb/.rpminstall— 安装到系统
分步执行
| 步骤 | 命令 | 说明 |
|---|---|---|
| 解包 + 编译 | make build-app | 生成 codex-app/ 目录 |
| 打包 | make package | 生成 .deb 到 dist/ |
| 安装 | sudo dpkg -i dist/*.deb | 安装到系统 |
| 运行（不安装） | ./codex-app/start.sh | 直接启动，不安装 |
使用本地 DMG
如果你已经下载了 Codex.dmg，可以指定本地路径，避免重复下载：
make build-app DMG=/path/to/Codex.dmg构建特定包格式
make deb # Debian/Ubuntu
make rpm # Fedora/RHEL/openSUSE
make pacman # Arch/Manjaro
make appimage # 通用 AppImage包脚本仅重新打包已生成的
codex-app/目录，不会自行下载或提取 DMG。
构建产物
| 产物 | 路径 | 大小 |
|---|---|---|
| Electron 应用目录 | codex-app/ | ~500MB |
| .deb 包 | dist/codex-desktop_*.deb | ~328MB |
| 启动脚本 | codex-app/start.sh | — |
网络加速（国内用户必读）
海外用户可跳过此节。国内访问 GitHub / crates.io / OpenAI CDN 极慢，必须配置。
cargo 镜像
国内访问 crates.io 极慢，必须配置镜像。编辑 ~/.cargo/config.toml：
[source.crates-io]
replace-with = "sjtug-sparse"
[source.sjtug-sparse]
registry = "sparse+https://mirrors.sjtug.sjtu.edu.cn/crates.io-index/"验证：
curl -sI --max-time 10 "https://mirrors.sjtug.sjtu.edu.cn/crates.io-index/config.json"
# 应返回 HTTP/2 200Electron 镜像
export ELECTRON_MIRROR="https://npmmirror.com/mirrors/electron/"预下载大文件
用 motrix-next（aria2 前端）多线程下载，避免 curl 单线程超时：
# Codex.dmg（497MB）
motrix-next download-add url="https://persistent.oaistatic.com/codex-app-prod/Codex.dmg" dir="$HOME/Work/codex-desktop-linux"
# Electron v42.1.0（114MB）
motrix-next download-add url="https://npmmirror.com/mirrors/electron/v42.1.0/electron-v42.1.0-linux-x64.zip" dir="$HOME/.cache/codex-desktop/electron"跳过重复下载
如果构建时网络不稳定，脚本会反复重试下载。设置环境变量即可跳过远程检测：
# 跳过上游版本检查，直接使用本地缓存（即使网络不通）
export CODEX_DMG_FORCE_CACHE=1
make build-app构建常见问题
cargo 下载失败
error: failed to get `xxx` as a dependency→ 检查 cargo 镜像配置是否正确，切换到 SJTUG sparse 镜像。
Codex.dmg 重复下载
脚本每次执行 --fresh 时删除缓存。如要强制重新下载：
rm -f Codex.dmg.metadata && make build-appElectron 版本不匹配
DMG 中包含的 Electron 版本可能变化，需下载对应的 Linux 版：
# 查看 DMG 中的 Electron 版本
grep -o '"version":"[^"]*"' codex-app/resources/app.asar.unpacked/node_modules/electron/package.json
# 下载对应版本
motrix-next download-add url="https://npmmirror.com/mirrors/electron/v<版本>/electron-v<版本>-linux-x64.zip"Browser Use 下载失败
构建过程中出现 Downloading Browser Use node_repl fallback runtime 卡住，是因为从 OpenAI CDN 下载大文件超时。
不影响核心功能，仅 computer-use（浏览器操控）相关插件不可用。Codex 本身的对话、代码编辑、终端功能一切正常。
解决方案：用 motrix-next 多线程下载后重新构建：
BROWSER_USE_URL="https://persistent.oaistatic.com/codex-primary-runtime/26.426.12240/codex-primary-runtime-linux-x64-26.426.12240.tar.xz"
CACHE_DIR="$HOME/.cache/codex-desktop/browser-use"
mkdir -p "$CACHE_DIR"
# 用 aria2 RPC 多线程下载
curl -s "http://localhost:30000/jsonrpc" \
-H "Content-Type: application/json" \
-d "{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"aria2.addUri\",\"params\":[\"token:YOUR_SECRET\", [\"$BROWSER_USE_URL\"], {\"dir\":\"$CACHE_DIR\",\"split\":\"16\"}]}"下载完成后重新 make build-app 即可。
启动后卡在加载界面
如果应用启动后一直显示加载界面，通常有两个原因：
- Codex CLI 未找到（见下文 CLI 配置）
- Webview 服务未就绪 — 检查端口 5175 是否被占用：
ss -tlnp | grep 5175
pkill -f "webview-server.py" # 杀掉残留进程后重试应用正常启动后的进程链：
start.sh → webview-server.py (:5175) → electron → 界面显示Codex CLI 配置
首次启动会提示 Unable to locate the Codex CLI binary，因为 Desktop 应用在 resources/bin/codex 中查找 CLI。
方案一（推荐）：符号链接到 resources 目录
sudo mkdir -p /opt/codex-desktop/resources/bin
sudo ln -sf $HOME/.local/share/mise/installs/npm-openai-codex/latest/bin/codex /opt/codex-desktop/resources/bin/codex方案二：环境变量（无需 sudo）
CODEX_CLI_PATH=$(which codex) /opt/codex-desktop/start.sh方案三：直接安装到全局
mise use --global npm:@openai/codex故障排查
/tmp 挂载为 noexec
某些 Linux 发行版将 /tmp 挂载为 noexec，会导致 Electron 运行时出错。
解决方案：将 TMPDIR 和 XDG_CACHE_HOME 设为 $HOME 下的可执行目录。
export TMPDIR="$HOME/tmp"
export XDG_CACHE_HOME="$HOME/.cache"空白窗口或启动画面卡住
最常见的症状是启动后看到空白窗口或卡在 Codex 启动画面。
排查步骤：
- 检查日志文件：
~/.cache/codex-desktop/launcher.log - 检查端口
5175是否已被占用 - 确保没有其他 Codex 实例在运行
CLI 安装错误
如果遇到 CODEX_CLI_PATH 或 CLI 安装错误：
- 重新打开应用
- 或手动安装
@openai/codex：npm install -g @openai/codex
Wayland / GPU / Vulkan 问题
如果遇到 Wayland 下的图形问题：
# 使用 Wayland GPU 模式
CODEX_LINUX_RENDERING_MODE=wayland-gpu ./codex-app/start.sh也可以创建持久启动标志脚本。
调整大小时出现残影或帧残留
CODEX_ELECTRON_DISABLE_GPU_COMPOSITING=1 ./codex-app/start.sh或者添加 --disable-gpu-compositing 参数。
Computer Use 相关问题
UI 隐藏：先启用 Computer Use UI 可选功能。注意服务端控制的部件可能仍会被隐藏，因为账户/服务器发布控制着显示权限。
无输入后端：检查以下项目：
# 检查 /dev/uinput 是否存在
ls -la /dev/uinput
# 检查 portal 支持
# 或安装 ydotool
systemctl --user status ydotool更新器卡住
检查更新器状态：
codex-update-manager status --json查看服务日志：
journalctl --user -u codex-update-manager.service项目架构简析
对于对实现细节感兴趣的朋友，这里简单介绍一下项目的架构：
codex-desktop-linux/
├── codex-app/ # 生成的 Electron 应用
├── linux-features/ # 可插拔的 Linux 功能
│ ├── features.json # 功能开关
│ └── <feature-id>/ # 每个功能的实现
├── docs/ # 文档
├── Makefile # 构建入口
└── scripts/ # 构建脚本核心流程：
- 提取：从 macOS DMG 中提取 Codex Desktop 的核心资源
- 修补：应用 Linux 特定的补丁（文件管理器集成、Chrome 插件主机、Wayland 支持等）
- 打包：根据目标发行版打包成对应的原生格式
- 安装：通过系统包管理器安装
总结
codex-desktop-linux 是 Linux 用户使用 OpenAI Codex Desktop 的最佳方案。它不仅完整还原了官方体验，还增加了大量 Linux 专有特性，从文件管理器集成到 Systemd 自动更新服务，处处体现着社区的力量。
无论是 Ubuntu 新手还是 Arch 老手，都能在几分钟内完成安装。如果你希望直接使用预构建包，可以访问 Releases 页面 下载。