Claude Desktop for Linux

本项目提供构建脚本，可在 Linux 系统上原生运行 Claude Desktop。它将官方 Windows 应用程序重新打包为适用于 Linux 发行版的软件包，生成 .deb 包（Debian/Ubuntu）、.rpm 包（Fedora/RHEL）、与发行版无关的 AppImage、一个用于 Arch Linux 的 AUR 软件包，以及一个用于 NixOS 的 Nix Flake。

注意： 这是一个非官方的构建脚本。如需官方支持，请访问 Anthropic 官网。如遇到构建脚本或 Linux 实现方面的问题，请在此仓库中提交问题。

---

⚠️ 实验性功能：协作模式支持

本构建版本默认启用协作模式，并采用可插拔的隔离后端：

后端	隔离方式	要求
bubblewrap（默认）	命名空间沙箱	已安装且可用的 bwrap
host（回退）	无 — 直接在主机上运行	无额外要求

启动时会自动检测并选择最佳可用后端。运行 claude-desktop --doctor 可检查将使用哪个后端以及缺少哪些依赖项。

注意： bubblewrap 后端会将您的主目录挂载为只读（仅项目工作目录可写）。host 后端不提供任何隔离——请仅在充分了解其安全影响的情况下使用。

KVM 状态： KVM/QEMU 后端代码已存在，但目前无法正常工作——为避免校验和循环问题，Linux 上已禁用虚拟机文件下载（#337）。该后端代码仍保留，以备未来可能使用。

---

功能特性

• 原生 Linux 支持：无需虚拟化或 Wine 即可运行 Claude Desktop
• MCP 支持：完整集成模型上下文协议 配置文件位置：~/.config/Claude/claude_desktop_config.json
• 系统集成：
  • 全局热键支持（Ctrl+Alt+Space）——在 X11 和 Wayland（通过 XWayland）下均可用
  • 系统托盘集成
  • 桌面环境集成

截图

安装方法

使用 APT 仓库（推荐：Debian/Ubuntu）

添加仓库以便通过 apt 自动更新：

# 添加 GPG 密钥
curl -fsSL https://aaddrick.github.io/claude-desktop-debian/KEY.gpg | sudo gpg --dearmor -o /usr/share/keyrings/claude-desktop.gpg

# 添加仓库
echo "deb [signed-by=/usr/share/keyrings/claude-desktop.gpg arch=amd64,arm64] https://aaddrick.github.io/claude-desktop-debian stable main" | sudo tee /etc/apt/sources.list.d/claude-desktop.list

# 更新并安装
sudo apt update
sudo apt install claude-desktop

未来的更新将随您常规的系统更新（sudo apt upgrade）自动安装。

使用 DNF 仓库（推荐：Fedora/RHEL）

添加仓库以便通过 dnf 自动更新：

# 添加仓库
sudo curl -fsSL https://aaddrick.github.io/claude-desktop-debian/rpm/claude-desktop.repo -o /etc/yum.repos.d/claude-desktop.repo

# 安装
sudo dnf install claude-desktop

未来的更新也将随您常规的系统更新（sudo dnf upgrade）自动安装。

使用 AUR（Arch Linux）

AUR 中提供了 claude-desktop-appimage 软件包，每次发布时都会自动更新。

# 使用 yay
yay -S claude-desktop-appimage

# 或使用 paru
paru -S claude-desktop-appimage

该 AUR 软件包会安装 Claude Desktop 的 AppImage 版本。

使用 Nix Flake（NixOS）

可以直接从 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 ];
        })
      ];
    };
  };
}

使用预编译的发布包

从 Releases 页面下载最新的 .deb、.rpm 或 .AppImage 文件。

从源码构建

详细构建步骤请参阅 docs/BUILDING.md。

配置

模型上下文协议的设置存储于：

~/.config/Claude/claude_desktop_config.json

有关包括环境变量和 Wayland 支持在内的更多配置选项，请参阅 docs/CONFIGURATION.md。

故障排除

运行 claude-desktop --doctor 可执行内置诊断，检查常见问题（显示服务器、沙箱权限、MCP 配置、过期锁等）。它还会报告协作模式的准备情况——将使用哪种隔离后端，以及哪些依赖项（KVM、QEMU、vsock、socat、virtiofsd、bubblewrap）已安装或缺失。

有关更多故障排除信息、卸载说明及日志位置，请参阅 docs/TROUBLESHOOTING.md。

致谢

