> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# 在 macOS 上安装 Octop 客户端与 OctopPet 桌宠

Octop 客户端和 OctopPet 桌宠目前还没有通过 Apple 的公证（notarization）。在 macOS 15（Sequoia）及更新的系统上第一次打开它们时，系统会弹出「已损坏，无法打开。你应该将它移到废纸篓」。

**这不代表安装包坏了。** macOS 会给所有从浏览器、微信、邮件下载的文件打上一个隔离标记（`com.apple.quarantine`），碰到没有公证的 app 就直接拒绝运行。把这个标记去掉，app 就能正常使用。


![macOS 提示 App 已损坏](/images/macos-unsigned-damaged.png "macOS 提示 App 已损坏")


> **注意**
> 
> 看到这个弹窗请点**取消**，不要点**移到废纸篓** —— 点了就得重新下载。
> 



> **说明**
> 
> 本文截图取自另一个未签名 app，操作流程完全一致。你实际看到的弹窗里显示的会是 `Octop.app` 或 `OctopPet.app`。
> 


## 第一步：把 app 放进「应用程序」文件夹

先把 app 安装到固定位置，后面的命令才好写。

Octop 桌面客户端请从 [Octop v1.0.3b5 发布页](https://github.com/TencentCloud/Octop/releases/tag/v1.0.3b5)下载与你的 Mac 匹配的 macOS 包：Apple Silicon 使用 `Octop-desktop-darwin-arm64-1.0.3b5.dmg`，Intel 使用 `Octop-desktop-darwin-amd64-1.0.3b5.dmg`。同一发布页也提供对应的 `.zip`。


**下载的是 .dmg**

双击 `.dmg` 文件挂载磁盘映像，把里面的 `Octop.app`（或 `OctopPet.app`）拖到左侧的**应用程序**文件夹，然后在访达侧边栏点击映像旁边的推出按钮。


**下载的是 .zip**

双击 `.zip` 解压，得到 `Octop.app`（或 `OctopPet.app`），把它拖进**访达 → 应用程序**。



> **提示**
> 
> 不要直接在「下载」文件夹里打开 app。放进**应用程序**后路径固定为 `/Applications/Octop.app` 和 `/Applications/OctopPet.app`，后续步骤可以直接复制粘贴命令。
> 


## 方案 A：移除隔离标记（推荐）

这是最省事也最安全的做法 —— 只对你指定的那个 app 生效，不会改动系统整体的安全设置。


### 打开「终端」

按 `⌘ + 空格` 唤出聚焦搜索，输入 `终端` 后回车。也可以在**启动台 → 实用工具 → 终端**里找到它。

### 执行命令

如果 app 已经放在**应用程序**文件夹里，直接复制下面的命令粘贴进终端，按回车：

```bash Octop 客户端
sudo xattr -rd com.apple.quarantine /Applications/Octop.app
```
```bash OctopPet 桌宠
sudo xattr -rd com.apple.quarantine /Applications/OctopPet.app
```


### 输入开机密码

终端会提示 `Password:`。输入你的 Mac 登录密码后回车。

> **说明**
> 
> 输入密码时终端不会显示任何字符，光标也不会动 —— 这是 macOS 的正常行为，不是卡住了。盲打完直接回车即可。
> 

### 打开 app

命令执行成功后终端不会有任何输出，直接回到**应用程序**双击 app 即可正常打开。

### 如果 app 不在「应用程序」文件夹

app 放在别处时，路径不用手打 —— 把图标拖进终端即可：


### 先输入命令前半段

在终端里输入下面这段，**末尾留一个空格**，先不要回车：
```bash
sudo xattr -rd com.apple.quarantine 
```

### 把 app 拖进终端

在访达里找到 app，把图标直接拖进终端窗口。终端会自动把完整路径填在命令后面。按回车，然后输入开机密码。

## 方案 B：允许「任何来源」

方案 A 之后仍然打不开，或者你要一次装好几个未签名 app，可以临时放开系统的来源限制。


> **注意**
> 
> 这一步会**全局**降低 macOS 的 Gatekeeper 检查，之后从任何地方下载的 app 都不再被拦截。装完建议按下面「装完后恢复默认」一节改回来。
> 



### 在终端执行命令

```bash
sudo spctl --global-disable
```
同样会提示输入开机密码，输入时没有字符显示，直接回车。

### 在系统设置里选择「任何来源」

打开**系统设置 → 隐私与安全性**，滚动到**安全性**分组。此时**允许以下来源的应用程序**下面会多出一个**任何来源**选项，选中它。

![隐私与安全性里的任何来源选项](/images/macos-unsigned-anywhere.png "隐私与安全性里的任何来源选项")

### 确认授权

系统会弹窗提醒风险，并要求再次验证。点击**允许任何来源**，输入密码或用触控 ID 确认。

![确认允许任何来源](/images/macos-unsigned-anywhere-auth.png "确认允许任何来源")

### 打开 app

回到**应用程序**双击 Octop 客户端或 OctopPet 桌宠。

### 装完后恢复默认

app 能正常启动之后，建议把 Gatekeeper 恢复到默认状态。已经装好的 app 不会受影响：

```bash
sudo spctl --global-enable
```

## 常见问题


**终端提示 No such xattr: com.apple.quarantine**

说明这个 app 上本来就没有隔离标记，或者你已经执行过一次了。这不是错误，直接打开 app 即可。

**系统设置里找不到「任何来源」**

说明 `sudo spctl --global-disable` 没有真正执行成功 —— 通常是密码没输对。回到终端重新执行一次，注意输入密码时屏幕上不会有任何显示。执行完再回到**系统设置 → 隐私与安全性**查看。

**弹窗写的是「无法验证开发者」而不是「已损坏」**

这种情况更好处理，不需要用终端。在**访达 → 应用程序**里**右键点击** app，选择**打开**，在确认弹窗里再点一次**打开**。
如果右键打开也被拦，去**系统设置 → 隐私与安全性**，在**安全性**分组里找到刚才被拦截的 app，点它旁边的**仍要打开**。

**更新到新版本后又提示已损坏**

新下载的文件会带上新的隔离标记，属于正常现象。对新版本重新执行一次**方案 A** 的命令即可。

**提示「找不到命令」或路径里有空格**

确认命令是 `xattr` 而不是别的拼写。如果 app 路径里包含空格，请用引号把路径包起来，例如 `sudo xattr -rd com.apple.quarantine "/Applications/My Apps/Octop.app"`。把 app 图标拖进终端窗口可以避免手打路径。

## 安全提醒

绕过 Gatekeeper 的前提是你信任这个安装包的来源。请只从 Octop 官方发布渠道下载客户端和桌宠，不要使用第三方转载的安装包。

方案 A 只影响你指定的那一个 app，是更推荐的做法；方案 B 会放开整个系统的来源检查，用完请及时恢复。


> **提示**
> 
> 只想在服务器或命令行环境里使用 Octop？桌面客户端不是必需的 —— 参考[快速开始](/guide/quickstart.md)直接安装 `octop` CLI 并从浏览器访问页面。
> 

