如何在 Linux 系统上安装 OneKey App

适用范围

本文适用于需要在 Linux 系统上安装和运行 OneKey App 的用户。

不同 Linux 发行版的依赖和权限策略可能不同。本文以 Ubuntu / Debian 系统为主要示例，同时提供通用的 udev 规则配置方法。

在 Linux 系统中，udev 规则用于让系统正确识别 OneKey 硬件钱包。无论你使用 Snap 还是 AppImage，都建议先完成此步骤。

下载并安装 OneKey udev 规则：

sudo curl -fsSL https://data.onekey.so/onekey.rules -o /etc/udev/rules.d/99-onekey.rules

如果系统未安装 curl，可以先运行：

sudo apt update 
sudo apt install curl

重新加载 udev 规则：

sudo udevadm control --reload-rules sudo udevadm trigger

安装 Snap：
```
sudo apt update 
sudo apt install snapd
```
如果你使用的是其他 Linux 发行版，可参考 Snap 官方文档安装 snapd。
安装 OneKey App：
```
sudo snap install onekey-wallet
```
你也可以打开 Snap 商店页面安装：https://snapcraft.io/onekey-wallet
允许 OneKey App 访问 USB 设备：
```
sudo snap connect onekey-wallet:raw-usb
```
打开 OneKey App，并选择连接硬件钱包。

如果启动时出现类似错误：

error while loading shared libraries: libgbm.so.1: cannot open shared object file

通常表示当前 Snap 包内缺少图形库依赖。

由于 Snap 使用沙箱隔离机制，即使在宿主机系统中安装 libgbm1，Snap 应用也不一定能读取宿主机中的图形库。

如遇到该问题，建议暂时改用 AppImage 版本，或等待 OneKey 更新 Snap 安装包后再使用 Snap 版本。

在 Ubuntu 24.04 及以上版本中，系统默认启用了更严格的非特权用户命名空间限制。部分 AppImage 应用可能会因为 Electron / Chromium 沙箱初始化失败而无法启动。

如果运行 AppImage 时出现类似错误：

The SUID sandbox helper binary was found, but is not configured correctly

或提示 chrome-sandbox 权限异常，可尝试使用以下命令启动：

./OneKey-Wallet-*.AppImage --no-sandbox

请确保命令在 AppImage 文件所在目录中运行。

如果运行时遇到缺少 X Server 或 $DISPLAY 的错误，通常表示当前系统缺少图形桌面环境或相关组件。

对于 Ubuntu / Debian 系统，可以安装图形环境相关组件后再尝试运行。

请依次检查：

如果你使用 Snap 版本，请确认已经运行：

sudo snap connect onekey-wallet:raw-usb