ChatGPT Community for Linux

English | 简体中文 | فارسی

codex-desktop 是 OpenAI 官方 Linux ChatGPT 桌面应用的非官方社区发行版。 它验证并重新打包已签名的官方 Linux 软件包，提供默认关闭的 Linux 扩展， 并可构建 deb、RPM、pacman、AppImage 和 Nix 产物。

桌面菜单中的自定义应用名为 ChatGPT Community，图标带有蓝色 C。 软件包名、命令名和安装目录仍为 codex-desktop、codex-desktop 和 /opt/codex-desktop，因此可以与 OpenAI 的 ChatGPT 清楚区分。

唯一的上游来源是 OpenAI 已签名的 Linux .deb。官方 Electron runtime、 原生模块、内置 codex 和 rg、code-mode host、插件、库、locale 与 Owl metadata 均被直接复用。默认构建仅对 resources/app.asar 应用必要的兼容性补丁， 并逐字节保留官方 ELF runtime 和内置工具。可选 Linux 扩展只有在明确选择后才会启用。

安装 · 卸载 · 功能 · 更新 · 构建 · 故障排除 · 文档 · Discord

参与贡献前请阅读 CONTRIBUTING.md。维护者和 coding agent 还应阅读 AGENTS.md。

安装

构建原生软件包或 AppImage 前先克隆仓库：

git clone https://github.com/ilysenko/codex-desktop-linux.git
cd codex-desktop-linux

平台	推荐命令	结果
Debian、Ubuntu、Pop!_OS、Mint、Elementary	make bootstrap-native	构建并安装 .deb
Raspberry Pi 5（64 位系统）	make bootstrap-native	构建官方 arm64 payload；参阅 Pi 说明
Fedora	make bootstrap-native	构建并安装 RPM
openSUSE	make bootstrap-native	构建并安装 RPM
Arch、Manjaro、EndeavourOS	make bootstrap-native	构建并安装 pacman 软件包
Gentoo	make bootstrap-native	构建本地 ebuild 并通过 Portage 安装；仅支持已审计的功能，不含更新器
NixOS 或其他 Nix 系统	nix run github:ilysenko/codex-desktop-linux	构建并运行 flake；参阅 Nix
Atomic 桌面或其他发行版	make build-app && make appimage	生成不含原生更新器的本地 AppImage

Gentoo 的应用合并会忽略 EMERGE_DEFAULT_OPTS，从生成的 ebuild 安装载荷，而非复用 二进制包缓存；不会修改全局 Portage 配置。 Gentoo 已提供分阶段依赖和包资源框架；现已支持 ui-tweaks、 remote-mobile-control 和 community-features-in-gui-settings，且仍默认关闭。手机远程控制沿用由 Desktop 管理的 app-server；ebuild 不安装或启用远程控制服务。 只读社区功能目录嵌入 ASAR，无需额外 Gentoo 依赖或更新构建器快照； 打包验证与实机 GUI 验收的区别见目录功能的 Gentoo 说明。 其他仓库功能需单独审查并声明支持。字段约定见Gentoo 功能契约。 Gentoo 本地 ebuild 安装路径已在 OpenRC 环境测试，尚未测试 Gentoo systemd 环境；验证范围见Gentoo 原生安装说明。

推荐的原生安装命令：

make bootstrap-native

它会安装构建依赖，通过 OpenAI 已签名的 stable APT metadata 解析当前 软件包，构建 codex-app/，创建适用于当前发行版的原生包，并安装 dist/ 中的最新产物。

依赖已经安装时使用：

make install-native

若要使用图形化引导安装器，请运行仓库中的独立入口：

./install-community

（make guided-install 调用同一个入口。）安装器属于仓库安装流程本身， 不是一个可选 Linux 扩展。在支持 GTK4/PyGObject 的桌面环境中，它会依次 完成扩展选择、安装选项、配置确认以及带实时日志的构建/安装进度。依赖扩展 会自动选中；与当前选择冲突的扩展会被禁用，并显示原因。

图形化安装器不会修改扩展实现或扩展设置。它只更新被启用的扩展列表以及 gitignored 的 linux-features/features.json 中属于安装器自己的偏好， 已有扩展设置会保持不变。无论是否包含自动更新器，原生输出始终保持 codex-desktop 软件包身份并安装到 /opt/codex-desktop。

如果只想配置扩展而暂不安装，仍然使用：

make setup-native
make install-native

