在树莓派5上运行codex-desktop-linux：arm64部署完整实践指南

在树莓派5上运行codex-desktop-linux：arm64部署完整实践指南

【免费下载链接】codex-desktop-linuxUnofficial ChatGPT desktop app for Linux (formerly the Codex app), built locally from OpenAI’s official macOS app. Includes Chat, Work, and Codex. Packages for Debian/Ubuntu (.deb), Fedora/openSUSE (.rpm), Arch (pacman), Nix/NixOS, and AppImage, with Wayland and X11 support.项目地址: https://gitcode.com/gh_mirrors/co/codex-desktop-linux

想在树莓派5上运行 codex-desktop-linux 这个非官方 ChatGPT 桌面应用（ChatGPT Community）吗？它基于 OpenAI 官方 macOS/Linux 应用本地构建，包含 Chat、Work 和 Codex 三大模块，并已在一台 16 GB 内存的树莓派5（aarch64）上完成实测验证。本文带你完成 arm64 部署的完整实践。

为什么树莓派5能跑：arm64 支持说明 🖥️

codex-desktop-linux 的 ARM64 支持并非额外移植，而是复用了仓库中已维护的上游 ARM64 能力：构建时直接解析 OpenAI 签名稳定的官方arm64.deb包，复用其 Electron 运行时、原生模块和捆绑的 Codex CLI 平台二进制，全程不需要下载替换版 Electron 或重新编译原生模块。

官方实测环境如下：

构建产物被验证为Architecture: arm64的 Debian 包，Electron 可执行文件、原生 Node 模块、Linux 辅助工具和 Codex CLI 均为 AArch64 可执行文件，构建验收结论为accepted，无阻塞项或警告。详见 docs/raspberry-pi-5.md。

部署前准备：硬件与系统清单 📋

开始之前，确认你的树莓派5满足以下条件：

• 必须是 64 位操作系统（uname -m输出应为aarch64）
• 建议配备主动散热，原生构建属于 CPU 密集型任务
• 建议使用 SSD 或 NVMe 存储，机械 SD 卡会显著拖慢构建
• 构建工具链需要 Node.js 20+、npm、Python 3、curl、gpgv 等，这些会由安装脚本自动处理

💡 注意：该应用需要图形桌面会话。如果你的树莓派配置为纯控制台启动，必须先启用显示管理器（如 LightDM），否则无法从桌面菜单启动应用。

一键构建：bootstrap-native 快速部署

推荐路径是一条命令完成"装依赖 → 构建 → 打包 → 安装"的全流程：

git clone https://gitcode.com/gh_mirrors/co/codex-desktop-linux cd codex-desktop-linux PACKAGE_WITH_UPDATER=0 MAX_BUILD_THREADS=4 make bootstrap-native

两个环境变量是关键：

• PACKAGE_WITH_UPDATER=0：省略自动更新重建服务，让首次树莓派安装更简单。基线稳定后可以再单独评估是否启用
• MAX_BUILD_THREADS=4：将并行编译限制为 4 个任务，是树莓派散热与系统响应性的保守起点

完成后，dist/目录下会生成codex-desktop_*.deb，用标准 Debian 包管理器安装即可。若依赖已装好，后续只需：

make install-native

构建脚本的完整定义可参考 Makefile，依赖安装逻辑位于 scripts/install-deps.sh。

分阶段构建：手动控制编译流程（进阶）⚙️

如果你想在每一步都保留控制权，官方实测就采用了分阶段执行方式：

# 第一步：安装构建依赖 bash scripts/install-deps.sh # 第二步：构建应用（解包并验证官方 arm64 载荷） PACKAGE_WITH_UPDATER=0 MAX_BUILD_THREADS=4 make build-app-fresh # 第三步：打包为 Debian 包 PACKAGE_WITH_UPDATER=0 MAX_BUILD_THREADS=4 make deb

这个流程适合构建中途报错时需要单独重试某一阶段的场景。各阶段的职责划分详见 docs/native-setup.md。

桌面环境配置：从菜单启动 ChatGPT Community 🚀

安装完成后，应用会以ChatGPT Community（蓝色C图标）出现在桌面菜单中，包名和安装身份保持codex-desktop，安装于/opt/codex-desktop，方便与 OpenAI 官方ChatGPT包区分。

实测采用的桌面方案是 LightDM 自动登录 + Raspberry Pi Labwc Wayland 会话。启动后：

1. 从桌面菜单点击ChatGPT Community
2. 官方 ARM64 包已包含匹配的 Codex CLI 与平台运行时，无需额外安装
3. 完成账户登录即可使用

⚠️ 官方chatgpt与社区codex-desktop包可以共存，但两者共享上游 Codex 用户配置文件，请勿同时运行。

验证结果：Pi 5 上跑通了哪些功能 ✅

官方现场测试在树莓派5上通过了以下全部检查：

• 干净的 ARM64 应用解包与自定义包构建
• 原生arm64Debian 包创建与安装
• 图形化重启进入 Labwc Wayland 桌面
• 从实时桌面会话启动应用，正确渲染 ChatGPT 登录窗口
• 账户登录成功
• 使用捆绑 ARM64 Codex CLI 启动 Codex app-server
• 工作区文件的创建与编辑、集成命令执行
• Python、SQLite、自动化测试和本地 Git 工作流

换句话说，它不只是一台"能打开的树莓派"，而是一个可以真实跑 Codex 开发任务的 arm64 工作站。

进阶能力：Linux Computer Use 桌面操控 🖱️（可选）

如果你希望 Codex 在树莓派5上完成截屏、元素发现、全局键鼠输入等桌面操控任务，还需要额外配置（完整说明见 docs/linux-computer-use.md）：

• 安装at-spi2-core并开启工具包无障碍支持（AT-SPI 元素发现）
• 编译并安装 ARM64 版ydotool1.0.3+，启用ydotoold.service
• 将桌面用户加入input组，并通过 udev 规则让input组读写/dev/uinput
• 注意：Labwc 目前不是受支持的窗口控制后端，窗口列表与聚焦需借助wlrctl手动完成

🔒 安全提示：/dev/uinput访问权限仅限受信任的本地用户，保持设备规则按组作用域限定，不要使用全局可写模式。

常见问题与问题反馈 📮

遇到问题时，建议先查看 docs/troubleshooting.md，然后收集以下信息用于反馈：

• Pi 型号与内存大小
• uname -m输出的操作系统与架构
• 桌面环境及 X11/Wayland 会话类型
• 仓库 commit 与上游应用版本
• 完整构建命令与包格式
• ~/.cache/codex-desktop/launcher.log相关输出

最后提醒：树莓派5构建属于长时任务，保持散热良好、耐心等待；首次验证未测量长期热行为与更新管理器表现，建议稳定运行一段时间后再评估。

祝你部署顺利，早日把 AI 开发工作站搬上树莓派5！🎉

【免费下载链接】codex-desktop-linuxUnofficial ChatGPT desktop app for Linux (formerly the Codex app), built locally from OpenAI’s official macOS app. Includes Chat, Work, and Codex. Packages for Debian/Ubuntu (.deb), Fedora/openSUSE (.rpm), Arch (pacman), Nix/NixOS, and AppImage, with Wayland and X11 support.项目地址: https://gitcode.com/gh_mirrors/co/codex-desktop-linux