本项目受到 k3d3 的 claude-desktop-linux-flake 以及他们关于在 Linux 上原生运行 Claude Desktop 的 Reddit 帖子 的启发。

特别感谢：

• k3d3 提供了最初的 NixOS 实现和原生绑定方面的见解
• emsi 修复了标题栏问题并提出了替代实现方案
• leobuskin 采用了基于 Playwright 的 URL 解析方法
• yarikoptic 支持 codespell 检查和 shellcheck 规范
• IamGianluca 改进了构建依赖检查
• ing03201 添加了 IBus/Fcitx5 输入法支持
• ajescudero 锁定了 @electron/asar 以确保与 Node.js 兼容
• delorenj 提供了 Wayland 兼容性支持
• Regen-forest 建议使用 Gear Lever 替代 AppImageLauncher
• niekvugteveen 修复了 Debian 打包权限问题
• speleoalex 支持原生窗口装饰
• imaginalnika 将日志移动到 ~/.cache/
• richardspicer 修复了 Linux 上菜单栏的可见性问题
• jacobfrantz1 支持 Claude Desktop 代码预览，并修复了快速提交窗口的问题
• janfrederik 添加了 --exe 标志，以便使用本地安装程序
• MrEdwards007 发现了 OAuth 令牌缓存的修复方法
• lizthegrey 贡献了版本更新内容
• mathys-lopinto 创建了 AUR 包并实现了自动化部署
• pkuijpers 分析了 RPM 仓库 GPG 签名问题的根本原因
• dlepold 识别并修复了托盘图标变量名错误
• Voork1144 对托盘图标压缩工具中的错误进行了详细分析，找到了 Chromium 布局缓存错误的根本原因，并提出了直接调用 setBounds() 方法来解决问题
• sabiut 添加了 --doctor 诊断命令，并对下载文件进行 SHA-256 校验
• milog1994 改进了 Linux 用户体验，包括弹出窗口检测、功能桩代码以及 Wayland 合成器支持
• jarrodcolburn 在容器/CI 环境中支持无密码 sudo，发现了 gh-pages 4GB 冗余的修复方法，识别了 Debian 上 virtiofsd PATH 检测问题，详细分析了 CI 发布流水线因 runner 被终止而导致 compare-releases 失败的原因，并提出了三种解决会话启动钩子阻止 sudo 的方案
• chukfinley 在 Linux 上实验性地支持 Cowork 模式
• CyPack 在启动时清理了孤立的 cowork 守护进程
• IliyaBrook 修复了 Claude Desktop >= 1.1.3541 arm64 架构的平台补丁重构问题
• MichaelMKenny 诊断了以 $ 开头的 electron 变量错误，并给出了根本原因分析及 workaround
• daa25209 对 cowork 平台闸门崩溃问题及其补丁脚本进行了详细的根因分析
• noctuum 引入了 CLAUDE_MENU_BAR 环境变量，支持可配置的菜单栏可见性和布尔别名
• typedrat 将 NixOS flake 与 build.sh 集成，添加了 node-pty 衍生、CI 自动更新功能，并修复了 flake 包作用域回归问题
• cbonnissent 反向工程了 Cowork VM 客户端 RPC 协议，修复了 KVM 启动阻塞问题，并解决了持久连接中 RPC 响应 ID 回显的问题
• joekale-pp 为 RPM 启动器添加了 --doctor 支持
• ecrevisseMiroir 提供了 bwrap 后端沙箱隔离功能，采用基于 tmpfs 的最小化 root 文件系统
• arauhala 对 NixOS isPackaged 回归问题进行了详细根因分析
• cromagnone 通过详细日志证实了 bwrap 安装中的 VM 下载循环问题，推翻了最初的初步判断
• aHk-coder 诊断了 cowork smol-bin 补丁中硬编码的压缩变量导致的崩溃问题
• RayCharlizard 对自引用 .mcpb-cache 符号链接 ELOOP 错误进行了详细分析
• reinthal 修复了因 nixpkgs 移除 nodePackages 导致的 NixOS 构建中断问题
• gianluca-peri 报告了 GNOME 退出时的无障碍问题，并确认了使用 AppIndicator 的托盘行为

赞助

Anthropic 并不发布 Claude Desktop 的发行说明。此处的每次发布都包含由 AI 生成的注释，用于分析版本之间的代码变更。如果您感兴趣，可以阅读我撰写的关于该流程的文章：从压缩的 Electron 应用程序中生成真实的发行说明。