make setup-native 只保存本地扩展选择，不会构建或安装应用。向导、 非交互配置、更新器选择和清理方式见原生安装。

使用已下载的官方软件包

默认构建会从签名 stable index 中选择 amd64 或 arm64。也可以复用已下载的 本地软件包，避免再次下载包体：

UPSTREAM_DEB=/path/to/chatgpt_<version>_<arch>.deb make build-app

本地包默认仍用签名 stable metadata 核对版本、architecture、大小和 SHA-256。 所有构建默认验证，不询问或读取用户输入，交互终端中也一样。 只有显式传入以下开关，才选择仅对本次构建生效的例外：

./install.sh --skip-oai-official-sig-verification /path/to/chatgpt_<version>_<arch>.deb

该开关要求提供本地包，仍检查 package name、版本格式、architecture 和 payload 完整性，并记录 SHA-256 与 signatureVerification: "skipped"；此时来源由调用者 负责。选择不会保存到配置，验签失败也不会自动改为跳过。 详见构建与打包。 旧 .dmg、DMG= 和 CODEX_DMG_* 输入已明确不再支持。

安装前须知

• 仅支持 OpenAI 最新的已签名 stable Linux 软件包和 amd64 / arm64。
• 构建需要 Node.js 20+、npm、Python 3、curl、gpgv、dpkg-deb、tar、 make 和 C/C++ 工具链。更新器及启用的原生扩展 helper 还需要 Rust。 make bootstrap-native 会安装或提示这些依赖。
• 官方 chatgpt 与自定义 codex-desktop 可以同时安装。默认情况下两者会 共享上游 Codex 用户 profile，因此不应同时运行。可选的 community-profile-isolation 扩展会为 Community 使用独立的 Codex 与 Electron 状态，并固定其内置 CLI，从而避免这条共享 profile 边界。
• AppImage 不会自动添加 --no-sandbox。若发行版禁用了 unprivileged user namespaces，请使用原生软件包或参阅故障排除。

匿名每日使用计数

为了帮助社区判断是否值得继续维护本发行版，launcher 每个 UTC 日期最多向 公开的 GoatCounter dashboard 发送一次匿名 使用事件。事件只包含固定路径 /app-launch。GoatCounter 根据网络请求生成汇总 国家信息；不会发送应用内操作、账户或设备标识、版本、架构、软件包格式、语言、 屏幕尺寸或 referrer。所有安装都会发送相同且不含识别信息的固定 User-Agent， 以避免 GoatCounter 将请求当作 bot 丢弃。

请求会在后台静默执行。缺少 curl、请求被拦截或发生任何其他错误时，应用启动 都不会被延迟，也不会产生输出。可用唯一的环境变量关闭此计数：

CODEX_LINUX_DISABLE_USAGE_REPORTING=1 codex-desktop

卸载

先完全关闭 ChatGPT Community 和官方 ChatGPT，然后使用安装它的包 管理器卸载：

# Debian / Ubuntu
sudo apt remove codex-desktop

# Fedora
sudo dnf remove codex-desktop

# openSUSE
sudo zypper remove codex-desktop

# Arch / Manjaro
sudo pacman -R codex-desktop

# Gentoo
sudo emerge --deselect app-misc/codex-desktop
sudo emerge --unmerge app-misc/codex-desktop

原生包卸载时会禁用用户更新服务。若旧安装或手动安装仍留下服务：

systemctl --user disable --now codex-update-manager.service
systemctl --user daemon-reload

AppImage 只需删除构建出的文件。仓库内生成的应用树可在 checkout 根目录中删除：

rm -rf -- ./codex-app

Nix 用户应从 profile、Home Manager 配置或 NixOS module 中删除该包，然后重新 构建 profile 或系统。

卸载软件包不会删除用户数据。仅要删除 Community wrapper 与更新器状态时， 请先检查再删除以下目录：

~/.config/codex-desktop
~/.local/state/codex-desktop
~/.cache/codex-desktop
~/.config/codex-update-manager
~/.local/state/codex-update-manager
~/.cache/codex-update-manager

若启用了 community-profile-isolation，Community 自己的状态位于 ~/.codex-community，Electron profile 位于 ~/.config/Codex-Community。 只有在确实要删除这份隔离的 Community 数据时才删除这些路径。

若启用了 remote-mobile-control，删除 private device keys 前请先撤销配对设备。 除非你确实希望删除默认共享的 Codex profile、配置、插件和项目状态，否则不要 删除 ~/.codex。

功能矩阵

核心发行版

