官方 docs · 核于 2026-09-23

Orca 装完之后找不到 orca 命令：先确认它装成了 orca-ide

Orca 这一页只排装与连不上这一类：Linux 上命令行名是 orca-ide 不是 orca、Homebrew 得用带 tap 的那条、CLI 提示 command not found、SSH 连上但远端终端起不来、手机配对连不上，官方 docs 对这几件各有一句（核于 2026-09-23）。

更新于 2026-09-23

#orca-ide 命令名#带 tap 的 brew#AppImage / deb / rpm#SSH 与手机配对

排障前先记住的四件事

orca-ide

命令行名与包名

官方明写 Linux 上装成 orca-ide，不遮蔽 GNOME 的读屏软件；.deb/.rpm 同名同因。先 which orca-ide，再去怀疑没装上。

带 tap

brew 那条要写全

stablyai/orca/orca 才是这个 cask；裸 orca 那个自 2026-09-01 起 disabled，原因是 fails_gatekeeper_check。

~/.local/bin

CLI 注册在哪

command not found 的官方解法是去 Settings → General → Orca CLI 注册，macOS 会把一个 shim 装进 ~/.local/bin，然后确认它在 PATH 里。

同一应用

包格式≠不同版本

AppImage/.deb/.rpm 装的是同一个应用，官方原话差别的只是更新怎么送达；别按包格式猜功能差异。

先说清楚：装的是同一个应用，命令名不一定叫 orca

官方 install 页把这件事单独立了一个小节，标题就是「The CLI command is orca-ide」，正文写 On Linux the Orca CLI installs as orca-ide, not orca，理由是 GNOME Orca — the screen reader that ships by default on Ubuntu and other GNOME desktops — already owns /usr/bin/orca, and Orca will not shadow it；同一节还补了一句：The .deb and .rpm packages are named orca-ide for the same reason。所以「装完敲 orca 没反应」在 Linux 上多半不是没装上，而是这条路径本来就不归它。

当天数得出来的

GitHub Releases 的 latest 页 2026-09-23 抓到的是 v1.4.207，published 2026-09-22T09:44:40Z，资产里同时有 orca-macos-x64.dmg、orca-windows-setup.exe 与 orca-linux.AppImage 这几类构建；许可按仓库 LICENSE 文件本体核为 MIT（API 的 license 字段同值）。star、fork 这类按分钟漂的计数不放本页正文——P4 那张横评表才放，且每个数都带当天抓取时刻。手机侧 iOS 走 App Store（列表里那个 app 的内部名是 orca-ide），Android 官方给的是 releases 上的 app-release.apk 与一页安装指引。

时间线

2026-09-01

2026-09-01：Homebrew 公开元数据里 orca 这个 cask 的 disable_date 就是这天，disable_reason 为 fails_gatekeeper_check；本页核于 2026-09-23，该 cask 的 disabled 仍是 true、deprecated 仍是 false。也就是说它不是「被 Orca 取代」，是被 Homebrew 停了。

2026-09-22

2026-09-22：这一页要用的官方 docs 六页（install、troubleshooting、ssh、mobile、android-apk、headless Linux server）与 README 全部原样抓回归档，页面里每处英文引号都能在那批档案里逐字搜到。

2026-09-23

2026-09-23：本页四语正文定稿并核对官方口径。命令行名、包名、cask 状态这类都会随版本变，所以每个小节都标了核对于哪天；下次改动按日期重取，不在原文里悄悄替换。

能自己排 vs 得看官方

官方逐字可证

核于 2026-09-23，能在官方页面逐字对上的有六条：1) On Linux the Orca CLI installs as orca-ide, not orca；2) GNOME Orca — the screen reader that ships by default on Ubuntu and other GNOME desktops — already owns /usr/bin/orca, and Orca will not shadow it；3) brew install --cask stablyai/orca/orca 与 brew upgrade --cask orca；4) Each published release ships three Linux packages — an AppImage, a .deb, and an .rpm ... They contain the same app；5) command not found 的解法是 Register the CLI under Settings → General → Orca CLI，macOS 的 shim 落在 ~/.local/bin；6) 手机那条 offer：A pairing offer is a capability containing a device credential and E2EE material。

⚠️ 三个想当然

一，「敲 orca 没反应就是没装上」：Linux 上它本来就不叫 orca，官方明写不遮蔽 GNOME 读屏软件，先看 orca-ide 与 PATH。二，「brew 里 orca 被下架了所以 Orca 不能用 Homebrew 装」：被停的是那个没带 tap 的同名 cask（fails_gatekeeper_check），带 tap 的 stablyai/orca/orca 才是这条路，官方 install 页第一句就是它。三，「SSH 能连就能干活」：官方 troubleshooting 页把 files 与 terminals 分成两件事，还单列了 SSH works for files but not “Download Folder”——整目录下载要递归 SFTP，系统自带的 sftp 通道上可能只成一半。

「装错了」与「真没装上」怎么分

先查这两处

一，名字：which orca-ide 有没有东西、PATH 里有没有 ~/.local/bin；二，通道：macOS 用的是带 tap 的 cask 还是 GitHub 上那个 .dmg，两者都是 stable，但只有前者会跟着 brew upgrade 走。这两处对上，大多数「找不到命令」就自己消失了。

再查这三处

