# 开始使用 Cage

这份指南从安装应用开始，带你完成系统选择、代理配置、启动环境和第一次项目操作。Cage 在电脑上运行独立的持久环境：可以在 Mac 上使用 macOS、在 Windows 上使用 Windows，也可以选择轻量的 Debian。终端、浏览器、编辑器和官方 Claude Desktop 都从同一个工作台进入。

功能按当前开发构建说明；公开安装包包含的入口与验证范围，以对应发行说明为准。详细的日常操作集中在[使用手册](guide/index.md)，本页保留从安装到第一次工作的路径与常用参考。

打开 Cage 默认进入本机首页。要使用服务器，在侧栏点「SSH 主机」，用加号保存地址、SSH 用户和密钥，然后点「连接此主机」。首次连接须核对主机指纹。服务器已就绪时直接进入远程工作台，已部署的服务停止时会自动启动。首次安装会显示「部署并连接」，点击后 Cage 通过 SSH 上传部署包并准备容器，本机虚拟机可以一直关闭。如果本机环境正在运行，切换前可选择保留或停止。[支持的服务器和部署条件](../deploy/cloud/README.md)

## 使用本机环境前的准备

| 需要准备 | 说明 |
|---|---|
| 支持的平台与虚拟化 | Apple Silicon Mac 需要 macOS 14+；Windows 10 22H2 / 11 x64 运行 Debian 时需要 Windows 虚拟机监控程序平台，Windows 11 客机需要受支持版本的完整 Hyper-V；Debian 12 / Ubuntu 22.04 / 24.04 x86_64 主机需要 KVM。具体组合见[选择客机系统](guide/guest-systems.md)。Intel Mac、Windows ARM64 和 Linux ARM64 暂不支持。 |
| 可用的代理 | Clash/Mihomo YAML 订阅、本地 YAML，或自己的 HTTP/SOCKS5 节点。Cage 随附代理核心，不提供代理服务。 |
| 自己的 Claude 使用资格 | 需要使用 Claude Code 时，在 Cage 内完成自己的授权。主机已有登录不会自动导入。 |

首次创建时需要准备所选系统的官方安装介质和开发工具，请保持网络可用并留出磁盘空间。下载与安装时间由系统和网络速度决定；随后启动复用已有环境。主机与客机的具体组合见[选择客机系统](guide/guest-systems.md)。

## 1. 安装应用