能力	默认状态	提供方式
官方 ChatGPT Linux runtime	始终启用	来自已验证官方 .deb 的 data payload
签名来源验证	默认启用	固定 repository key → InRelease → Packages SHA-256 → package SHA-256；显式本地例外会记录在构建元数据中
deb、RPM、pacman 原生包	手动构建	make deb、make rpm、make pacman
AppImage	手动构建	make appimage；不绕过 sandbox，不含原生 updater
Nix flake	手动构建	nix run github:ilysenko/codex-desktop-linux
事务式更新管理器	原生包	除非设置 PACKAGE_WITH_UPDATER=0
官方 Browser 和 Chrome 集成	上游提供	直接复用官方 Linux 实现，不保留旧移植层
可靠的 shell 环境启动	始终启用	由已验证的上游 runtime 负责；不应用核心 shell 启动补丁
可靠地完成已批准的退出	始终启用	必需的核心补丁在唯一的 before-quit owner 中消费上游退出批准，使清理流程能够到达 will-quit
Linux 可选扩展框架	默认关闭	使用 make setup-native 配置
独立桌面标识	始终启用	ChatGPT Community、蓝色 C 图标、codex-desktop package identity

可选 Linux 扩展

以下扩展全部默认关闭。每个扩展目录中的 README 都包含依赖、限制、配置与测试。

扩展 ID	用途	文档
account-switcher	实验性功能：从个人资料菜单切换加密保存的 ChatGPT 登录；需要 Secret Service 和 secret-tool；本地聊天和设置共用	文档
agent-workspace	隐藏桌面环境中的 agent-workspace 设置和 bridge	文档
api-key-model-visibility	显示 API-key compatible provider 返回的模型	文档
api-key-service-tier	API-key compatible provider 的 Fast/service-tier UI	文档
appshots	从 composer 捕获并裁剪当前 Linux 窗口	文档
authored-message-visibility	工具活动折叠后，仍显示助手和用户消息	文档
authenticated-proxy	带用户名和密码的 HTTP proxy	文档
automation-extensions	多时间调度和 eager automation_update	文档
browser-proxy	让 Browser Use 的网络辅助进程继承显式代理设置	文档
chatgpt-dil-markdown-fallback	交互式 ChatGPT 回复渲染失败时显示已保存的 Markdown 正文	文档
chatgpt-dots-any-country	当账号响应受到国家限制时，仍显示 ChatGPT Dots 入口和可用性说明	文档
chatgpt-sidebar-separate-history	ChatGPT 历史记录默认仅显示聊天，并记住聊天 / Work / 全部筛选选项	文档
chronicle-skysight	可选的 Linux 桌面活动记忆与受限 Skysight MCP 工具	文档
codex-micro	使用上游 node-hid 的 Codex Micro hotplug/hidraw policy	文档
community-features-in-gui-settings	在常规设置页顶部查看公共功能、已声明的子功能及已启用的本地功能树；显示构建选择的数量与状态，支持英语和简体中文	文档
community-profile-isolation	将 Community 的 Codex/Electron 状态与子进程 CLI 解析和官方 ChatGPT 隔离	文档
computer-use-linux	Linux desktop-control UI 与原生 MCP backend	文档
copilot-reasoning-effort	Copilot auth 的 reasoning-effort 默认值	文档
desktop-identity	通知与子进程使用 Community 桌面入口标识，以正确显示图标	文档
desktop-new-window	在 ChatGPT Community 桌面启动器中添加“新建窗口”操作	文档
directory-only-working-tree-watch	有界 Watchbound 工作树监听	文档
filesystem-root-follow-ups	允许工作目录为 / 的现有本地任务继续发送消息	文档
flatpak-chrome-native-messaging	将官方 Chrome 扩展连接到 Flatpak Google Chrome	文档
frameless-titlebar	隐藏官方 Linux overlay 按钮，改由 compositor 管理窗口装饰	文档
global-dictation	X11 / XDG portal 全局听写快捷键	文档
wayland-global-shortcuts	为弹出聊天、Mini/Pet 等全局快捷键提供原生 Wayland 支持；可独立于听写启用	文档
global-dictation-gnome	无需 RemoteDesktop 会话的可选 GNOME Shell 粘贴扩展；依赖 global-dictation，必须显式启用扩展	文档
linux-performance-workarounds	针对受影响系统的 renderer workaround	文档
mcp-helper-reaper	安全清理孤立 MCP helper	文档
model-picker-default-presets	配置 ChatGPT Default 的有序 model/effort 组合	文档
node-repl-reaper	清理 owner 退出后泄漏的 Browser Use node_repl	文档
omarchy-theme	加载当前 Omarchy 主题生成的 CSS	文档
persistent-status-panel	在线程切换和重启后保留 /status panel	文档
pet-overlay	Linux avatar overlay 定位和 compositor hints	文档
preferred-editor-file-links	单击源代码链接时使用所选编辑器打开	文档
project-group-last-updated-sort	对 project group 和 task 应用 Last updated 排序	文档
project-task-sort	恢复 alternate Projects 的 Created 排序	文档
read-aloud	为 assistant response 添加 Linux 朗读控件	文档
read-aloud-mcp	让 agent 通过 Linux Read Aloud backend 发声	文档
reasoning-visibility	在常规设置中添加默认关闭且已翻译的推理摘要开关；重启后生效	文档
record-and-replay	将 Linux 操作演示录制为可复用 skill	文档
remote-control-ui	显示实验性 remote-control 设置	文档
remote-mobile-control	实验性 Linux remote-host / outbound-control flow	文档
shallow-repository-watches	避免临时 repo preview 在主线程递归遍历	文档
shared-app-server-socket	共享 protocol-transparent Unix app-server socket	文档
start-minimized-to-tray	在常规设置中添加默认关闭的启动到系统托盘选项，可选择每次启动或仅登录自动启动时隐藏窗口	文档
thorium-chrome-plugin	为官方 Chrome integration 添加 Thorium	文档
tray-usage	在 Linux 系统托盘菜单显示剩余用量	文档
usage-limit-send-attempt	登录账户用量耗尽时，仍允许在本地 Codex 对话中尝试发送消息	文档
ui-tweaks	可选 UI 与交互自定义	文档