该分析是通过 Claude 的 API 运行的。费用会根据更新的大小有很大差异。最近几次发布的费用介于 每版 3.36 美元到 76.16 美元 之间。

如果这个项目对您有所帮助，请考虑在 GitHub 上赞助，以帮助支付这些成本。

许可证

本仓库中的构建脚本采用双重许可：

• MIT 许可证（参见 LICENSE-MIT）
• Apache 2.0 许可证（参见 LICENSE-APACHE）

而 Claude Desktop 应用程序本身则受 Anthropic 的消费者条款 约束。

贡献

欢迎贡献！通过提交贡献，即表示您同意将其按照与本项目相同的双重许可条款进行授权。

Claude Desktop for Linux 快速上手指南

本指南帮助你在 Debian/Ubuntu、Fedora/RHEL、Arch Linux 或 NixOS 系统上原生运行 Claude Desktop。该项目通过重新打包官方 Windows 应用，提供 .deb、.rpm、AppImage 等多种格式支持。

注意：这是一个非官方构建脚本。如遇构建或 Linux 实现问题，请在原仓库提交 Issue。

环境准备

系统要求

• 架构：amd64 (x86_64) 或 arm64
• 发行版：
  • Debian / Ubuntu (推荐 apt 源)
  • Fedora / RHEL (推荐 dnf 源)
  • Arch Linux (通过 AUR)
  • NixOS (通过 Flake)
• 显示服务器：支持 X11 或 Wayland (通过 XWayland)

前置依赖

大多数安装方式会自动处理依赖。若需手动检查环境或排查沙箱权限问题，可运行以下诊断命令：

claude-desktop --doctor

该命令将检测显示服务器、沙箱后端（bubblewrap/host）、MCP 配置及缺失的依赖项。

安装步骤

请根据你的 Linux 发行版选择对应的安装方式。

方案一：Debian / Ubuntu (推荐)

通过添加 APT 仓库实现自动更新：

# 1. 添加 GPG 密钥
curl -fsSL https://aaddrick.github.io/claude-desktop-debian/KEY.gpg | sudo gpg --dearmor -o /usr/share/keyrings/claude-desktop.gpg

# 2. 添加软件源
echo "deb [signed-by=/usr/share/keyrings/claude-desktop.gpg arch=amd64,arm64] https://aaddrick.github.io/claude-desktop-debian stable main" | sudo tee /etc/apt/sources.list.d/claude-desktop.list

# 3. 更新并安装
sudo apt update
sudo apt install claude-desktop

方案二：Fedora / RHEL (推荐)

通过添加 DNF 仓库实现自动更新：

# 1. 添加软件源
sudo curl -fsSL https://aaddrick.github.io/claude-desktop-debian/rpm/claude-desktop.repo -o /etc/yum.repos.d/claude-desktop.repo

# 2. 安装
sudo dnf install claude-desktop

方案三：Arch Linux

使用 AUR 助手（如 yay 或 paru）安装 AppImage 版本：

# 使用 yay
yay -S claude-desktop-appimage

# 或使用 paru
paru -S claude-desktop-appimage

方案四：NixOS

直接通过 Flake 安装：

# 基础安装
nix profile install github:aaddrick/claude-desktop-debian

# 包含 MCP 服务器支持 (FHS 环境)
nix profile install github:aaddrick/claude-desktop-debian#claude-desktop-fhs

方案五：通用安装 (AppImage/包文件)

访问 Releases 页面 下载最新的 .deb、.rpm 或 .AppImage 文件进行手动安装。

基本使用

启动应用

安装完成后，直接在终端输入以下命令启动：

claude-desktop

或在应用程序菜单中搜索 "Claude Desktop" 点击启动。

核心功能

• 全局快捷键：默认使用 Ctrl+Alt+Space 唤起窗口（支持 X11 和 Wayland）。
• 系统托盘：最小化后将在系统托盘显示图标。
• MCP 支持：完整集成 Model Context Protocol。

配置文件

MCP 及相关设置存储在以下位置：

~/.config/Claude/claude_desktop_config.json

实验性功能：Cowork 模式

当前版本默认启用 Cowork 模式，并自动选择最佳隔离后端：

• bubblewrap (默认)：提供命名空间沙箱隔离（家目录只读，仅项目工作目录可写）。需安装 bwrap。
• host (降级方案)：无隔离，直接在宿主机运行。仅在了解安全风险时使用。

运行 claude-desktop --doctor 可查看当前使用的后端及依赖状态。