在[项目主页](https://claude-cage.com/#download)点击“下载应用”，选择 macOS、Windows 或 Linux。也可直接查看 [GitHub Releases](https://github.com/Lee-xeo/Claude-Cage/releases)，无需获得仓库访问授权。各平台的可下载版本可能不同；没有公开安装包的平台会提供安装与构建说明。

| 平台 | 安装方式 |
|---|---|
| macOS | 下载 Apple Silicon `.dmg`，打开后将 Cage 拖入 Applications（应用程序），再从“应用程序”启动。 |
| Windows | 下载 x64 `.exe` 安装器，运行后从开始菜单打开 Cage。可信签名包支持校验发布者身份；旧版或单独标明“未签名”的预览包仅用于手动安装测试，不能自动安装更新。详见 [Windows 指南](windows.md)。 |
| Linux | 下载 x86_64 `.deb`，使用 `sudo apt install ./Cage-<版本>-linux-amd64.deb` 安装。缺少 QEMU、GTK、WebKitGTK、OpenSSH 等主机依赖时，APT 会从系统配置的软件源补齐，再从应用菜单打开 Cage。详见 [Linux 指南](linux.md)。 |

无需先安装开发工具或 Clash。签名、公证和平台验证情况以该安装包的 Release 说明为准。如果系统拒绝打开，先按[安装问题](troubleshooting.md#下载或安装受阻)核对版本与来源。下述代理、环境和项目操作共用。

首次打开 Cage，先注册用户名和至少 8 个字符的密码，再选择客机系统、存储位置和网络代理。Mac 上的用户名使用小写字母开头的 1–31 个小写字母、数字或下划线，密码使用 8–256 个英文键盘可输入的字符；新建 macOS 客机使用同一套账密。三平台完整桌面版默认勾选“记住我”，可取消勾选；已有密码账户也可在登录时勾选，或在“设置 → 账户 → 记住我”中开启。关闭后的选择会保留。

账户保存在当前主机，没有在线找回。左下角头像菜单的“设置 → 账户”可以更换头像和密码；用户名用于 macOS 客机后会固定，以保留用户目录和文件。修改共用密码时，客机关闭或暂时无法连接，会在下次启动时继续同步；完成前客机可能仍需原密码。Cage 账户不替代 Claude 账号，也不会加密项目文件或整个虚拟磁盘。

### 选择客机系统

首次创建本机环境时，可以选择与主机同类的系统：Apple Silicon Mac 上使用兼容的 macOS，具备完整 Hyper-V 的 Windows 11 专业版、企业版或教育版上使用 Windows 11。三个受支持的桌面平台都可以选择 Debian 13；Windows 家庭版和受支持的 Windows 10 主机使用 Debian。

客机系统决定终端、编译器和应用实际运行的平台。开发 Mac 或 Windows 应用时选择对应系统，主要使用 Linux 命令行与服务时选择 Debian。macOS 和 Windows 按引导完成客机账户、首次登录和权限设置；系统镜像来源、空间要求与许可见[客机系统指南](guide/guest-systems.md)。更新 Cage 不改变已有系统，更换系统需要独立安装并保留原环境。

首次创建也可按本机版本自动匹配官方材料，建立干净的独立客机，主机个人文件和登录资料不在创建来源中。Mac 的本机匹配入口要求 macOS 26.4+；Windows 匹配发行版本、版本类型和语言，补丁构建可不同；Linux 支持 Debian 12/13 与 Ubuntu 22.04/24.04。具体版本、下载量、空间与续装规则见[本机系统匹配](guide/guest-systems.md#克隆本机系统)。

### 选择环境存储位置

Windows 安装器中选择的是程序目录。如果希望镜像下载和虚拟磁盘都放在 D 盘，首次登录后在独立初始化界面的“系统与存储”中修改已填入默认值的“存储目录”，或选择专用空文件夹，例如 `D:\CageData`，点击“下一步：配置代理”时保存。macOS 和 Linux 使用相同流程。安装、必要授权与网络检查完成后才进入工作台；中断后重新打开仍可继续。Debian 环境默认设置下，虚拟磁盘在用户主目录的 `.claude-cage/state/lima`，镜像下载缓存在系统用户缓存目录下的 `lima`（Windows 为 `%LOCALAPPDATA%\lima`）。

选择支持私有文件权限和稀疏文件的本地磁盘。Windows 可用 NTFS，Linux 可用 ext4、XFS 或 Btrfs。Mac 需要 APFS 卷并启用所有权。使用 Mac 外接盘时，在 Finder 的磁盘“显示简介”中取消“忽略此宗卷的所有权”。

已有环境可在“设置 → 环境与恢复 → 本机环境存储”换盘。先保存终端和编辑器中的工作，选择空文件夹并确认迁移。Cage 会停止环境，复制并校验数据，然后切换目录。手动启动环境，核对原先的文件和登录状态后，可以清理面板显示的旧备份以释放空间。目标盘需有足够的可用空间，使用外接盘时每次启动前都要接回原盘。账户配置保存在原用户目录，共享项目仍从各自的项目文件夹打开。旧的系统用户缓存可能还供其他 Lima 实例使用，迁移会将它留在原处。

### 首次启动下载什么

macOS 使用 Apple 提供的兼容恢复镜像，或用户已有的官方 IPSW；Windows 使用 Microsoft 官方 ISO，并准备对应系统的开发工具。两者的下载量和系统盘需求按所选版本显示。下面的下载清单及 24 GiB 初始磁盘上限适用于 Debian 13；macOS、Windows 的要求见[下载量与磁盘空间](guide/guest-systems.md#下载量与磁盘空间)。

| 内容 | 来源与用途 |
|---|---|
| Debian 13 基础镜像 | 按处理器架构下载一份，约 320–325 MiB。优先尝试南大、中科大的镜像，再尝试 Debian 官方源，使用 Cage 固定的 SHA-512 校验。 |
| Linux 软件包 | Debian 提供 Chromium、Python、Git、编译工具、远程桌面、字体和系统依赖。安装依赖前先检查 Debian 13 的 APT；低于 3.0.4 时通过官方安全源升级，并保留 Debian 签名与摘要校验。软件包默认优先使用通过连通性探测的南大、中科大镜像，最后回到官方。不可达的镜像本轮跳过；自定义软件源保持原配置。 |
| Node.js、编辑器与工具管理器 | Node.js 24 通过 NodeSource 安装。mise 优先从 npmmirror 下载上游发布的对应架构可执行包。code-server 优先从中科大下载固定版本的 Debian 安装包。两者都按 Cage 固定的 SHA-256 校验，公共镜像不可用时自动回到各自的 GitHub Release。编辑器还会从 SchemaStore 等来源预取 JSON 校验规则供离线使用，缺少某条规则只影响对应文件的校验。 |
| Claude Code | npm 官方注册表提供版本与完整性信息。较大的 Linux 可执行包优先从 npmmirror 下载，使用 npm 官方摘要校验。 |

首次安装和工具升级会自动选择下载来源，无需手动补缓存。中科大的 code-server 镜像只保留最近版本；Cage 固定的版本缺失时，会直接从 GitHub 下载该版本。下载仍经过当前选择的 Cage 代理。初始虚拟磁盘的容量上限为 24 GiB，下载流量与实际占用取决于架构、软件包版本和已有缓存。以后启动会复用已安装的环境。需要 Claude Desktop 时，在工作台单独安装，届时才访问 Anthropic 的软件源。

需要固定 Debian 官方源时，在客机的 `/etc/claude-cage/debian-mirror` 中写入 `official`；写入 `auto` 或移除该文件可恢复自动选择。下一次安装或维护时生效，偏好随虚拟磁盘保留，从基础环境克隆出的工作环境也会继承。镜像探测每个地址最多等待 8 秒；安装下载的无响应等待为 15 秒，最多重试一次。APT 升级失败会停止后续依赖安装，修复网络后可重试，无需删除个人数据或虚拟磁盘。

### 受信任的本机登录

注册账户时勾选「记住我」，以后同一系统用户打开 Cage 可自动进入。已有密码账户在登录页验证密码后也可启用，或在「设置 → 账户 → 记住我」中开启或关闭。三平台使用相同的本机信任机制。手动锁定仍需验证，退出账户会撤销此项信任。远程连接不能使用本机信任登录；Claude 服务仍需自己的授权。

受信任模式依赖操作系统的用户登录。离开电脑时请锁定系统。已有免账号工作区仍可继续使用；准备 macOS 客机时，引导会先要求设置共用账密，工作区内部密钥和已有数据继续保留。备份免账号工作区时，还需备份系统用户配置目录（Windows 使用 `%LOCALAPPDATA%`）下的 `Cage/trusted-local` 私有信任凭据，并以私有权限保存。

## 2. 导入并选择代理

进入工作台后点击“配置网络与代理”。之后也可以从左下角“设置 → 网络与代理”进入。没有节点时点击“添加来源”，选择一种导入方式：

- **订阅链接**：填写来源名称和 HTTPS 订阅地址。首次没有可用节点时，勾选“通过主机网络下载这份订阅”；不勾选则经当前配置的代理下载，失败不会自动切换路径。
- **本地 YAML**：选择文件，或粘贴配置内容。适合已经导出节点配置的情况。
- **手动节点**：填写自己的 HTTP 或 SOCKS5 节点参数；用户名和密码在对应字段中填写。

点击“导入并验证”，再进入“节点”，选择最终出口并点击“应用代理”。顶部会显示当前出口和准确状态：核心运行但环境未启动时显示“待启动环境”，检查通过后显示“已联网”；核心停止或未应用节点时不会放行外网。

如果住宅代理无法从国内直接连接，在“节点”页切换到“链式代理”，选择国内可连接的中转节点，再将住宅代理选为“最终出口”。节点可以来自不同订阅；按页面从上到下的顺序连接，预览应显示“Cage → 中转节点 → 住宅代理 → 目标网站”。点击“应用代理”后生效，网站看到的是最终出口的 IP。若需要多次中转，可点击“添加中转”。

代理组合会独立保存，订阅更新不会覆盖它；更新移除了正在使用的节点时，会保留原配置并显示错误。应用前的选择只是草稿，离开页面会提示是否放弃。“保存设置”用于 DNS、IP 变化规则等其他设置；代理使用配置区内的“应用代理”。

订阅应包含 `proxies` 或 `payload` 节点内容。Base64 列表、单个分享链接以及仅含远程 provider 的配置暂不支持；请向服务提供方获取 Clash/Mihomo YAML 节点订阅，或导出本地 YAML。导入只采用节点与明确的代理链，配置中的系统代理、TUN、端口及直连规则不会应用到 Cage。

Cage 使用独立端口和配置，不设置 系统代理，不开启主机 TUN，也不改变本机 Clash 的节点选择。订阅的主机下载与节点域名启动解析属于代理的准备通信；Cage 环境内的业务 DNS 仍经过选定节点。

HTTP/SOCKS5 服务可通过“订阅 → 添加来源 → 手动节点”录入服务器、端口和认证。所有节点均由 Cage 自带核心承接，网络页的加密 DNS 经当前节点转发。没有应用有效节点时，Cage 不会联网。

## 3. 启动并等待检查完成

返回工作台，首次创建时确认客机系统与存储位置，再点击“启动 Cage 环境”。无需先选择项目。应用先只读检查本机 Git；已启用保护，或确认未安装 Git 时，会直接继续。系统安装和必要授权完成后，后续启动继续使用原环境。

如果出现“启动前，保护本机 Git”，请阅读说明，再点击“启用保护并继续”。这会将当前主机用户的一项全局 Git 设置改为 `safe.bareRepository=explicit`，防止 Git 自动识别共享目录中的裸仓库并使用其中的配置。普通 `.git` 项目的提交、拉取、历史和远程地址不受影响；使用裸仓库时需要通过 `--git-dir` 明确指定。设置也会影响本机其他 Git 工具，Cage 仅在你明确确认后修改，重新检查通过后才启动环境。也可以选择“暂不启动”。

第一次启动时，工作台会显示当前正在下载或安装的组件。下载 Debian 镜像时可以看到已接收的数据量，服务器提供文件总大小时也会显示百分比。下载 mise、Claude Code 和网页编辑器时，可以看到当前文件已接收的数据量。安装软件包时显示组件名称，点击“操作详情”可查看安装日志。下载中断后，可以点击“继续安装”，Cage 会尝试从已保存的位置续传。环境启动后会连接浏览器并执行网络检查。Git 检查未通过时，按[启动前 Git 检查](troubleshooting.md#启动前的-git-检查未通过)处理，无需重新配置代理。

环境启动后先关闭业务外网，执行 11 项关键检查，覆盖出口、DNS、系统和浏览器配置、文件共享、宿主管理接口、代理故障关闭、UDP、IPv6 与出口规则。首次构建基础镜像没有项目挂载，需要经指定代理下载工具。

环境就绪、关键检查通过且网络授权有效时，界面显示绿色带对钩的盾牌。检查失败或证据缺失会保持外网关闭，终端、共享文件和环境内的本地网页仍可使用。点击底部网络状态查看具体失败项，修复后重新检查；检查进行中可以取消，也可以停止环境。

macOS、Windows 和 Linux 首次使用时，默认开启“跟随出口 IP 的时区”，在启动或应用设置时同步 Cage 环境的时区。进入“设置 → 时区与语言”可改为手动选择；已保存的手动选择会保留。语言可以单独开启自动跟随或手动选择。网络与系统设置需要应用后重启环境，界面会提醒保存文件和终端中断。运行中的任务不会因后台发现位置变化而被静默重启。

## 4. 打开项目并开始工作

点击左侧“项目”标题旁的加号，选择已有项目，或点击“添加本机项目…”选择主机上的项目文件夹。新终端和文件编辑器将从这个目录开始工作；没有项目时请先添加一个文件夹。终端使用所选客机的系统工具，Windows 客机提供 PowerShell 7，并保留 Windows PowerShell 5.1。

点击项目右侧的终端图标，选择“新建 Claude 终端”，Cage 会在该项目中自动运行 `claude`。也可选择普通终端，手动输入命令。“设置 → 通用 → Claude 终端启动命令”可添加参数，例如 `claude --continue`；保存后只影响新建的 Claude 终端，退出 Claude 后仍可继续使用 shell。

打开“设置 → Claude 账号”。如果你已在 Cage 普通终端用 Claude Code 登录订阅，环境就绪后，页面会显示默认终端检测到的邮箱。点击“加入调度”即可复用这份登录。设备上的 Claude Desktop、网页和 Mac 系统终端有各自的登录，面板只检查 Cage 客机里的 Claude Code。

要添加另一个订阅，点击“登录新账号”，在临时浏览器窗口完成官方授权。Cage 为这次登录分配独立目录，成功后按邮箱登记并参与调度，也可以再改备注。取消登录不会增加一个可调度账号。以后点击项目右侧的终端图标新建 Claude 终端，标签会显示它分配到的账号。

如果普通终端原先登录 A，后来登录 B，Cage 会停止把默认目录分配给 A。B 需要单独点击“加入调度”。要让 A 和 B 长期同时在线，可以保留一份默认登录，再用“登录新账号”为另一个账号建立独立登录。

关闭某个账号的“参与自动分配”只影响之后新建的终端，正在使用该账号的会话可以继续。打开账号面板时，Cage 会向客机里的官方 Claude Code 查询五小时和七天额度。点击卡片的“检查状态”可立即重查该账号，无需先发一条模型消息。某个窗口没有返回读数时，面板会说明结果，并保留该窗口上一次的百分比和读取时间。[账号调度与额度说明](guide/accounts.md)

新会话可均衡分配或按列表顺序选择账号。已有会话只有在明确授权、同一接续分组且原任务可安全停止时，才能切换账号恢复历史；也可预先允许额度确认耗尽后的自动接续。技能、指令与同项目记忆的共享范围，以及原生客机验证条件，见[多账号与额度](guide/accounts.md)。Claude Code 标签中的 Agent 编号表示当前绑定账号。

可以先让 Claude 读取项目并解释一个文件，确认模型请求正常，再让它在测试文件中完成一个小修改。通过“浏览文件”查看内容，并在主机上确认同一文件的变化。首次使用前请备份重要项目。

文件修改会直接作用于共享目录。项目内的 `.git` 可读写，可以让 Claude 修改代码，并在 Cage 中审查、暂存和提交。

点击左侧“浏览器”可返回正在使用的浏览页面；通过顶部加号新建网页。地址栏中的 `localhost` 指向当前 Cage 客机，可用于预览在 Cage 终端中启动的开发服务。

## 日常使用

### Claude 官网与桌面应用

浏览器下方的 `claude.ai` 入口直接在 Cage 浏览器中打开官网。`Claude Desktop` 入口提供官方桌面应用：首次点击“下载并安装”，Cage 从 Anthropic 官方源完成安装，随后打开应用；Chat 和 Code 在同一个应用内切换。安装前先启动环境并确保所选代理可用，无需等待业务网络放行；应用内联网仍需通过网络检查。安装失败时可查看进度并重试。

如果浏览器和 Claude Desktop 在滚动时卡顿，可开启“设置 → 通用 → 流畅画质”并保存。下次启动环境时，两者会用 1.5 倍像素绘图，文字和控件维持原有大小。关闭后可切回默认的 2 倍高清画质。

Desktop 的画面会随 Cage 窗口和侧栏自动调整。右上角“显示大小”默认 100%；选择较小的值可以显示更多内容，较大的值可以放大文字和控件，无需重启应用。调整结果会在本机保留。若提示画面尺寸未能同步，点击“重试调整”。

应用只在使用时下载和启动。切换到浏览器或终端时保持运行；点击应用上方的“关闭应用”释放其运行资源，登录数据仍保留在 Cage 中。应用关闭后可“更新 / 修复安装”。Claude 账号的首次登录在 Cage 内完成，不导入主机账号。系统密钥环由 Cage 在内部创建和解锁，无需再设置一份密钥环密码；修改 Cage 密码会保留应用登录数据。需要额外虚拟机的 Cowork 功能暂未适配。

应用页或 Cage 主机窗口不可见时，Cage 暂停对应用状态的定时检查；返回时立即重新读取。应用内任务继续运行，画质设置保持原有选择。

Linux 客机中由 Cage 管理的 Desktop 在最后一个电脑或手机查看者断开后自动隐藏窗口，减少后台绘图；再次打开画面时恢复。应用进程与正在执行的任务继续运行。Windows 和 macOS 原生客机保持其原生窗口行为，画面捕获随查看连接停止。

### 锁定与退出账户

左下角头像菜单中的“锁定 Cage”隐藏工作台并要求重新输入密码，正在运行的 Claude、终端和环境任务继续运行。“退出账户”会先提醒保存文件，再停止环境并锁定凭据。仅退出应用时后台任务继续运行。“设置 → 账户 → 记住我”可开启本机自动登录，下次用当前系统用户打开时直接进入；手动锁定后仍需密码或 Touch ID，重新打开也不会跳过验证。Mac 已设置 Touch ID 时，可在“登录与解锁”中开启指纹解锁。退出账户会撤销本机快捷登录授权。

### 保存网站账号密码

在 Cage 浏览器中提交邮箱等网站的登录表单后，浏览器工具区会提示保存账号密码。先确认网站登录成功，再点击“保存密码”；密码变化时可选择“更新密码”。“此网站不再提示”只关闭该网站的保存提示。

再次打开同一网站时，展开浏览器工具区的“密码”，选择账号填入登录框，再自行提交。当前支持 HTTPS 顶层页面的常见表单；嵌入框架、验证码和 Passkey 不自动处理。旧环境如果提示密码功能不可用，先到“设置 → 环境与恢复”更新环境组件。

在“设置 → 密码保险箱”中可以搜索、添加、编辑、删除记录，或恢复某网站的保存提示。查看、复制密码需要再次输入 Cage 账户密码。保险箱随 Cage 一起解锁和锁定；已启用记住登录时，也会随之解锁。密码只保存在本机，备份时需同时保留配置目录中的账户文件与密码库，具体边界见[密码保险箱设置](guide/settings.md)。

### 项目、标签与文件

左侧“项目”列出明确打开的文件夹，列表由 Cage 保存，重新打开应用后仍可看到。每个项目右侧有两个图标。点击打开图标（↗）可在 code-server 中编辑该目录的文件。点击终端图标（>_）可选择终端类型，在该目录新建终端。已有终端始终留在创建它的目录下。所有项目共用一个持久环境，所选客机系统、工具、账户和文件系统也相互共享。已打开的目录在环境启动时恢复连接。

浏览器独立于项目，网页和文件编辑器使用顶部标签页；切换项目不会关闭或迁移网页。将鼠标移入终端行，或用键盘聚焦该行，即可在右侧置顶、重命名或删除终端。浏览器标签可通过右键或 Shift+F10 打开操作菜单。拖动可调整同一列表内的顺序，刷新后保留。⌘1–9 切换当前浏览器的页面或当前目录的终端。

点击浏览器工作区右上角的 ×，退出浏览器视图并返回打开前的首页、终端或 Claude Desktop；原来的终端已结束时返回首页。横排与竖排标签均提供此按钮，双网页分屏共用一个关闭按钮。网页标签、登录和后台无痕会话继续保留，再次点击侧栏“浏览器”可以继续使用；结束无痕会话需关闭全部无痕标签或停止环境。

标签较多时会自动缩短，当前页面的标签保留更多标题空间。拖动时其他标签即时让位，松手保存顺序，Esc 取消；置顶标签在置顶分组内排序。右侧向下箭头可以搜索已打开的页面。

点击地址栏右侧的星标或按 ⌘D 收藏当前网页，可修改名称并选择或新建收藏夹。点击旁边的收藏夹按钮或按 ⌘⇧O，可搜索、打开和编辑收藏；编辑时可移动到其他收藏夹。删除收藏夹会把其中的网页移至“未分类”。收藏保存在本机当前 Cage 配置中，所有项目共用，重启后保留。

### 浏览器设置与扩展

在浏览器右上角“…”菜单点击“设置”，即可打开独立的设置标签；再次点击会回到同一标签。“新标签页”中可保存默认网址，“外观”中选择横排或竖排标签，“隐私与网站数据”中管理 Cookie 和网站权限。这些浏览器专属设置由浏览器自身管理。

进入“扩展”，可以添加 Manifest V3 的 ZIP 扩展。选择文件后先检查名称、版本和权限，再点击“安装扩展”。已安装列表支持启用、停用、移除和打开扩展选项；也可进入 Chromium 原生扩展管理或扩展商店。安装和启停状态随当前 Cage 环境保存，重启后继续使用。

点击“从本机导入”，选择 Edge、Chrome、Brave 或 Chromium 的用户配置，核对清单后导入所选扩展。原启停状态能读取时按原状态导入，无法读取时显示说明并保持停用。不兼容或已导入的扩展会单独标明；失败项目给出原因，不影响其余项目的结果。完成后点击“完成并关闭”，回到已安装列表。

导入一次后，两边独立管理。本机浏览器的账户、Cookie、扩展登录数据与原生伴随程序不会包含在程序包中，相关扩展可能需要重新登录或配置。部分扩展依赖浏览器专属能力或授权，兼容范围以扩展在 Cage 内的实际运行结果为准。详细机制见[浏览器设置与扩展](guide/browser.md)。

### 无痕浏览与 Cookie

点击地址栏右侧的“浏览器菜单”，选择“新建无痕标签”；也可按 macOS 的 ⌘⇧N 或 Windows、Linux 的 Ctrl+Shift+N。无痕标签在标题和地址栏中显示“无痕”。在无痕页点击标签栏加号或按新建网页快捷键，会继续创建无痕标签；从菜单选择“新建普通标签”可返回普通浏览。

普通网页与无痕网页的 Cookie、登录状态和网站存储相互隔离，同一批无痕标签之间共享临时会话。关闭最后一个无痕标签后清理该会话，重启环境不会恢复无痕网页。无痕页不会提示保存密码，标签重命名和排列也不写入本地持久存储。下载文件及主动保存的收藏继续保留。仅关闭或隐藏 Cage 窗口会保留后台浏览器；结束无痕会话应关闭所有无痕标签或停止环境。无痕浏览继续使用 Cage 的网络出口，网站和代理服务仍可识别相应请求。无痕网页可以与终端分屏，双网页分屏目前仅支持普通标签。

在浏览器菜单选择“管理 Cookie”，即可查看当前网站的 Cookie，或切换到“所有网站”。列表支持按网站或名称搜索、查看值、删除单条，以及清空当前网站或当前会话所有网站的 Cookie。每次操作仅影响当前标签所属的普通或无痕会话；清空范围不受搜索条件限制，需要再次确认，完成后网站可能要求重新登录。清空普通会话的所有 Cookie 也会清除文件编辑器的认证，可通过编辑器菜单的“恢复编辑器”重新打开。Cookie 清理保留网站的其他存储，例如 localStorage。

### 浏览器上传与下载

在网页中点击上传后，工作台显示“上传本机文件”。点击“选择本机文件”，即可用系统文件窗口选择图片、视频或文档，传递状态会显示在面板中。只传递所选文件，不增加文件夹共享。网页允许多选时最多选择 100 个文件，每个文件不超过 2 GB；目标网站自身的格式与大小限制仍然有效。可以取消上传，刷新或关闭原网页后需要重新选择。Claude Desktop 的文件上传也使用此本机选择入口；如果仍显示客机文件窗口，先保存并关闭 Claude Desktop，再重新打开。 在 Claude Desktop 的 Code 页选择工作文件夹时，Cage 会显示“选择工作项目”，列表与左侧项目列表保持一致。选中已有项目后点击“使用此项目”；新目录通过“添加本机项目…”打开系统窗口，确认后加入 Cage 项目列表并交给 Claude。Claude 选择项目不会切换 Cage 当前项目或已有终端。该目录中的改动会同步到本机。

网页下载仍在 Cage 内完成。本机先收到下载暂存目录中的完整文件，同名文件自动换名。工作台连接期间观察到下载完成后，会弹出系统“另存为”窗口；取消时保留默认位置的文件。共享目录暂时不可写而客机文件已完整下载时，也可以从下载列表直接另存为。

左侧“下载”入口和地址栏旁的下载按钮都可查看进度、文件名和保存位置，并提供“打开文件”“在文件夹中显示”“另存为”。已记录的本机文件在停止环境后仍能查看；再次打开 Cage 也保留保存位置。下载暂存目录通常为 `~/.claude-cage-downloads/Downloads/`，无需添加项目即可下载。使用普通浏览器打开工作台时，导出由该浏览器的下载功能处理。

Desktop 的主机文件操作只接受已授权项目或已保存下载记录中的文件，生成文档须先完成保存。Linux 客机沿用现有文件入口；macOS、Windows 原生保存与文件打开已经接入，完整官方应用的上传、保存、打开与定位仍待实机验收。需要其他目录时，先通过“添加本机项目…”明确授权；更新后关闭再打开 Desktop。当前条件与恢复方法见[Claude Desktop](guide/desktop.md#选择项目与传文件)。

### 关闭、退出与再次打开

| 操作 | 会发生什么 |
|---|---|
| 关闭窗口 | 环境和后台终端保留运行。 |
| 退出时选择保留环境 | 后台任务继续运行，下次打开 App 重新连接。 |
| 停止环境，或停止环境并退出 | 终端进程结束；项目文件、虚拟磁盘与登录状态保留。 |
| 刷新工作台 | 可重新连接控制服务中仍存活的终端。 |
| 重启控制服务或虚拟机 | 旧终端会话不能恢复，需要新建终端。 |

停止前先保存编辑器中的修改。再次打开 Cage 会使用同一环境，无需重新导入项目或重新创建虚拟磁盘。

切到终端、设置页，或隐藏、最小化窗口时，Cage 暂停浏览器画面的显示连接，保留浏览器页面、下载和后台任务。画面重新可见时自动连接；这项节省显示资源的行为不等于暂停浏览器或停止环境。

### 按键与剪贴板

“设置 → 通用”可以选择按键习惯。Mac 模式将网页和编辑器的 `⌘F`、`⌘Z`、`⌘⇧Z` 等映射为 Linux 对应的 Ctrl 组合；本机地址栏与设置输入框保留 Mac 操作。终端的 `Ctrl+C` 中断命令，`⌘C` 复制选中文本。

Windows 和 Linux 默认采用 Ctrl 按键习惯，工作台快捷键中的 `⌘` 对应 `Ctrl`；终端复制粘贴使用 `Ctrl+Shift+C/V`，保留 `Ctrl+C` 中断命令。

在 Claude Desktop、Claude Code 和普通终端的多行输入中，按 `Shift+Enter` 在当前输入内换行，按 `Enter` 提交消息或执行命令。网页和 Desktop 的目标输入框须支持多行；终端程序须支持多行粘贴或识别 Shift+Enter。Bash、zsh 启用多行粘贴时，换行不会执行已写好的命令；自行关闭此模式或使用其他终端程序时，行为取决于程序的按键支持。中文输入法仍在选择候选词时，回车先由输入法处理。

复制粘贴支持纯文本、中文、多行和 emoji。先点击目标输入框，再使用快捷键或工具栏按钮；普通浏览器限制剪贴板权限时，可用“文本传递”面板。Cage 仅在主动复制或粘贴时访问本机剪贴板，不持续轮询。

Cage 浏览器中的网页复制按钮也可同步纯文本到本机。点击后保持当前网页和 Cage 窗口处于前台，出现“已复制到本机”即可在其他应用粘贴。如果网页采用不受支持的旧式复制方式，或复制期间切换了标签、输入位置或窗口，可重新复制，或使用复制快捷键和“文本传递”面板。

本机截图可以粘贴到 Cage。视频、文档和图片文件可以直接拖入工作内容区，也可以先在本机文件管理器中复制，再到 Cage 粘贴。文件保留原始名称与内容，包括 GIF 动画；单文件最多 2 GB，一次最多 100 个。网页拖入会交给落点，文件粘贴会交给当前输入位置，目标网页须支持附件拖入；Claude Desktop 须先点击支持附件的输入位置。终端把文件保存到客机附件目录并插入带引号的路径，供 Claude Code 等工具读取，不自动执行命令。

截图粘贴上限为 20 MB、4000 万像素。Cage 通过本机与客机的控制通道传递附件，不借助外部存储服务；目标网页或应用可以按自身行为上传。终端附件保留到用户自行删除，Desktop 的上传副本保留到图形会话重建。切换目标或断开连接后，尚未发送的输入会取消。使用旧环境时，先按应用提示更新环境组件。

### 外观与浏览器首页

“设置 → 外观”支持跟随系统或固定使用浅色、深色主题。基础配色可调整强调色、背景和文字，展开每套主题的“自定义”后，还可分别调整侧栏、工具栏、标题、辅助文字、边框、输入框、按钮、链接、焦点、悬停、选中及状态提示颜色。终端的背景、文字、光标、选区与 ANSI 色板也可单独设置；虚拟机内的网页和编辑器保留各自外观设置。

每套主题的预设下拉框按“经典、编辑器、阅读、无障碍”分组，共有 14 个系列、22 套明暗搭配。可选 Codex、Solarized、Ayu、VS Code Modern / Classic、GitHub、Nord、Dracula、Monokai，以及参考 Typora 的纸白、暖纸和夜间风格。部分主题只提供浅色或深色版本，下拉框只显示当前模式可用的版本。选择预设会同时应用界面与终端配色，替换之前的元素颜色覆盖，保留已设置的字体；已保存的自定义主题不会被改写。

“无障碍 → 色觉友好 · 蓝橙”用蓝色与橙色区分成功和错误，减少红绿依赖；“高对比”提供白底黑字和黑底白字两种搭配，并加强边框与焦点。两类预设都关闭半透明侧栏，使对比保持稳定。卡片中带图标和文字的成功、警告、错误预览，可帮助比较状态色。不同色觉差异的适用配色会有差别，可继续自定义并另存主题；这些配色影响 Cage 界面和内置终端，虚拟机中的网页与编辑器保持各自外观。

颜色支持取色器和六位 HEX 输入。HEX 输入按 Enter 或离开输入框后生效；单独设置的颜色旁可恢复自动配色。字体、字号、对比度、指针和动态效果也在此调整。修改即时生效并自动保存，失败时保留当前输入，可点击“重试保存”。

在“我的主题”中输入名称，点击“另存为主题”，即可将浅色、深色两套配色、字体和侧栏透明度保存为一个主题。下拉框用于切换主题；修改后可“更新此主题”，也可另存，或点击“恢复已保存配色”放弃此次配色调整。删除主题会保留当前配色。最多保存 50 个自定义主题。

“导出主题”将当前两套配置保存为 `.cage-theme.json` 文件；“导入主题”校验文件后添加并应用，同名文件会另存，不覆盖已有主题。桌面版通过系统文件窗口读写，浏览器版使用文件选择与下载。主题文件不包含账户、代理、项目或本机路径；明暗切换模式、字号及交互偏好不随主题文件迁移。文件须为不超过 256 KB 的 Cage JSON 主题，格式版本不支持或内容无效时保留当前设置。

“从本机 Codex 同步”可复制 Codex 当前的外观偏好，导入后独立保存，并保留 Cage 中已保存的自定义主题。

浏览器“…”菜单的“设置 → 新标签页”控制新网页的默认入口，初始为 Bing；保存后下次打开网页生效，无需重启环境。

### 计算资源上限

“设置 → 环境与恢复 → 计算资源”默认按主机份额自动设置上限。关闭“自动分配资源上限”后，可分别指定内存 GiB 和 CPU 逻辑核心数，可填范围显示在输入框下方。点击“保存资源配置”后，下次启动环境时生效；运行中可点击“重启并应用已保存配置”，请先保存工作，重启会结束正在运行的命令。内存仍会在指定上限内按需增长和回收。macOS、Windows 和 Linux 操作一致；服务器容器资源由服务器部署配置管理。

### 时区、语言和出口变化

新用户默认开启时区和语言跟随出口 IP。自动时区经代理查询出口位置，采用返回的 IANA 时区；保存时和停止后的下一次启动会同步。位置服务不可用时显示错误，不使用主机位置代替。IP 定位依赖外部数据库，不能保证节点的物理位置。

语言可独立跟随出口地区，也可手动选择。自动模式使用内置地区默认值，多语言地区可自行调整；未知地区保留现有语言。

“设置 → IP 变化规则”支持静态 IP，以及动态 IP 的同一城市、同一州／省、同一国家／地区、不限地区。城市规则同时检查国家、州／省和城市。规则与最终出口节点的关联、首次绑定及切换行为见[时区、语言与出口规则](guide/network.md#时区语言与出口规则)。同一节点已有的基准只在用户明确修改时改变，重检不会自动接受新出口。

### 查看检查、暂停与恢复网络

点击底部网络状态可查看证据、重检或暂停外网。暂停会切断已有外部连接，终端和文件仍可离线使用。第三方 IP 信誉仅作提示，不单独决定联网；社区检查网站需要用户主动打开。

人工暂停会保存，关闭并重开后台后仍保持暂停，定期订阅刷新也不会自动恢复。旧配置没有暂停记录，或记录损坏时，Cage 默认保持外网关闭；确认后可通过启动环境、重新检测或手动应用网络配置恢复。若提示无法保存状态，当前外网仍会关闭，请解决配置写入问题后重试。

后台约每 30 秒核对出口与环境配置，发现不符合规则时暂停外网。网络放行每次最多 90 秒，控制服务失联后到期关闭；完整报告最多有效 24 小时，过期需要重检。HTTP/SOCKS5 代理可能按连接分配不同出口，抽样检查不能证明每条连接使用相同 IP；固定出口仍需代理服务自身保证。

## 网络与数据边界

Cage 使用轻量 Linux 虚拟机，没有完整桌面。浏览器与编辑器页面在虚拟机内执行，本机工作台呈现画面和终端；Chromium 以普通用户运行并保留自身沙箱。

- 对外 TCP 在主机侧虚拟网卡出口统一交给指定代理，没有直连回退。DNS 经同一代理转为 DoH，代理失败时不回退主机 DNS。
- 客机公网 IPv6、普通 UDP、ICMP，以及到主机和局域网的直连受限；当前公网出站支持 IPv4 TCP。SSH 管理、共享文件和本地显示使用明确的内部通道。主动启用 [Tailscale 私网](guide/tailscale.md)后，可按设备和 SSH 权限双向连接，外层通信仍受代理与暂停控制。
- 代理凭据保存在主机私有配置，不传入客机。终端 SSH 禁用本机转义、本机命令、代理转发与交互密码，且不继承主机环境变量。
- 工作台只监听本机 loopback，App 自动换取会话；接口校验 Host、Origin 与会话，外部网页不能直接调用管理操作。
- 明确打开的项目目录及下载暂存目录会共享到同一环境，彼此可以访问。修改、删除共享文件会影响主机，请保留备份。不要把 Cage 私有配置目录或正在运行的控制程序作为共享项目。

网络约束在虚拟机外，客机中的 sudo 不能直接关闭。虚拟机或浏览器漏洞、主机管理员修改配置，以及用户在主机执行共享项目中的脚本，超出这层边界能阻止的范围。Cage 不提供账号封禁预测或避免限制的承诺。镜像化分享和系统时钟伪造尚未提供。

### 播放环境声音

在 Cage 浏览器播放视频或音频时，声音会从本机当前的扬声器或耳机输出。点击底部的扬声器按钮展开音量滑块，调整整个 Cage 环境的音量；展开时再次点击扬声器可以静音或取消静音。鼠标移出控件后滑块自动收起。Claude Desktop 和终端程序共用此控制。若播放受到限制，点击页面后继续播放。

切换标签或项目不会停止声音。静音、停止环境、锁定 Cage 账户或退出应用会断开播放；取消静音后播放当前内容，不补播中断期间的声音。旧环境首次使用时需要更新组件。此功能提供声音输出，不提供本机麦克风输入。

## 升级与卸载

本节的安装包替换与卸载步骤适用于 macOS。Windows 用户参阅 [Windows 更新与卸载](windows.md#更新与卸载)，Linux 用户参阅 [Linux 更新与卸载](linux.md#更新与卸载)；Linux 使用系统安装包手动更新。环境组件与工具仍在各平台共用的工作台设置中更新。

首次安装请下载公开 Release 的 DMG。应用内更新用于后续版本升级。

安装、重装、更新和卸载均保留个人数据。macOS、Windows 和 Linux 默认使用用户主目录下的 `~/.claude-cage/`：本地账户、收藏和设置保存在该目录，浏览器历史、网站登录状态和环境内文件保存在其中的持久虚拟磁盘。更换应用安装位置不会更换默认数据目录；通过 `CLAUDE_CAGE_CONFIG` 指定其他配置时，应始终使用同一配置。终端窗口的临时输出和正在运行的进程不属于磁盘备份。

已创建过账户却再次出现创建页面时，先按[账户与数据目录检查](troubleshooting.md#已有账户却再次显示创建账户)核对目录，不要创建新账户或删除旧配置。

应用会在启动后自动检查更新，运行期间每六小时重查；普通检查失败后每五分钟重试，更新源要求等待时按其指定时间重试，隐藏窗口期间暂停检查。没有新版时不显示更新入口。有新版时，左下角显示金色圆形下载按钮；请先保存文件并结束运行中的任务，再点击一次。按钮会显示环形下载进度和百分比，下载校验完成后自动停止环境、安装并重启，不再弹出确认框。应用更新会结束工作台终端，保留项目、配置、虚拟磁盘和登录状态。失败时显示原因，点击原按钮可重试；限流等待期间按钮禁用，悬浮可查看最早重试时间。

macOS 的 `0.1.3-alpha.1` 及更早公开版本存在本机更新校验错误。遇到“本机更新验证未完成”时，请保存文件、停止环境并退出 Cage，从官方 Release 下载 `0.1.3-alpha.2` 或更新的 DMG，替换原来的应用一次；已有项目和数据会保留。修复版之后可使用应用内更新。

检查和下载使用已经应用并运行的所选代理，失败不会改用主机直连。自动安装要求当前 App 与新 App 使用相同发布者的 Developer ID 签名，且新包通过 Apple 验证；ad-hoc 开发构建不能自动安装。更新器使用公开的 GitHub Releases 接口，无需 GitHub 登录，也不读取浏览器会话。若提示更新源不可访问，先确认所选代理可用，再检查对应 Release 是否仍公开且附件完整；需要手动下载时使用同一公开 Release。实际安装、重启和恢复的验收范围以该版本说明为准。

手动替换 App 前，保存文件并选择“停止环境并退出”。新 App 会核对后台版本；若出现“更新待完成”，可先打开现有环境保存文件，再选择“保存后停止环境并完成更新”。预发行版本间的兼容性和特殊迁移要求以对应 Release 说明为准。

“设置 → 环境与恢复”分别提供环境组件与工具更新，并显示实际版本。组件更新会重启浏览器和编辑器，保留 VM、磁盘和工作台独立终端；编辑器内的集成终端可能结束，操作前需要保存内容。依赖安装和工具更新使用所选代理，无需业务网络已经放行；工具更新采用当前 App 指定的最低版本，人工暂停外网不会被更新操作解除。替换 App 不等于已经升级全部 Linux 工具。

卸载应用前也应先停止环境并退出，再将 Cage.app 移到废纸篓。删除 App 不会自动删除共享项目、下载暂存、代理配置或虚拟磁盘。需要清理这些数据时，先备份：私有状态默认在 `~/.claude-cage/`，下载暂存通常在 `~/.claude-cage-downloads/Downloads/`；原 `~/.claude-cage-workspace/` 中的个人文件也保留，自行打开的项目仍在原目录。删除虚拟磁盘会丢失只存在于客机中的文件和登录状态。

下一步：[常见问题与恢复](troubleshooting.md)