在Linux上运行OpenAI Codex Desktop完整指南

前言

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 等格式的直接下载，省去自行构建的繁琐流程。

本文将详细介绍这个项目的使用方式，包括安装、配置、更新和故障排查。

linux codex destop

项目概述

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-native

make 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 package

AppImage 构建和仅仓库生成的应用不包含原生包更新器。

本地构建指南

如果你希望自行从源码构建，而不是使用预构建包，本节将详细介绍完整的构建流程。

构建流程概述

构建的本质是：将官方 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/.rpm
install — 安装到系统

分步执行

步骤	命令	说明
解包 + 编译	`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 200

Electron 镜像

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-app

Electron 版本不匹配

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/                # 构建脚本

核心流程：