2026/9/17 14:44:19
FEATURED · 精选文章 
Claude Desktop for Linux 发行版重打包指南rpm / AppImage / Nix 格式、Linux 启动器与 --doctor 诊断体系全解析【免费下载链接】claude-desktop-debianClaude Desktop for Linux项目地址: https://gitcode.com/GitHub_Trending/cl/claude-desktop-debian本指南以 README.md 为骨架系统讲解 claude-desktop-debian 项目如何在 Anthropic 官方 Linux.deb基础上为 Fedora/RHEL、NixOS、Arch 等官方未覆盖的发行版提供.rpm、AppImage、Nix flake 等打包产物并深入剖析其 Linux 启动器launcher、--doctor诊断工具、MCP 配置方式以及五枚存活的 asar 补丁。读完你将掌握多格式安装与构建的全部命令、CLAUDE_*环境变量的语义与取舍、Cowork 的 KVM 依赖栈与 bubblewrap 后备方案以及补丁零契约下的代码修改纪律。项目定位官方 .deb 之外的长尾发行版Anthropic 于 2026-06-30 发布了首个第一方 Claude Desktop for Linux beta以.deb格式amd64 与 arm64从其官方 APT 仓库分发。自 v3.0.0 起本项目不再重打包 Windows 安装器而是重打包这份官方 Linux.deb应用本体保持官方字节不变项目只补齐官方未覆盖的发行版、桌面环境与会话类型。从本项目自身的 issue 历史整理的发行版环境调查见 docs/reports/CDL-ANT-0009_patch-suite-history/reported-environments/grouped-families.md。官方.deb只覆盖一个打包目标而项目要服务的是这一长尾外加一个 Linux 启动器和一个--doctor诊断命令。包名上有一个重要约定v3.0.0 起本项目所有产物统一命名为claude-desktop-unofficial可与 Anthropic 官方的claude-desktop并排安装但两者共享~/.config/Claude因此同一时间只能运行其中一个。各格式由谁分发格式分发方.debDebian/Ubuntuamd64 arm64Anthropic 官方 APT 仓库本项目镜像为claude-desktop-unofficial附加启动器与 doctor可与官方包并存.rpmFedora/RHEL本项目AppImage任意发行版本项目AURArch本项目构建 AppImage。自 2026-08-01 起暂不可用见下文Nix flakeNixOS本项目核心特性一览官方应用、额外格式重打包官方 Linux.deb为.rpm、AppImage 与 AUR 构建。MCP 支持完整的 Model Context Protocol 集成配置位于~/.config/Claude/claude_desktop_config.json详见下文 配置 一节。Linux 启动器可选的原生 WaylandCLAUDE_USE_WAYLAND1、GPU 崩溃自动恢复、XRDP 检测、输入法IM模块覆盖、自启动项修复。--doctor诊断检查显示服务器、沙箱权限、MCP 配置、陈旧锁、KVM/Cowork 栈以及官方版本漂移。Cowork on Linux当 KVM硬件虚拟化可用时运行doctor 会报告就绪状态。系统集成X11 与 Wayland 下的全局热键CtrlAltSpace、系统托盘与桌面环境集成。安装指南五种方式使用 APT 仓库Debian/Ubuntu推荐添加仓库即可随系统apt自动更新# 添加 GPG 密钥 curl -fsSL https://pkg.claude-desktop-debian.dev/KEY.gpg | sudo gpg --dearmor -o /usr/share/keyrings/claude-desktop-unofficial.gpg # 添加仓库 echo deb [signed-by/usr/share/keyrings/claude-desktop-unofficial.gpg archamd64,arm64] https://pkg.claude-desktop-debian.dev stable main | sudo tee /etc/apt/sources.list.d/claude-desktop-unofficial.list # 更新并安装 sudo apt update sudo apt install claude-desktop-unofficial后续随常规系统更新自动升级sudo apt upgrade。使用 DNF 仓库Fedora/RHEL推荐# 添加仓库 sudo curl -fsSL https://pkg.claude-desktop-debian.dev/rpm/claude-desktop-unofficial.repo -o /etc/yum.repos.d/claude-desktop-unofficial.repo # 安装 sudo dnf install claude-desktop-unofficial后续随常规系统更新自动升级sudo dnf upgrade。使用 AURArch Linux自 2026-08-01 起暂不可用claude-desktop-appimage因与aur/claude-desktop重复而被删除恢复请求已提交给列表管理员。在恢复之前请直接安装 AppImage见下文。自动发布流水线在请求处理期间暂停被删除的 pkgbase 仍保留 git 仓库且接受推送若在审查中发布会造成包在审查期间被重建。包恢复后执行gh variable set AUR_PUBLISH_ENABLED --body true.github/workflows/ci.yml中的update-aur-repo作业由该变量门控。恢复后安装命令为# 使用 yay yay -S claude-desktop-appimage # 或使用 paru paru -S claude-desktop-appimage使用 Nix FlakeNixOS直接从 flake 安装# 基础安装 nix profile install github:aaddrick/claude-desktop-debian # 带 MCP 服务器支持FHS 环境 nix profile install github:aaddrick/claude-desktop-debian#claude-desktop-fhs或加入 NixOS 配置# flake.nix { inputs.claude-desktop.url github:aaddrick/claude-desktop-debian; outputs { nixpkgs, claude-desktop, ... }: { nixosConfigurations.myhost nixpkgs.lib.nixosSystem { modules [ ({ pkgs, ... }: { nixpkgs.overlays [ claude-desktop.overlays.default ]; environment.systemPackages [ pkgs.claude-desktop ]; }) ]; }; }; }Flake 结构见 flake.nixclaude-desktop基础包与claude-desktop-fhsFHS 环境提供 MCP 运行时依赖与 OVMF 固件是默认输出。claude-desktop-fhs通过nix/fhs.nix派生覆盖 Cowork 硬编码的固件探测路径nix/claude-desktop.nix则用fetchurl从官方 APT 池拉取.deb、以autoPatchelfHook处理裸目录树不引入 nixpkgs 的 Electron。使用预构建发行版从 Releases 页面下载最新的.deb、.rpm或.AppImage即可。注意 AppImage 登录需要正确的桌面集成可使用 Gear Lever 或手动将生成的.desktop文件安装到~/.local/share/applications/。从 GitHub releases 下载的 AppImage 内含更新信息可与 Gear Lever 配合自动更新。从源码构建详细说明见 docs/building.md。构建脚本会自动下载官方.deb、可选地对app.asar打补丁并把官方应用树重打包为.deb、.rpm或 AppImage# 按宿主机发行版自动检测格式 ./build.sh # 或显式指定格式 ./build.sh --build deb ./build.sh --build rpm ./build.sh --build appimage格式自动检测规则Debian/Ubuntu/Mint →debFedora/RHEL/CentOS →rpmNixOS →nix当前为存根其余含 Arch→appimage。构建标志由scripts/setup/detect-host.sh的parse_arguments解析标志默认作用-b,--build自动检测输出格式deb、rpm、appimage或nix-c,--cleanyes打包后清理build/中间文件--clean no保留以供检查-d,--deb下载使用本地下载的官方.deb而非拉取固定版本本地文件跳过 SHA256 固定值校验-a,--archuname -m覆盖目标架构amd64/arm64做交叉构建——重打包与架构无关amd64 主机也能产出 arm64 包-r,--release-tag未设置发布标签如v3.0.0claude1.18286.0提取包装器版本并追加到包版本1.18286.0-3.0.0供 CI 使用-s,--source-dir仓库根为脚本与资源指定仓库根路径支持树外调用--test-flags关闭只解析标志并打印结果后退出不构建构建无需dpkg-deb官方.deb用artar解包因此 rpm 系与 Arch 主机也能构建。各格式依赖见 scripts/setup/dependencies.shasar 补丁阶段要求 Node.js v22.12electron/asar引擎下限。官方 .deb 的解析与固定构建从不抓取下载页而是从 Anthropic 官方 APT 池拉取固定产物scripts/setup/official-deb.sh固定OFFICIAL_DEB_VERSION及每架构的 pool 路径与 SHA256指向https://downloads.claude.ai/claude-desktop/apt/stable。下载后先校验 SHA256 再解包。artar解出data.tar.*与control.tar.*zst/xz/gz 均处理应用树必须落在usr/lib/claude-desktop否则构建以上游布局变化中止。版本从解出的 control 文件读取与固定值不一致仅告警不失败。Depends:与Recommends:从官方 control 文件原样再发射——该契约因架构而异arm64 推荐与 amd64 不同的 qemu 栈原样转发可自动跟随上游。固定值由check-claude-version工作流自动更新轮询官方 APTPackages索引、重写scripts/setup/official-deb.sh中的OFFICIAL_DEB_*固定值、更新仓库版本变量并推送触发发布构建的标签。配置MCP 配置Model Context Protocol 设置存放于~/.config/Claude/claude_desktop_config.json手改此文件前请先退出 Claude Desktop改完再重新打开。应用在运行期间会按自己的节奏重写该配置因此开着应用编辑会被其下一次写入覆盖。启动时已存在的mcpServers条目会被加载并跨重启存活——丢失窗口只发生在针对运行中应用的手工编辑。运行claude-desktop-unofficial --doctor可校验 JSON 并查看已配置的 MCP 服务器数量。其他配置选项含环境变量与 Wayland 支持见 docs/configuration.md。启动器环境变量opt-in 政策自 v3.0.0 重基到官方 Linux 构建后启动器政策为纯 opt-in默认不传递任何会遮蔽官方代码路径的标志窗口框架、标题栏、密码存储、特性开关。每个保留的默认标志都必须能针对具体的 Linux 环境缺口自证合理tools/chromium-switch-smoke.sh守卫会在有效开关列表漂移而未同步基线时响亮失败基线见 tools/chromium-switches.baseline。启动器读取一小撮CLAUDE_*环境变量其余一切——窗口框架、菜单栏、关闭到托盘、硬件加速——都是官方应用的原生设置变量默认说明CLAUDE_USE_WAYLAND未设置自动强制 Wayland 显示后端1 原生 Wayland0 XWayland。未设置时按合成器自动检测只有 Niri 默认原生 WaylandCLAUDE_DISABLE_GPU未设置自动1 禁用硬件加速--disable-gpu0 抑制 GPU 进程崩溃后的粘性自动恢复未设置 上次启动以 GPU FATAL 签名崩溃时自动应用该标志CLAUDE_PASSWORD_STORE未设置显式逃生舱口设置后其值原样作为 Chromium 的--password-store传递未设置时由官方构建的os_crypt自动检测决策CLAUDE_GTK_IM_MODULE未设置启动时传播给 Electron 的GTK_IM_MODULE用于修复损坏的 IBus/GTK 输入法集成的可选覆盖CLAUDE_TRAY_USE_DARK_ICON未设置Cinnamon 上自动1 用上游浅色TrayIconLinux-Dark.png深色面板0 强制深色TrayIconLinux.png未设置由启动器自动检测 Cinnamon 深色面板主题启动器如何把这些变量翻译成 Electron 参数见 scripts/launcher-common.sh 的build_electron_args该函数集中处理--class$WM_CLASS命令行 UI 指纹、XRDP 会话的 GPU 自动关闭、GPU 崩溃粘性恢复、Wayland 后端选择以及仅在设置CLAUDE_PASSWORD_STORE时才追加--password-store。Wayland 支持在 Wayland 会话上启动器按合成器选择显示后端合成器后端原因Niri原生 Wayland自动完全没有 XWayland 支持其余全部GNOME、KDE、Sway、Hyprland、COSMIC…XWayland自动XWayland 全局按键抓取在多数环境仍可用路径成熟、兼容性最广默认只有 Niri 自动选原生 Wayland。GNOME Wayland 默认留在 XWayland尽管 mutter 已不再支持 XWayland 全局按键抓取——把 GNOME 会话默认切出 XWayland 存在渲染/IME/HiDPI 风险故暂保持 opt-in。要让 Quick Entry 的全局快捷键CtrlAltSpace在 GNOME 上走 XDG GlobalShortcuts 门户用CLAUDE_USE_WAYLAND1选原生 WaylandGNOME ≤ 49在一次性的门户权限对话框接受以绑定快捷键后即可工作GNOME 50 / xdg-desktop-portal ≥ 1.20 尚不可用——新版门户要求应用通过org.freedesktop.host.portal.Registry.Register声明身份而 Electron/Chromium 未实现故globalShortcut.register()失败快捷键只能保持焦点绑定。覆盖自动检测# 强制原生 WaylandGNOME 门户路由或 Sway/Hyprland CLAUDE_USE_WAYLAND1 claude-desktop-unofficial # 强制 XWayland例如覆盖 Niri 的自动原生或原生 Wayland 渲染回退 CLAUDE_USE_WAYLAND0 claude-desktop-unofficial # 或持久化任一选择 export CLAUDE_USE_WAYLAND1注意门户路由的全局快捷键只在合成器的门户后端实现了org.freedesktop.portal.GlobalShortcuts时生效。GNOME 与 KDE 已实现自 xdg-desktop-portal 1.21 起对 GlobalShortcuts 强制要求应用 IDKDE 亦然wlroots 系Sway、Hyprland、Niri与 COSMIC 目前没有 GlobalShortcuts 后端门户路由在那里是空操作。从启动器代码看scripts/launcher-common.sh 的detect_display_backendNiri 通过NIRI_SOCKET或XDG_CURRENT_DESKTOP的子串匹配该变量可能是冒号分隔的如niri:GNOME被强制为原生 Wayland。GPUCLAUDE_DISABLE_GPUCLAUDE_DISABLE_GPU1让启动器向官方二进制传递--disable-gpu——与应用内设置里的硬件加速开关等价只是改由环境持久化。变量未设置且上次启动死于 Chromium GPU 进程 FATAL 签名时启动器自动应用同一标志并保持粘性恢复CLAUDE_DISABLE_GPU0可在驱动修复后重测硬件加速时抑制该自动回退。XRDP 会话内也会自动应用该标志。崩溃检测实现在 scripts/launcher-common.sh 的_previous_launch_hit_gpu_fatal单遍、常量内存扫描launcher.log上一节penultimate section的崩溃签名避免 GPU 崩溃循环导致的大日志节被反复重扫的 O(n²) 问题。密码存储CLAUDE_PASSWORD_STORE默认情况下启动器不传--password-store官方构建的os_crypt自动检测拥有钥匙串决策权在部分会话上它会刻意拒绝弱持久化而非不安全地存 token。CLAUDE_PASSWORD_STORE是文档化的逃生舱口设置后其值原样作为--password-storevalue传入并覆盖自动检测CLAUDE_PASSWORD_STOREgnome-libsecret claude-desktop-unofficialdoctor 会报告当前生效的模式Password store: upstream os_crypt autodetect (default)或forced to value。关联的钥匙串检查_doctor_check_keyring_persistence会探测会话总线上的org.freedesktop.secrets/ KWallet当无后端可达时官方os_crypt自动检测会回退到明文basic后端登录 token 以未加密形式存于~/.config/Claude下——这是数据静止的提示登录仍可用永不为 FAIL。输入法CLAUDE_GTK_IM_MODULECLAUDE_GTK_IM_MODULE会在启动时传播给 Electron 的GTK_IM_MODULE从而无需每次启动都包裹命令即可持久化不同的 GTK 输入模块如xim。具体症状与取舍见 docs/troubleshooting.md 的键盘输入一节。doctor 的 IM 模块检查_doctor_check_im_modules会诊断GTK_IM_MODULEibus但ibus-gtk3未安装Arch 的 ibus 主包已含 GTK3 immoduleDebian/Ubuntu/Fedora 需单独安装以及 GTK immodules 缓存过期gtk-query-immodules-3.0未列出活动模块用sudo gtk-query-immodules-3.0 --update-cache修复。托盘图标CLAUDE_TRAY_USE_DARK_ICON上游随包提供两张 Linux 托盘 PNG通常依据 GTK 深色模式状态加 GNOME 检查来选。在 Cinnamon 上深色面板可与浅色 GTK 配色共存于是选错黑色图标。未设置时启动器在 Cinnamon 会话上探测org.cinnamon.theme当主题名像深色面板风格如Mint-Y-Dark-Aqua时置CLAUDE_TRAY_USE_DARK_ICON1。自行设置1或0可强制浅色/深色字形——0连上游的选择也覆盖。其他任何非空值会被应用忽略但会禁用启动器自动检测启动器记录日志、doctor 告警。需要包含patch_tray_icon_env_overrideasar 补丁的构建--doctor会报告当前生效模式。持久化变量environment 配置文件要让变量持久生效——包括从桌面/应用菜单启动无法携带逐命令环境——可写入启动器配置文件# ~/.config/claude-desktop-debian/environment COWORK_VM_BACKENDbwrap启动器在启动时读取${XDG_CONFIG_HOME:-~/.config}/claude-desktop-debian/environment中的KEYvalue行。只认可固定允许清单COWORK_VM_BACKEND、COWORK_NODE_PATH、CLAUDE_USE_WAYLAND、CLAUDE_PASSWORD_STORE、CLAUDE_GTK_IM_MODULE、CLAUDE_DISABLE_GPU、CLAUDE_TRAY_USE_DARK_ICON——且仅在变量未设置时生效因此命令行显式VAR… claude-desktop-unofficial仍优先。该文件从不作为 shell 执行。--doctor也读取它保证诊断与真实启动所见一致。v3.0.0 移除的变量v3.0.0 重基删除了读取以下变量的补丁doctor 的 legacy-environment 检查会在仍设置时告警2.x 变量替代方案CLAUDE_QUIT_ON_CLOSE原生设置设置 通用 系统托盘开 关闭到托盘关 退出CLAUDE_MENU_BAR原生应用设置官方构建默认保持菜单栏开启构建的 MB-1 tripwire 监视上游翻转CLAUDE_TITLEBAR_STYLE无——官方构建自持窗口框架topbar shim 已删除CLAUDE_KEEP_AWAKE无——读取它的补丁随 Windows 流水线一并删除COWORK_VM_BACKEND仍在读取但只认bwrap值进入 bubblewrap 后备其余值忽略应用日志运行时日志位于~/.cache/claude-desktop-debian/launcher.log每次启动还会记录一个env{...}块包含驱动显示与输入决策的会话与CLAUDE_*变量log_session_env覆盖XDG_SESSION_TYPE、WAYLAND_DISPLAY、XDG_CURRENT_DESKTOP、GTK_IM_MODULE等使 bug 报告自带上下文。日志轮转rotate_log_file在超过 5 MiB 时轮转并保留两份旧副本。日志另有隐私保护claude://login/...?codesecret中的授权码会在写入前被脱敏LOG-1 约定。--doctor内置诊断运行claude-desktop-unofficial --doctor获取内置诊断检查常见嫌疑显示服务器、沙箱权限、MCP 配置、陈旧锁等并报告 Cowork 就绪状态。其实现为 scripts/doctor.sh由 scripts/launcher-common.sh 汇入最终被各包格式deb/rpm/AppImage/Nix的启动器脚本引用。核心检查项每项一个_check_*函数_fail计数累加为退出状态显示后端与会话Wayland/X11 检测、IM 模块路由提示Wayland 会话下 Electron 走 XWaylandIBus 经 XIM 有损。沙箱与锁_doctor_check_singleton_lock检查~/.config/Claude/SingletonLock——Chromium 以hostname-PID符号链接写入陈旧锁PID 已死或被回收可被自愈真正阻塞启动的是非符号链接的普通文件异常更新后可能产生此情形必须以 WARN 而非静默 PASS 报告。MCP 配置校验claude_desktop_config.json的 JSON 合法性并统计服务器数。磁盘空间_doctor_check_disk_space检查配置分区剩余空间100 MB FAIL500 MB WARN。钥匙串_secret_backend_reachable探测 Secret Service / KWallet含 D-Bus 可激活名并附数据静止建议。版本漂移_check_official_drift以 curl8 秒超时拉取官方 APTPackages索引比对最新版本离线或池不可达为_info跳过而非失败。名称冲突_check_name_collision区分 Anthropic 官方claude-desktop信息提示共享配置目录、本项目改名前的旧包 1.16000告警迁移等情形。崩溃统计_doctor_check_recent_crashes用coredumpctl统计近 7 天 Electron 崩溃数≥3 提示 GPU 进程 FATAL 工作区。文件名长度限制_doctor_check_filename_limit检测短 NAME_MAX 文件系统eCryptfs 加密家目录 NAME_MAX143导致的 Cowork 会话 ENAMETOOLONG 问题。bwrap 挂载审计_doctor_check_bwrap_mounts解析claude_desktop_linux_config.json中的preferences.coworkBwrapMounts报告只读/读写绑定挂载与禁用的默认挂载并对遮蔽/usr、/etc等沙箱默认挂载的情形告警。Cowork on LinuxKVM 依赖栈默认情况下官方 Linux 客户端把 Cowork 作为驱动 QEMU/KVM 的辅助守护进程运行。默认 KVM 路径在主机上所需的完整组件栈对应 doctor 的_check_cowork_stack各检查组件要求Doctor 检查KVM/dev/kvm存在且可读写否则sudo usermod -aG kvm $USER_check_kvmvsock/dev/vhost-vsock存在sudo modprobe vhost_vsock_check_vhost_vsockQEMUqemu-system-x86_64arm64 为qemu-system-aarch64在PATH上_check_cowork_stack固件OVMF 位于硬编码探测路径之一/usr/share/OVMF/OVMF_CODE_4M.fd或/usr/share/OVMF/OVMF_CODE.fdarm64/usr/share/AAVMF/AAVMF_CODE.fd。无环境变量覆盖——装在 Fedora/Arch edk2 位置的固件缺兼容符号链接就找不到本项目 RPM 包的%post自动创建该链接CW-1_check_cowork_stackvirtiofsd在PATH上或位于知名 off-PATH 位置/usr/libexec/virtiofsd、/usr/lib/qemu/virtiofsd、/usr/lib/virtiofsd_check_cowork_stackdoctor 的 Cowork Mode 区块会逐项报告各组件并给出发行版专属安装提示_cowork_pkg_hint按 Debian/Ubuntu/Fedora/Arch 映射包名与一行就绪摘要。栈缺失不会让 doctor 失败——没有 Cowork 应用也能正常用。值得注意doctor 的_find_virtiofsd刻意比官方客户端的探测仅/usr/libexec与/usr/bin加自带副本更宽用于解释装在某处但客户端不去找的错位。Bubblewrap 后备COWORK_VM_BACKENDbwrap有些主机无论如何安装都无法满足 KVM 栈。最典型的是ChromeOS Crostini其 Termina 内核在命名空间层面封锁vhost_vsock/dev/vhost-vsock缺失且没有标志或modprobe能唤回。这类主机上 KVM Cowork 后端是死路。设置COWORK_VM_BACKENDbwrap可选用 bubblewrap 沙箱后端直接在主机的命名空间沙箱内运行 Claude Code无 VMCOWORK_VM_BACKENDbwrap claude-desktop-unofficial工作原理一个 asar 补丁patch_cowork_bwrap短路 KVM 支持门禁把原生 VM 辅助换成捆绑的 Node 守护进程scripts/cowork-fallback/cowork-vm-service.js它以与官方辅助相同的 socket 协议通信但用bwrap而非 QEMU 作后端。补丁的每个分支都以该精确标志门控未设标志的启动所有分支均为假官方 KVM 路径原样运行——对 KVM 多数用户毫无变化。启用时的要求组件要求Doctor 检查Node.js系统node或nodejs在PATH上且提供fs.statfsSyncNode ≥ 18.15 / 16.19——捆绑的 Electron 二进制 RunAsNode 熔断关闭无法自行运行守护进程。可用COWORK_NODE_PATH覆盖_doctor_check_bwrap_nodebubblewrap安装bwrap且允许非特权用户命名空间Ubuntu 24.04 通过 AppArmor 封锁见 docs/troubleshooting.md_doctor_check_bwrap_fallback带标志运行claude-desktop-unofficial --doctor可见 bwrap 路径的诊断。隔离是命名空间级而非 VM——弱于 KVM 默认这是在 KVM 不可用处运行的取舍。COWORK_VM_BACKEND取bwrap之外的任何值都是 2.x 时代的旋钮官方客户端会忽略。asar 补丁补丁零契约与五枚幸存者应用本体是官方app.asar。补丁必须对照官方字节自证合理否则删除——Anthropic 发布官方 Linux 构建时v3.0.0 之前的大部分补丁套件已被删除。补丁编排见 scripts/patches/app-asar.shactive_patches数组列出仍存活的补丁数组为空时官方app.asar字节级原样交付从不解包重打包。目前五枚 Linux 缺口补丁幸存virtiofsd 解析scripts/patches/virtiofsd-probe.sh上游只探测/usr/libexec/virtiofsd与/usr/bin/virtiofsd仅在/etc/os-release报告 Ubuntu 22.x 时才回退到自带副本。Arch 把 virtiofsd 装在/usr/lib/virtiofsd、Debian 装在/usr/lib/qemu/virtiofsd于是完整的 KVM 栈上 Cowork 却报requires QEMU。去掉 os-release 门禁即修复系统路径仍优先。已上报上游。org-plugins 路径scripts/patches/org-plugins.sh上游平台 switch 只有 darwin 与 win32 分支默认返回 nullorg-plugins 特性在 Linux 上静默失效。补丁加入case linux解析/etc/claude/org-plugins——FHS 合规的 MDM 托管配置路径与 Claude Code 的/etc/claude-code/一致。已上报上游。托盘图标选择scripts/patches/tray-icon-selection.sh上游桌面环境检测器只返回 kde/gnome/otherCinnamon——深色面板配浅色 GTK 配色的典型——会选错字形。补丁把启动器的CLAUDE_TRAY_USE_DARK_ICON穿入上游自己的选择器而不替换其图标。已上报上游。Quick Entry 焦点scripts/patches/quick-window.sh在弹窗hide()前加blur()使提交后主窗口重现绕开 KDE 上的 Electron 焦点 bug。补丁两处独立解析锚点其一重写setAlwaysOnTop(!0, pop-up-menu)调用处的||Var.hide()其二重写 QuickEntry 提交路径的focusCheck()||win.show()——两处均以XDG_CURRENT_DESKTOP含kde门控GNOME 上沿用原逻辑以免回归。Cowork bubblewrap 后端scripts/patches/cowork-bwrap.sh经COWORK_VM_BACKENDbwrapopt-in供无 KVM/vhost-vsock 的主机使用。每个分支都以该标志门控未设标志的启动原样走上游路径。补丁机制的技术细节同样值得了解。自 1.26832.0 起主进程 JS 被拆为 83 个 content-hashed chunkindex.chunk-*与index2.chunk-*不再有单一主 JS 文件因此_resolve_anchor_file让每个补丁用完整锚点形状PCRE自行定位所在文件并要求恰好命中一个文件0 个或多个都是硬错误而非静默错补。锚点须用引号类[]而非裸双引号——1.26832.0 换过压缩器几乎每个字符串字面量都变成了反引号模板。详见 docs/learnings/patching-minified-js.md。两个构建期 tripwire每次构建都会 grep 原始app.asarasar 内容未压缩可直接 grep若上游翻转了被删补丁的行为则响亮失败managed_by_package_managerAU-1Linux 构建的常量折叠更新器提前返回里的遥测原因[updater] Linux: in-app updater off (updates via apt)保证官方自动更新器在 APT 通道就绪期间休眠。若消失说明上游重写了该门禁、可能开启了自更新会与包管理器打架。menuBarEnabled:!0MB-1保持菜单栏开启的设置默认值。若消失说明上游翻转了已删除 menuBar 补丁曾强制执行的默认值。另外两个保障WM_CLASS 从 asar 的package.json的desktopName字段推导_derive_wm_classChromium 从该字段去.desktop后缀派生窗口类而非 ELF 名或--class标志上游已改名过一次claude-desktop.desktop→com.anthropic.Claude.desktop硬编码值会在下次改名时静默破坏窗口分组productName保持Claude被单独 tripwireElectron 的 userData 路径~/.config/Claude依赖它。重打包还精确保留上游的app.asar.unpacked集合集合发散即中止。常见问题与排查先跑claude-desktop-unofficial --doctor走内置诊断见上。卸载指引、日志位置与更多故障处理见 docs/troubleshooting.md。GPU 进程反复崩溃#583 系列应用内 设置 → 关闭硬件加速 → 重启或设CLAUDE_DISABLE_GPU1持久化CLAUDE_DISABLE_GPU0在驱动修复后重测。键盘输入失效IBus/GTK 输入法设CLAUDE_GTK_IM_MODULExim等覆盖或确认ibus-gtk3已装、GTK immodules 缓存未过期。Wayland 快捷键不生效确认合成器门户实现org.freedesktop.portal.GlobalShortcutsGNOME 需CLAUDE_USE_WAYLAND1并接受一次性门户授权GNOME 50 以上暂不支持。手改claude_desktop_config.json被覆盖先退出应用再编辑。Cowork 报 requires QEMU确认 virtiofsd 在PATH或知名 off-PATH 位置Arch/Debian 路径与上游探测不一致时由 virtiofsd 补丁兜底。被删除补丁的完整档案见 docs/reports/CDL-ANT-0009_patch-suite-history 及其 dossiers 目录。其他须知文档入口docs/index.md发布历史见 CHANGELOG.md构建指引见 docs/building.md。许可仓库构建脚本采用 MITLICENSE-MIT与 Apache 2.0LICENSE-APACHE双许可Claude Desktop 应用本体受 Anthropic 消费者条款约束。隐私仓库使用自动 triage 机器人提交 bug 报告或功能请求时会把 issue 内容发往 Anthropic API 做分类与调查。机器人只读 issue 正文、标题及引用的关联 issue不访问 URL、不执行代码块、不读触发 issue 之外的内容。完整设计与数据清单见 docs/issue-triage/README.md。贡献欢迎提交贡献提交即同意以与本项目相同的双许可条款授权见 CONTRIBUTING.md 与 ACKNOWLEDGMENTS.md。【免费下载链接】claude-desktop-debianClaude Desktop for Linux项目地址: https://gitcode.com/GitHub_Trending/cl/claude-desktop-debian创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Claude Desktop for Linux 发行版重打包指南：rpm / AppImage / Nix 格式、Linux 启动器与 --doctor 诊断体系全解析
Claude Desktop for Linux 发行版重打包指南rpm / AppImage / Nix 格式、Linux 启动器与 --doctor 诊断体系全解析【免费下载链接】claude-desktop-debianClaude Desktop for Linux项目地址: https://gitcode.com/GitHub_Trending/cl/claude-desktop-debian本指南以 README.md 为骨架系统讲解 claude-desktop-debian 项目如何在 Anthropic 官方 Linux.deb基础上为 Fedora/RHEL、NixOS、Arch 等官方未覆盖的发行版提供.rpm、AppImage、Nix flake 等打包产物并深入剖析其 Linux 启动器launcher、--doctor诊断工具、MCP 配置方式以及五枚存活的 asar 补丁。读完你将掌握多格式安装与构建的全部命令、CLAUDE_*环境变量的语义与取舍、Cowork 的 KVM 依赖栈与 bubblewrap 后备方案以及补丁零契约下的代码修改纪律。项目定位官方 .deb 之外的长尾发行版Anthropic 于 2026-06-30 发布了首个第一方 Claude Desktop for Linux beta以.deb格式amd64 与 arm64从其官方 APT 仓库分发。自 v3.0.0 起本项目不再重打包 Windows 安装器而是重打包这份官方 Linux.deb应用本体保持官方字节不变项目只补齐官方未覆盖的发行版、桌面环境与会话类型。从本项目自身的 issue 历史整理的发行版环境调查见 docs/reports/CDL-ANT-0009_patch-suite-history/reported-environments/grouped-families.md。官方.deb只覆盖一个打包目标而项目要服务的是这一长尾外加一个 Linux 启动器和一个--doctor诊断命令。包名上有一个重要约定v3.0.0 起本项目所有产物统一命名为claude-desktop-unofficial可与 Anthropic 官方的claude-desktop并排安装但两者共享~/.config/Claude因此同一时间只能运行其中一个。各格式由谁分发格式分发方.debDebian/Ubuntuamd64 arm64Anthropic 官方 APT 仓库本项目镜像为claude-desktop-unofficial附加启动器与 doctor可与官方包并存.rpmFedora/RHEL本项目AppImage任意发行版本项目AURArch本项目构建 AppImage。自 2026-08-01 起暂不可用见下文Nix flakeNixOS本项目核心特性一览官方应用、额外格式重打包官方 Linux.deb为.rpm、AppImage 与 AUR 构建。MCP 支持完整的 Model Context Protocol 集成配置位于~/.config/Claude/claude_desktop_config.json详见下文 配置 一节。Linux 启动器可选的原生 WaylandCLAUDE_USE_WAYLAND1、GPU 崩溃自动恢复、XRDP 检测、输入法IM模块覆盖、自启动项修复。--doctor诊断检查显示服务器、沙箱权限、MCP 配置、陈旧锁、KVM/Cowork 栈以及官方版本漂移。Cowork on Linux当 KVM硬件虚拟化可用时运行doctor 会报告就绪状态。系统集成X11 与 Wayland 下的全局热键CtrlAltSpace、系统托盘与桌面环境集成。安装指南五种方式使用 APT 仓库Debian/Ubuntu推荐添加仓库即可随系统apt自动更新# 添加 GPG 密钥 curl -fsSL https://pkg.claude-desktop-debian.dev/KEY.gpg | sudo gpg --dearmor -o /usr/share/keyrings/claude-desktop-unofficial.gpg # 添加仓库 echo deb [signed-by/usr/share/keyrings/claude-desktop-unofficial.gpg archamd64,arm64] https://pkg.claude-desktop-debian.dev stable main | sudo tee /etc/apt/sources.list.d/claude-desktop-unofficial.list # 更新并安装 sudo apt update sudo apt install claude-desktop-unofficial后续随常规系统更新自动升级sudo apt upgrade。使用 DNF 仓库Fedora/RHEL推荐# 添加仓库 sudo curl -fsSL https://pkg.claude-desktop-debian.dev/rpm/claude-desktop-unofficial.repo -o /etc/yum.repos.d/claude-desktop-unofficial.repo # 安装 sudo dnf install claude-desktop-unofficial后续随常规系统更新自动升级sudo dnf upgrade。使用 AURArch Linux自 2026-08-01 起暂不可用claude-desktop-appimage因与aur/claude-desktop重复而被删除恢复请求已提交给列表管理员。在恢复之前请直接安装 AppImage见下文。自动发布流水线在请求处理期间暂停被删除的 pkgbase 仍保留 git 仓库且接受推送若在审查中发布会造成包在审查期间被重建。包恢复后执行gh variable set AUR_PUBLISH_ENABLED --body true.github/workflows/ci.yml中的update-aur-repo作业由该变量门控。恢复后安装命令为# 使用 yay yay -S claude-desktop-appimage # 或使用 paru paru -S claude-desktop-appimage使用 Nix FlakeNixOS直接从 flake 安装# 基础安装 nix profile install github:aaddrick/claude-desktop-debian # 带 MCP 服务器支持FHS 环境 nix profile install github:aaddrick/claude-desktop-debian#claude-desktop-fhs或加入 NixOS 配置# flake.nix { inputs.claude-desktop.url github:aaddrick/claude-desktop-debian; outputs { nixpkgs, claude-desktop, ... }: { nixosConfigurations.myhost nixpkgs.lib.nixosSystem { modules [ ({ pkgs, ... }: { nixpkgs.overlays [ claude-desktop.overlays.default ]; environment.systemPackages [ pkgs.claude-desktop ]; }) ]; }; }; }Flake 结构见 flake.nixclaude-desktop基础包与claude-desktop-fhsFHS 环境提供 MCP 运行时依赖与 OVMF 固件是默认输出。claude-desktop-fhs通过nix/fhs.nix派生覆盖 Cowork 硬编码的固件探测路径nix/claude-desktop.nix则用fetchurl从官方 APT 池拉取.deb、以autoPatchelfHook处理裸目录树不引入 nixpkgs 的 Electron。使用预构建发行版从 Releases 页面下载最新的.deb、.rpm或.AppImage即可。注意 AppImage 登录需要正确的桌面集成可使用 Gear Lever 或手动将生成的.desktop文件安装到~/.local/share/applications/。从 GitHub releases 下载的 AppImage 内含更新信息可与 Gear Lever 配合自动更新。从源码构建详细说明见 docs/building.md。构建脚本会自动下载官方.deb、可选地对app.asar打补丁并把官方应用树重打包为.deb、.rpm或 AppImage# 按宿主机发行版自动检测格式 ./build.sh # 或显式指定格式 ./build.sh --build deb ./build.sh --build rpm ./build.sh --build appimage格式自动检测规则Debian/Ubuntu/Mint →debFedora/RHEL/CentOS →rpmNixOS →nix当前为存根其余含 Arch→appimage。构建标志由scripts/setup/detect-host.sh的parse_arguments解析标志默认作用-b,--build自动检测输出格式deb、rpm、appimage或nix-c,--cleanyes打包后清理build/中间文件--clean no保留以供检查-d,--deb下载使用本地下载的官方.deb而非拉取固定版本本地文件跳过 SHA256 固定值校验-a,--archuname -m覆盖目标架构amd64/arm64做交叉构建——重打包与架构无关amd64 主机也能产出 arm64 包-r,--release-tag未设置发布标签如v3.0.0claude1.18286.0提取包装器版本并追加到包版本1.18286.0-3.0.0供 CI 使用-s,--source-dir仓库根为脚本与资源指定仓库根路径支持树外调用--test-flags关闭只解析标志并打印结果后退出不构建构建无需dpkg-deb官方.deb用artar解包因此 rpm 系与 Arch 主机也能构建。各格式依赖见 scripts/setup/dependencies.shasar 补丁阶段要求 Node.js v22.12electron/asar引擎下限。官方 .deb 的解析与固定构建从不抓取下载页而是从 Anthropic 官方 APT 池拉取固定产物scripts/setup/official-deb.sh固定OFFICIAL_DEB_VERSION及每架构的 pool 路径与 SHA256指向https://downloads.claude.ai/claude-desktop/apt/stable。下载后先校验 SHA256 再解包。artar解出data.tar.*与control.tar.*zst/xz/gz 均处理应用树必须落在usr/lib/claude-desktop否则构建以上游布局变化中止。版本从解出的 control 文件读取与固定值不一致仅告警不失败。Depends:与Recommends:从官方 control 文件原样再发射——该契约因架构而异arm64 推荐与 amd64 不同的 qemu 栈原样转发可自动跟随上游。固定值由check-claude-version工作流自动更新轮询官方 APTPackages索引、重写scripts/setup/official-deb.sh中的OFFICIAL_DEB_*固定值、更新仓库版本变量并推送触发发布构建的标签。配置MCP 配置Model Context Protocol 设置存放于~/.config/Claude/claude_desktop_config.json手改此文件前请先退出 Claude Desktop改完再重新打开。应用在运行期间会按自己的节奏重写该配置因此开着应用编辑会被其下一次写入覆盖。启动时已存在的mcpServers条目会被加载并跨重启存活——丢失窗口只发生在针对运行中应用的手工编辑。运行claude-desktop-unofficial --doctor可校验 JSON 并查看已配置的 MCP 服务器数量。其他配置选项含环境变量与 Wayland 支持见 docs/configuration.md。启动器环境变量opt-in 政策自 v3.0.0 重基到官方 Linux 构建后启动器政策为纯 opt-in默认不传递任何会遮蔽官方代码路径的标志窗口框架、标题栏、密码存储、特性开关。每个保留的默认标志都必须能针对具体的 Linux 环境缺口自证合理tools/chromium-switch-smoke.sh守卫会在有效开关列表漂移而未同步基线时响亮失败基线见 tools/chromium-switches.baseline。启动器读取一小撮CLAUDE_*环境变量其余一切——窗口框架、菜单栏、关闭到托盘、硬件加速——都是官方应用的原生设置变量默认说明CLAUDE_USE_WAYLAND未设置自动强制 Wayland 显示后端1 原生 Wayland0 XWayland。未设置时按合成器自动检测只有 Niri 默认原生 WaylandCLAUDE_DISABLE_GPU未设置自动1 禁用硬件加速--disable-gpu0 抑制 GPU 进程崩溃后的粘性自动恢复未设置 上次启动以 GPU FATAL 签名崩溃时自动应用该标志CLAUDE_PASSWORD_STORE未设置显式逃生舱口设置后其值原样作为 Chromium 的--password-store传递未设置时由官方构建的os_crypt自动检测决策CLAUDE_GTK_IM_MODULE未设置启动时传播给 Electron 的GTK_IM_MODULE用于修复损坏的 IBus/GTK 输入法集成的可选覆盖CLAUDE_TRAY_USE_DARK_ICON未设置Cinnamon 上自动1 用上游浅色TrayIconLinux-Dark.png深色面板0 强制深色TrayIconLinux.png未设置由启动器自动检测 Cinnamon 深色面板主题启动器如何把这些变量翻译成 Electron 参数见 scripts/launcher-common.sh 的build_electron_args该函数集中处理--class$WM_CLASS命令行 UI 指纹、XRDP 会话的 GPU 自动关闭、GPU 崩溃粘性恢复、Wayland 后端选择以及仅在设置CLAUDE_PASSWORD_STORE时才追加--password-store。Wayland 支持在 Wayland 会话上启动器按合成器选择显示后端合成器后端原因Niri原生 Wayland自动完全没有 XWayland 支持其余全部GNOME、KDE、Sway、Hyprland、COSMIC…XWayland自动XWayland 全局按键抓取在多数环境仍可用路径成熟、兼容性最广默认只有 Niri 自动选原生 Wayland。GNOME Wayland 默认留在 XWayland尽管 mutter 已不再支持 XWayland 全局按键抓取——把 GNOME 会话默认切出 XWayland 存在渲染/IME/HiDPI 风险故暂保持 opt-in。要让 Quick Entry 的全局快捷键CtrlAltSpace在 GNOME 上走 XDG GlobalShortcuts 门户用CLAUDE_USE_WAYLAND1选原生 WaylandGNOME ≤ 49在一次性的门户权限对话框接受以绑定快捷键后即可工作GNOME 50 / xdg-desktop-portal ≥ 1.20 尚不可用——新版门户要求应用通过org.freedesktop.host.portal.Registry.Register声明身份而 Electron/Chromium 未实现故globalShortcut.register()失败快捷键只能保持焦点绑定。覆盖自动检测# 强制原生 WaylandGNOME 门户路由或 Sway/Hyprland CLAUDE_USE_WAYLAND1 claude-desktop-unofficial # 强制 XWayland例如覆盖 Niri 的自动原生或原生 Wayland 渲染回退 CLAUDE_USE_WAYLAND0 claude-desktop-unofficial # 或持久化任一选择 export CLAUDE_USE_WAYLAND1注意门户路由的全局快捷键只在合成器的门户后端实现了org.freedesktop.portal.GlobalShortcuts时生效。GNOME 与 KDE 已实现自 xdg-desktop-portal 1.21 起对 GlobalShortcuts 强制要求应用 IDKDE 亦然wlroots 系Sway、Hyprland、Niri与 COSMIC 目前没有 GlobalShortcuts 后端门户路由在那里是空操作。从启动器代码看scripts/launcher-common.sh 的detect_display_backendNiri 通过NIRI_SOCKET或XDG_CURRENT_DESKTOP的子串匹配该变量可能是冒号分隔的如niri:GNOME被强制为原生 Wayland。GPUCLAUDE_DISABLE_GPUCLAUDE_DISABLE_GPU1让启动器向官方二进制传递--disable-gpu——与应用内设置里的硬件加速开关等价只是改由环境持久化。变量未设置且上次启动死于 Chromium GPU 进程 FATAL 签名时启动器自动应用同一标志并保持粘性恢复CLAUDE_DISABLE_GPU0可在驱动修复后重测硬件加速时抑制该自动回退。XRDP 会话内也会自动应用该标志。崩溃检测实现在 scripts/launcher-common.sh 的_previous_launch_hit_gpu_fatal单遍、常量内存扫描launcher.log上一节penultimate section的崩溃签名避免 GPU 崩溃循环导致的大日志节被反复重扫的 O(n²) 问题。密码存储CLAUDE_PASSWORD_STORE默认情况下启动器不传--password-store官方构建的os_crypt自动检测拥有钥匙串决策权在部分会话上它会刻意拒绝弱持久化而非不安全地存 token。CLAUDE_PASSWORD_STORE是文档化的逃生舱口设置后其值原样作为--password-storevalue传入并覆盖自动检测CLAUDE_PASSWORD_STOREgnome-libsecret claude-desktop-unofficialdoctor 会报告当前生效的模式Password store: upstream os_crypt autodetect (default)或forced to value。关联的钥匙串检查_doctor_check_keyring_persistence会探测会话总线上的org.freedesktop.secrets/ KWallet当无后端可达时官方os_crypt自动检测会回退到明文basic后端登录 token 以未加密形式存于~/.config/Claude下——这是数据静止的提示登录仍可用永不为 FAIL。输入法CLAUDE_GTK_IM_MODULECLAUDE_GTK_IM_MODULE会在启动时传播给 Electron 的GTK_IM_MODULE从而无需每次启动都包裹命令即可持久化不同的 GTK 输入模块如xim。具体症状与取舍见 docs/troubleshooting.md 的键盘输入一节。doctor 的 IM 模块检查_doctor_check_im_modules会诊断GTK_IM_MODULEibus但ibus-gtk3未安装Arch 的 ibus 主包已含 GTK3 immoduleDebian/Ubuntu/Fedora 需单独安装以及 GTK immodules 缓存过期gtk-query-immodules-3.0未列出活动模块用sudo gtk-query-immodules-3.0 --update-cache修复。托盘图标CLAUDE_TRAY_USE_DARK_ICON上游随包提供两张 Linux 托盘 PNG通常依据 GTK 深色模式状态加 GNOME 检查来选。在 Cinnamon 上深色面板可与浅色 GTK 配色共存于是选错黑色图标。未设置时启动器在 Cinnamon 会话上探测org.cinnamon.theme当主题名像深色面板风格如Mint-Y-Dark-Aqua时置CLAUDE_TRAY_USE_DARK_ICON1。自行设置1或0可强制浅色/深色字形——0连上游的选择也覆盖。其他任何非空值会被应用忽略但会禁用启动器自动检测启动器记录日志、doctor 告警。需要包含patch_tray_icon_env_overrideasar 补丁的构建--doctor会报告当前生效模式。持久化变量environment 配置文件要让变量持久生效——包括从桌面/应用菜单启动无法携带逐命令环境——可写入启动器配置文件# ~/.config/claude-desktop-debian/environment COWORK_VM_BACKENDbwrap启动器在启动时读取${XDG_CONFIG_HOME:-~/.config}/claude-desktop-debian/environment中的KEYvalue行。只认可固定允许清单COWORK_VM_BACKEND、COWORK_NODE_PATH、CLAUDE_USE_WAYLAND、CLAUDE_PASSWORD_STORE、CLAUDE_GTK_IM_MODULE、CLAUDE_DISABLE_GPU、CLAUDE_TRAY_USE_DARK_ICON——且仅在变量未设置时生效因此命令行显式VAR… claude-desktop-unofficial仍优先。该文件从不作为 shell 执行。--doctor也读取它保证诊断与真实启动所见一致。v3.0.0 移除的变量v3.0.0 重基删除了读取以下变量的补丁doctor 的 legacy-environment 检查会在仍设置时告警2.x 变量替代方案CLAUDE_QUIT_ON_CLOSE原生设置设置 通用 系统托盘开 关闭到托盘关 退出CLAUDE_MENU_BAR原生应用设置官方构建默认保持菜单栏开启构建的 MB-1 tripwire 监视上游翻转CLAUDE_TITLEBAR_STYLE无——官方构建自持窗口框架topbar shim 已删除CLAUDE_KEEP_AWAKE无——读取它的补丁随 Windows 流水线一并删除COWORK_VM_BACKEND仍在读取但只认bwrap值进入 bubblewrap 后备其余值忽略应用日志运行时日志位于~/.cache/claude-desktop-debian/launcher.log每次启动还会记录一个env{...}块包含驱动显示与输入决策的会话与CLAUDE_*变量log_session_env覆盖XDG_SESSION_TYPE、WAYLAND_DISPLAY、XDG_CURRENT_DESKTOP、GTK_IM_MODULE等使 bug 报告自带上下文。日志轮转rotate_log_file在超过 5 MiB 时轮转并保留两份旧副本。日志另有隐私保护claude://login/...?codesecret中的授权码会在写入前被脱敏LOG-1 约定。--doctor内置诊断运行claude-desktop-unofficial --doctor获取内置诊断检查常见嫌疑显示服务器、沙箱权限、MCP 配置、陈旧锁等并报告 Cowork 就绪状态。其实现为 scripts/doctor.sh由 scripts/launcher-common.sh 汇入最终被各包格式deb/rpm/AppImage/Nix的启动器脚本引用。核心检查项每项一个_check_*函数_fail计数累加为退出状态显示后端与会话Wayland/X11 检测、IM 模块路由提示Wayland 会话下 Electron 走 XWaylandIBus 经 XIM 有损。沙箱与锁_doctor_check_singleton_lock检查~/.config/Claude/SingletonLock——Chromium 以hostname-PID符号链接写入陈旧锁PID 已死或被回收可被自愈真正阻塞启动的是非符号链接的普通文件异常更新后可能产生此情形必须以 WARN 而非静默 PASS 报告。MCP 配置校验claude_desktop_config.json的 JSON 合法性并统计服务器数。磁盘空间_doctor_check_disk_space检查配置分区剩余空间100 MB FAIL500 MB WARN。钥匙串_secret_backend_reachable探测 Secret Service / KWallet含 D-Bus 可激活名并附数据静止建议。版本漂移_check_official_drift以 curl8 秒超时拉取官方 APTPackages索引比对最新版本离线或池不可达为_info跳过而非失败。名称冲突_check_name_collision区分 Anthropic 官方claude-desktop信息提示共享配置目录、本项目改名前的旧包 1.16000告警迁移等情形。崩溃统计_doctor_check_recent_crashes用coredumpctl统计近 7 天 Electron 崩溃数≥3 提示 GPU 进程 FATAL 工作区。文件名长度限制_doctor_check_filename_limit检测短 NAME_MAX 文件系统eCryptfs 加密家目录 NAME_MAX143导致的 Cowork 会话 ENAMETOOLONG 问题。bwrap 挂载审计_doctor_check_bwrap_mounts解析claude_desktop_linux_config.json中的preferences.coworkBwrapMounts报告只读/读写绑定挂载与禁用的默认挂载并对遮蔽/usr、/etc等沙箱默认挂载的情形告警。Cowork on LinuxKVM 依赖栈默认情况下官方 Linux 客户端把 Cowork 作为驱动 QEMU/KVM 的辅助守护进程运行。默认 KVM 路径在主机上所需的完整组件栈对应 doctor 的_check_cowork_stack各检查组件要求Doctor 检查KVM/dev/kvm存在且可读写否则sudo usermod -aG kvm $USER_check_kvmvsock/dev/vhost-vsock存在sudo modprobe vhost_vsock_check_vhost_vsockQEMUqemu-system-x86_64arm64 为qemu-system-aarch64在PATH上_check_cowork_stack固件OVMF 位于硬编码探测路径之一/usr/share/OVMF/OVMF_CODE_4M.fd或/usr/share/OVMF/OVMF_CODE.fdarm64/usr/share/AAVMF/AAVMF_CODE.fd。无环境变量覆盖——装在 Fedora/Arch edk2 位置的固件缺兼容符号链接就找不到本项目 RPM 包的%post自动创建该链接CW-1_check_cowork_stackvirtiofsd在PATH上或位于知名 off-PATH 位置/usr/libexec/virtiofsd、/usr/lib/qemu/virtiofsd、/usr/lib/virtiofsd_check_cowork_stackdoctor 的 Cowork Mode 区块会逐项报告各组件并给出发行版专属安装提示_cowork_pkg_hint按 Debian/Ubuntu/Fedora/Arch 映射包名与一行就绪摘要。栈缺失不会让 doctor 失败——没有 Cowork 应用也能正常用。值得注意doctor 的_find_virtiofsd刻意比官方客户端的探测仅/usr/libexec与/usr/bin加自带副本更宽用于解释装在某处但客户端不去找的错位。Bubblewrap 后备COWORK_VM_BACKENDbwrap有些主机无论如何安装都无法满足 KVM 栈。最典型的是ChromeOS Crostini其 Termina 内核在命名空间层面封锁vhost_vsock/dev/vhost-vsock缺失且没有标志或modprobe能唤回。这类主机上 KVM Cowork 后端是死路。设置COWORK_VM_BACKENDbwrap可选用 bubblewrap 沙箱后端直接在主机的命名空间沙箱内运行 Claude Code无 VMCOWORK_VM_BACKENDbwrap claude-desktop-unofficial工作原理一个 asar 补丁patch_cowork_bwrap短路 KVM 支持门禁把原生 VM 辅助换成捆绑的 Node 守护进程scripts/cowork-fallback/cowork-vm-service.js它以与官方辅助相同的 socket 协议通信但用bwrap而非 QEMU 作后端。补丁的每个分支都以该精确标志门控未设标志的启动所有分支均为假官方 KVM 路径原样运行——对 KVM 多数用户毫无变化。启用时的要求组件要求Doctor 检查Node.js系统node或nodejs在PATH上且提供fs.statfsSyncNode ≥ 18.15 / 16.19——捆绑的 Electron 二进制 RunAsNode 熔断关闭无法自行运行守护进程。可用COWORK_NODE_PATH覆盖_doctor_check_bwrap_nodebubblewrap安装bwrap且允许非特权用户命名空间Ubuntu 24.04 通过 AppArmor 封锁见 docs/troubleshooting.md_doctor_check_bwrap_fallback带标志运行claude-desktop-unofficial --doctor可见 bwrap 路径的诊断。隔离是命名空间级而非 VM——弱于 KVM 默认这是在 KVM 不可用处运行的取舍。COWORK_VM_BACKEND取bwrap之外的任何值都是 2.x 时代的旋钮官方客户端会忽略。asar 补丁补丁零契约与五枚幸存者应用本体是官方app.asar。补丁必须对照官方字节自证合理否则删除——Anthropic 发布官方 Linux 构建时v3.0.0 之前的大部分补丁套件已被删除。补丁编排见 scripts/patches/app-asar.shactive_patches数组列出仍存活的补丁数组为空时官方app.asar字节级原样交付从不解包重打包。目前五枚 Linux 缺口补丁幸存virtiofsd 解析scripts/patches/virtiofsd-probe.sh上游只探测/usr/libexec/virtiofsd与/usr/bin/virtiofsd仅在/etc/os-release报告 Ubuntu 22.x 时才回退到自带副本。Arch 把 virtiofsd 装在/usr/lib/virtiofsd、Debian 装在/usr/lib/qemu/virtiofsd于是完整的 KVM 栈上 Cowork 却报requires QEMU。去掉 os-release 门禁即修复系统路径仍优先。已上报上游。org-plugins 路径scripts/patches/org-plugins.sh上游平台 switch 只有 darwin 与 win32 分支默认返回 nullorg-plugins 特性在 Linux 上静默失效。补丁加入case linux解析/etc/claude/org-plugins——FHS 合规的 MDM 托管配置路径与 Claude Code 的/etc/claude-code/一致。已上报上游。托盘图标选择scripts/patches/tray-icon-selection.sh上游桌面环境检测器只返回 kde/gnome/otherCinnamon——深色面板配浅色 GTK 配色的典型——会选错字形。补丁把启动器的CLAUDE_TRAY_USE_DARK_ICON穿入上游自己的选择器而不替换其图标。已上报上游。Quick Entry 焦点scripts/patches/quick-window.sh在弹窗hide()前加blur()使提交后主窗口重现绕开 KDE 上的 Electron 焦点 bug。补丁两处独立解析锚点其一重写setAlwaysOnTop(!0, pop-up-menu)调用处的||Var.hide()其二重写 QuickEntry 提交路径的focusCheck()||win.show()——两处均以XDG_CURRENT_DESKTOP含kde门控GNOME 上沿用原逻辑以免回归。Cowork bubblewrap 后端scripts/patches/cowork-bwrap.sh经COWORK_VM_BACKENDbwrapopt-in供无 KVM/vhost-vsock 的主机使用。每个分支都以该标志门控未设标志的启动原样走上游路径。补丁机制的技术细节同样值得了解。自 1.26832.0 起主进程 JS 被拆为 83 个 content-hashed chunkindex.chunk-*与index2.chunk-*不再有单一主 JS 文件因此_resolve_anchor_file让每个补丁用完整锚点形状PCRE自行定位所在文件并要求恰好命中一个文件0 个或多个都是硬错误而非静默错补。锚点须用引号类[]而非裸双引号——1.26832.0 换过压缩器几乎每个字符串字面量都变成了反引号模板。详见 docs/learnings/patching-minified-js.md。两个构建期 tripwire每次构建都会 grep 原始app.asarasar 内容未压缩可直接 grep若上游翻转了被删补丁的行为则响亮失败managed_by_package_managerAU-1Linux 构建的常量折叠更新器提前返回里的遥测原因[updater] Linux: in-app updater off (updates via apt)保证官方自动更新器在 APT 通道就绪期间休眠。若消失说明上游重写了该门禁、可能开启了自更新会与包管理器打架。menuBarEnabled:!0MB-1保持菜单栏开启的设置默认值。若消失说明上游翻转了已删除 menuBar 补丁曾强制执行的默认值。另外两个保障WM_CLASS 从 asar 的package.json的desktopName字段推导_derive_wm_classChromium 从该字段去.desktop后缀派生窗口类而非 ELF 名或--class标志上游已改名过一次claude-desktop.desktop→com.anthropic.Claude.desktop硬编码值会在下次改名时静默破坏窗口分组productName保持Claude被单独 tripwireElectron 的 userData 路径~/.config/Claude依赖它。重打包还精确保留上游的app.asar.unpacked集合集合发散即中止。常见问题与排查先跑claude-desktop-unofficial --doctor走内置诊断见上。卸载指引、日志位置与更多故障处理见 docs/troubleshooting.md。GPU 进程反复崩溃#583 系列应用内 设置 → 关闭硬件加速 → 重启或设CLAUDE_DISABLE_GPU1持久化CLAUDE_DISABLE_GPU0在驱动修复后重测。键盘输入失效IBus/GTK 输入法设CLAUDE_GTK_IM_MODULExim等覆盖或确认ibus-gtk3已装、GTK immodules 缓存未过期。Wayland 快捷键不生效确认合成器门户实现org.freedesktop.portal.GlobalShortcutsGNOME 需CLAUDE_USE_WAYLAND1并接受一次性门户授权GNOME 50 以上暂不支持。手改claude_desktop_config.json被覆盖先退出应用再编辑。Cowork 报 requires QEMU确认 virtiofsd 在PATH或知名 off-PATH 位置Arch/Debian 路径与上游探测不一致时由 virtiofsd 补丁兜底。被删除补丁的完整档案见 docs/reports/CDL-ANT-0009_patch-suite-history 及其 dossiers 目录。其他须知文档入口docs/index.md发布历史见 CHANGELOG.md构建指引见 docs/building.md。许可仓库构建脚本采用 MITLICENSE-MIT与 Apache 2.0LICENSE-APACHE双许可Claude Desktop 应用本体受 Anthropic 消费者条款约束。隐私仓库使用自动 triage 机器人提交 bug 报告或功能请求时会把 issue 内容发往 Anthropic API 做分类与调查。机器人只读 issue 正文、标题及引用的关联 issue不访问 URL、不执行代码块、不读触发 issue 之外的内容。完整设计与数据清单见 docs/issue-triage/README.md。贡献欢迎提交贡献提交即同意以与本项目相同的双许可条款授权见 CONTRIBUTING.md 与 ACKNOWLEDGMENTS.md。【免费下载链接】claude-desktop-debianClaude Desktop for Linux项目地址: https://gitcode.com/GitHub_Trending/cl/claude-desktop-debian创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