一，签名与放行：官方 macOS 一节写 Signed and notarized，同时说明首次启动仍可能让你确认，这在 Electron 应用上是正常现象；二，远端机器：SSH 连上但终端起不来，官方让确认远端有 Node 且首次 relay 安装要能出网，Linux 上还要有 make、g++/clang++、python3，装完重连一次；三，最小镜像：headless 那页写着 A minimal server or container image ships none of the Electron libraries，缺的是共享库不是 Orca 本体。

装的时候选哪条路

macOS：官方给的是带 tap 的那条 brew install --cask stablyai/orca/orca，升级是 brew upgrade --cask orca，并写明这个 cask 跟的是 stable 通道，要 RC 构建得走 GitHub Releases 或应用内的 Check for Updates。裸 orca 这个 cask 名被别的产物占着：Homebrew 的公开元数据 2026-09-23 抓到的是 disabled: true、disable_date 2026-09-01、disable_reason 是 fails_gatekeeper_check（不是「下架」，deprecated 仍然是 false）。Linux：官方说每个发布都出 AppImage、.deb、.rpm 三种包，x64 与 arm64 都有，They contain the same app. What differs is how updates reach you，所以选哪个只看「更新怎么到你手上」。Arch 那条是 yay -S stably-orca-bin（或 stably-orca-git 从源码构建）。无图形界面的服务器另有官方一页：先装 Xvfb 与 Electron 要链的那批共享库，官方提醒 A minimal server or container image ships none of the Electron libraries。

这和 QCode 有什么关系

装这一侧没有关系：Orca 不含模型，也不替你保管凭据，装完之后模型访问仍然来自被启动的那个 agent CLI 自己的配置。有关系的是那一把 key 指到哪：如果你走的是自有端点，改的是那个 CLI 的 base_url 与 key，这一页只负责让 Orca 本身先起来、远端终端能开、手机能配上。端点写法在站内那篇自定义端点指南里，本页不重复。

常见问题

Linux 上敲 orca 没反应，是安装失败吗？

通常不是。官方 install 页专门写了「The CLI command is orca-ide」这一节：Linux 上 Orca CLI 装成 orca-ide，因为 GNOME 自带桌面已经占着 /usr/bin/orca，Orca 不去遮蔽它；.deb 与 .rpm 的包名同理。所以先 which orca-ide，再看 ~/.local/bin 在不在 PATH 里，这两步排完再谈重装。

为什么 brew install --cask orca 报这个 cask 被禁用？

因为 orca 这个不带 tap 的 cask 不是本项目的发布通道。Homebrew 公开元数据 2026-09-23 显示它 disabled: true、disable_date 2026-09-01、disable_reason 为 fails_gatekeeper_check（同时 deprecated 仍是 false）。官方 install 页给的是带 tap 的 brew install --cask stablyai/orca/orca，升级是 brew upgrade --cask orca，并说明该 cask 跟 stable 通道。

AppImage、deb、rpm 该选哪个？

官方原话是每个发布都出这三种包（x64 与 arm64 都有），They contain the same app. What differs is how updates reach you, so pick on that —— 也就是说选型的依据是「更新怎么送到你手上」，不是功能差异。要 Arch 那条就走 stably-orca-bin 或从源码构建的 stably-orca-git。

终端里提示 Orca CLI command not found，去哪修？

官方 troubleshooting 页给的是注册那一步：Register the CLI under Settings → General → Orca CLI；macOS 上它会往 ~/.local/bin 放一个 shim，接着确认这个目录在你的 shell PATH 里。换句话说这不是重装能解决的，缺的是 PATH 里那一条。

SSH 连上了但远端终端开不起来，先查什么？

官方 troubleshooting 页列了三条：确认远端有 Node 且首次 relay 安装时能出网；Linux 远端补上 make、g++/clang++、python3 这套 C/C++ 工具链；装完记得重连一次，让 Orca 重装它的原生模块。另一页（headless Linux server）补了服务器侧的前提：A minimal server or container image ships none of the Electron libraries，要连 Xvfb 与 Electron 的共享库一起装。

手机配对那张 offer 看起来没问题，为什么连不上？

官方 headless 页把原因拆成两层：offer 本身是「A pairing offer is a capability containing a device credential and E2EE material」，只该发给目标客户端、也不要落到代理访问日志里；而连不上通常是网络那侧 —— boundEndpoint 是进程在听的地址，advertisedEndpoint 是客户端要拨的地址，官方写明只要 DNS、防火墙、Docker 端口发布、Tailscale 策略或反向代理没把 advertised 路由到 bound，一张看起来合法的 offer 照样连不上。

信息来源

官方文档（2026-09-22 原样抓回本地归档）：install、troubleshooting、ssh、mobile、android-apk 五页在 https://raw.githubusercontent.com/stablyai/orca/HEAD/docs/site/content/docs/<页名>.mdx；headless Linux server 与 linux glibc 兼容两页在 docs/reference/ 下；README 在仓库根。Homebrew 侧用 https://formulae.brew.sh/api/cask/orca.json 的公开元数据；发布与资产名用 https://api.github.com/repos/stablyai/orca/releases/latest。全部为公网抓取，不带任何登录态。

先让 CLI 被认出来

排障顺序建议：orca-ide 在不在 PATH → CLI 注册（Settings → General → Orca CLI）→ 远端 Node/工具链 → 再谈模型端点。官方口径核于 2026-09-23。

创建账号浏览模型查看套餐