若要在 GNOME Wayland 下听写时避免 RemoteDesktop 权限提示，请通过 make setup-native 同时选择 global-dictation 和 global-dictation-gnome， 然后重新构建并安装。首次启动应用会为当前用户安装配套扩展；注销并重新登录后， 显式执行 gnome-extensions enable [email protected]。 启用扩展后请重启应用/helper。helper 会在启动时自动检查配套扩展的版本： 已启用且兼容时选择 GNOME，否则选择 RemoteDesktop；此选择在重启前保持不变。 一旦选择 GNOME，粘贴错误不会回退到 RemoteDesktop，也不会自动重试。 构建功能仅负责分发和安装配套扩展；手动安装的兼容扩展也会被自动检测。 快捷键授权仍使用 GlobalShortcuts。关闭构建功能不会卸载用户扩展；详见 启用与移除说明。

可选的 Computer Use backend 提供 guard-accessibility 命令，可显式在前台保持 GNOME 辅助功能开启。它不会自动启动；详见 Linux Computer Use。

启用 shared-app-server-socket 并保持 Desktop 运行后，可使用 codex-desktop --cli 将 Codex CLI 连接到 Desktop 的 app-server。详见 CLI 连接说明。

ChatGPT account rollout 和 server-side 功能仍由 OpenAI 控制。重新构建本项目 不会解锁账号功能。

如需输入 CSS 字体 fallback 列表，可启用可选的 ui-tweaks 自定义字体输入， 在外观设置的字体菜单中切换系统字体列表与手填字体栈。这个子选项默认关闭， 需在本地 feature settings 中启用后重新构建。

ui-tweaks 的可选子选项 tweaks.selection.moreDetails.enabled 可恢复 Codex 回复正文选中文字菜单中的“更多详情”，让 ChatGPT Quick Chat 结合原对话上下文解释 所选文字。此子选项默认关闭；详见 UI Tweaks 配置。

测试本地构建时，通过 codex-app/start.sh 启动，并保留正常桌面启动器中的 Electron 参数，包括需要的 --proxy-server=...。ChatGPT 账号初始化完成后， Quick Chat 入口才会可用。

ui-tweaks 的可选子选项 tweaks.selection.annotationSubmit.enabled 默认关闭： 选中文字后，当前有活动的批注文字编辑器时，Ctrl+Enter 发送批注文字，不被常规输入框拦截。 详见批注发送配置。

配置可选扩展

推荐使用向导：

make setup-native

也可以手动复制 gitignored 配置：

cp linux-features/features.example.json linux-features/features.json

{
  "enabled": [
    "read-aloud",
    "ui-tweaks"
  ]
}

然后重新构建并安装：

make install-native

