远程 SSH 工作区
把一台远程服务器变成你的 AI 编程工作台——通过 SSH 连上远端主机，直接在服务器上运行 Claude Code / Codex / Gemini / OpenCode，浏览远端文件、操作远端 Git，所有配置（API 档案 / MCP / Hooks）按工作区独立隔离，本地与远程互不污染。
为什么需要远程工作区
很多代码并不在本机：部署在云服务器上的项目、公司内网的开发机、家里的 NAS / 软路由。过去你得先 SSH 进去、手动装好 CLI、配好 API Key，才能在远端用 AI 编程。远程工作区把这一整套流程搬进图形界面：
- 就近运行：AI 工具在代码所在的机器上运行，读写文件、执行命令零延迟，不需要把代码拉回本地
- 环境隔离：每个工作区（本地 / 远程主机 A / 远程主机 B）有各自的 API 档案、MCP、Hooks，切换工作区即切换整套环境
- 统一界面：远端会话和本地会话在同一个窗口里，标签栏、状态栏、额度统计一视同仁
工作区的概念
工作区（Workspace）是「一套运行环境」的抽象：
| 工作区类型 | 运行位置 | 配置存储位置 |
|---|---|---|
| 本地 | 你的电脑 | ~/.claude 等本机目录 |
| 远程主机 | SSH 连接的远端服务器 | 远端的 ~/.claude 等目录 |
窗口顶部的工作区切换器用来在本地与各远程主机之间切换。切到某个远程工作区后，新建会话、Provider 面板、API 档案、文件浏览全部自动指向该远端主机。
添加远程主机
设置 → 远程主机 → 「添加主机」：
| 字段 | 说明 | 示例 |
|---|---|---|
| 名称 | 工作区显示名，自取 | 阿里云开发机 |
| 主机地址 | IP 或域名 | 192.168.1.20 / dev.example.com |
| 端口 | SSH 端口 | 22 |
| 用户名 | 登录用户 | root / ubuntu |
| 认证方式 | 密码 或 私钥 | 见下方 |
添加时即可配密码
添加主机的同时就能填写密码，保存后切换到该工作区会自动发起连接，省去"先添加再单独连"的两步操作。
连接与认证
支持两种 SSH 认证方式：
| 方式 | 配置 | 适用 |
|---|---|---|
| 密码 | 直接填写登录密码（加密存于本地） | 临时机器、内网开发机 |
| 私钥 | 指定私钥文件路径，必要时填私钥口令 | 云服务器、安全要求高的环境 |
首次连接陌生主机时会记录其 host key 到 known_hosts，后续连接据此校验，防止中间人攻击。
断线提示
远程 SSH 连接可能因网络波动、服务器休眠而断开。断线时终端会给出明确指引，可在工作区切换器、终端内或主机设置三处重新连接。
在远端运行 AI 工具
切换到远程工作区后，新建会话的流程与本地完全一致，区别在于：
- 运行位置：Claude / Codex / Gemini / OpenCode 在远端服务器上启动，而非本机
- 项目路径：新建会话时的"浏览"按钮走 SSH 目录浏览，选择的是远端目录
- 会话历史：读取的是远端机器上的会话记录
四个 Provider 的工具检测、认证状态、版本管理在远程工作区下都会经 SSH 指向远端环境，状态栏的额度统计也支持远程主机（通过把 statusline 部署到远端 ~/.claude）。
配置按工作区隔离
这是远程工作区的核心：每个工作区有独立的一整套配置，互不干扰。
| 配置项 | 隔离粒度 |
|---|---|
| API Profile（API Key / OAuth 档案） | 每个工作区独立列表，切档案写到对应机器的配置文件 |
| MCP Server | Claude / Codex / Gemini 的 MCP 按工作区隔离 |
| Hooks | Claude Hooks 按工作区隔离 |
| OAuth 登录态 | 切换工作区时清理本地 ANTHROPIC_* 环境变量，避免本地凭据泄漏到远端 |
在远程工作区里切换 API 档案、导入分享的配置档案、改 MCP，都会真正写到远端的 settings.json / ~/.claude.json，而不是本机。
远程文件浏览与 Git
切到远程工作区后，工作区编辑器的文件树、编辑器、Git 面板、终端全部作用于远端：
- 文件树：浏览远端目录，支持新建 / 删除 / 重命名、右键菜单
- 目录选择器：带面包屑导航、历史记录、新建目录、隐藏文件切换，
~与$HOME会正确展开 - Git 操作：在远端仓库查看状态、diff、提交、切分支
- 远端终端：基于 tmux，开启了鼠标支持，滚轮可翻历史
远程一键安装 Node / CLI
远端机器没装环境也不要紧——Provider 面板提供一键安装：
- 安装 Node.js：可选版本，默认 22 LTS（应用要求 Node ≥ 20）
- 安装 AI CLI：选定版本后通过 SSH 在远端安装 Claude / Codex / Gemini / OpenCode
- 实时日志：安装过程的 SSH 输出实时显示在面板里，失败原因一目了然
安装历史里的版本 Tag 可点击，回填到版本选择框，方便重装或切换。
故障排查
| 现象 | 排查方向 |
|---|---|
| 装了 CLI 却检测不到 | 环境探测用 login shell 执行；确认 CLI 在远端 PATH 中（重连后重试检测） |
| 远程 Claude 启动报 root 拒绝 | 远端以 root 运行时会自动注入 IS_SANDBOX=1 绕过限制 |
| 切换工具/档案不生效 | 确认当前处在目标远程工作区；远程切档案会写远端配置 |
| 终端鼠标滚轮无反应 | 远端 tmux 已默认开启鼠标支持，若仍无效尝试重连 |
| reopen 报 Session ID 已被占用 | 会话存在性检查已感知工作区，重连后重试 |
| 连接频繁断开 | 检查服务器是否休眠、网络稳定性；按提示重新连接 |
相关章节
- 工作区编辑器 — 文件树 / 代码编辑 / Git / 终端的完整能力
- 多 AI 工具统一管理 — 四大工具在本地与远程的检测与切换
- 配置档案管理 — API 档案如何按工作区隔离
- MCP Server 管理 — MCP 配置的工作区隔离