私有扩展可以放在 gitignored 的 linux-features/local/<feature-id>/，并使用相同 manifest。已知 retired ID 会被忽略以迁移旧配置；任意未知 ID 与拼写错误仍会 报错。参阅扩展框架 README和 扩展架构。

更新

deb、RPM 和 pacman 包默认包含 codex-update-manager。其 user service 使用同一签名 APT metadata 检查更新，按 version/architecture/SHA-256 缓存官方包，使用当前启用 扩展在独立 workspace 中重建原生包，并等待受管应用退出后授权包管理器安装。 持久事务用于恢复中断或部分完成的安装；此流程不使用手动生成树重建的目录原子交换。 上一份已管理软件包会保留用于回滚。

codex-update-manager status
codex-update-manager status --json
codex-update-manager check-now
codex-update-manager diagnose
codex-update-manager install-ready
codex-update-manager rollback

systemctl --user enable --now codex-update-manager.service
systemctl --user status codex-update-manager.service
journalctl --user -u codex-update-manager.service

构建不含 updater 的手动更新包：

PACKAGE_WITH_UPDATER=0 make package
make install

AppImage、仓库内生成应用、Nix 和手动更新的 Gentoo 产物不使用此原生包 updater。 参阅更新器。

构建、打包与运行

# 构建本地应用树并直接运行
make build-app
make run-app

# 为当前发行版构建并安装原生包
make package
make install

# 构建指定格式
make deb
make rpm
make pacman
make appimage

构建采用事务方式：候选版本通过验证后才会替换当前应用。启用的 ASAR 扩展 发生 drift 时会拒绝候选版本；未启用扩展不会被探测。依赖、变量、输出布局、 并行构建和 payload 检查见构建与打包。

故障排除

问题	首先检查
官方与 Community 启动互相影响	完全退出所有 ChatGPT 进程；两者共享上游 profile
Flatpak Chrome 能打开 AppImage，但扩展显示 Native transport disconnected	启用 flatpak-chrome-native-messaging；参阅 Flatpak Chrome 设置
迁移后 Browser/Chrome extension 无法连接	完全退出 ChatGPT 与 Chrome，再按故障排除执行窄范围 cache repair
签名或软件包验证失败	检查系统时间、网络、gpgv、architecture 和磁盘空间；有意进行未验证的本地构建时，必须显式传入文档中的开关
应用无法启动	运行 /opt/codex-desktop/start.sh --diagnose
应用使用 XWayland，或需要持久化 Electron 参数	确认为 Wayland 会话时会自动选择原生后端；可用 CODEX_OZONE_PLATFORM=x11|wayland 固定后端，或在 ~/.config/codex-desktop/electron-flags.conf 中每行写一个参数，例如 --ozone-platform=x11
AppImage 报 sandbox 错误	启用 user namespaces 或安装原生包；不会自动添加 --no-sandbox
上游更新后启用扩展发生 drift	禁用该扩展确认 clean baseline，并在 issue 中附上 patch report
updater 等待应用退出	关闭受管应用（默认 /opt/codex-desktop/ChatGPT）；用 codex-update-manager diagnose --json 检查 appExecutable 和 appRunning
旧 codex-app.backup-* 出现权限错误	先确认精确路径，再按 root-owned backup 流程处理；不要盲删 wildcard

完整指南：故障排除。

项目文档

• 入门：原生安装、构建与打包、Nix、Raspberry Pi 5
• 运行与维护：架构、更新器、故障排除
• 扩展：扩展框架、扩展架构、Linux Computer Use、Record and Replay、Chronicle / Skysight
• 贡献：贡献指南、Agent 指令、仓库结构、验证流程、生成与运行时说明
• 项目运维：GitHub CLI 认证、Label 管理

旧 macOS DMG 转换、下载 Electron 替换、原生模块重建、本地 webview server 和 自定义 warm-start 文档不会恢复为当前文档，因为这些 runtime 责任已由官方 Linux 软件包承担。

免责声明

这是一个非官方社区项目，与 OpenAI 没有隶属关系。ChatGPT、OpenAI 服务、 商标、上游应用代码、二进制文件和资产仍归 OpenAI 或各自所有者所有。

本仓库在本地下载并重新打包官方 Linux payload，不授予任何 OpenAI 软件或 服务权利。使用 ChatGPT 仍须遵守 OpenAI 的适用条款和 server-side 功能可用性。

MIT 许可证仅适用于本仓库的 wrapper source、打包、文档和社区扩展。

许可证

MIT