远程 SSH 工作区
把一台远程服务器变成你的 AI 编程工作台——通过 SSH 连上远端主机，直接在服务器上运行 Claude Code / Codex / Gemini / OpenCode，浏览远端文件、操作远端 Git，所有配置（API 档案 / MCP / Hooks）按工作区独立隔离，本地与远程互不污染。
视频演示：远程 SSH 多机开发 + 多开崩溃自恢复 + 浏览器自动化
完整演示远程工作区的连接、切换与实操，配合本页文字一起看更直观。
为什么需要远程工作区
很多代码并不在本机：部署在云服务器上的项目、公司内网的开发机、家里的 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 工具
切换到远程工作区后，新建会话的流程与本地完全一致，区别在于：
- 运行位置：九家 CLI（Claude / Codex / Gemini / Grok / Kimi / CodeBuddy / Pi 等）在远端服务器上启动，而非本机
- 项目路径：新建会话时的"浏览"按钮走 SSH 目录浏览，选择的是远端目录
- 会话历史：读取的是远端机器上的会话记录
各 Provider 的工具检测、认证状态、版本管理在远程工作区下都会经 SSH 指向远端环境，状态栏的额度统计也支持远程主机（通过把 statusline 部署到远端 ~/.claude）。
远程会话读取：九家全覆盖
远程会话现在和本地一样，标题会自动更新、重开标签页能还原历史。九家 Provider 的会话落盘格式各不相同，AICoder 分别做了适配：
| Provider | 远端读取方式 |
|---|---|
| Claude / Gemini | 读远端会话记录文件 |
| Codex | 扫远端 rollout 文件（不调 CLI，更快也更稳） |
| OpenCode | 调远端 CLI 查询 |
| Grok | 读远端 summary.json |
| Kimi | 读远端索引 |
| CodeBuddy / Pi / Antigravity | 各按其落盘结构读取 |
配置按工作区隔离
这是远程工作区的核心：每个工作区有独立的一整套配置，互不干扰。
| 配置项 | 隔离粒度 |
|---|---|
| API Profile（API Key / OAuth 档案） | 每个工作区独立列表，切档案写到对应机器的配置文件 |
| MCP Server | 各 CLI 的 MCP 按工作区隔离 |
| Hooks | Claude Hooks 按工作区隔离 |
| OAuth 登录态 | 切换工作区时清理本地 ANTHROPIC_* 环境变量，避免本地凭据泄漏到远端 |
在远程工作区里切换 API 档案、导入分享的配置档案、改 MCP，都会真正写到远端的 settings.json / ~/.claude.json，而不是本机。
MCP 配置：八家可视化管理
八家 CLI（Claude / Codex / Gemini / OpenCode / Kimi / Grok / Pi / CodeBuddy / Antigravity）的 MCP 服务器都能在远程主机上直接增删改，配置写到远端对应的文件。Pi 本身不带 MCP 能力，AICoder 会连同自研的桥接扩展一并写到远端。
原生配置编辑器读写远端
Provider 的原生配置文件编辑器（直接改 settings.json 这类文件）也接入了工作区 —— 切到远程主机时编辑的是远端文件。
未接通的入口一律停用
如果某个功能还没有远程实现，在远程工作区下会被明确停用而不是照常放行 —— 否则你以为在配远端，实际悄悄改了本机配置。
档案空态与从本地导入
远程主机第一次用时档案列表是空的，界面会说清「为什么是空的」，而不是让你以为配置丢了。新建会话时如果这台远程主机没配该工具的档案，也会提前提示。
「从本地导入」可以把本机配好的端点搬到远程主机：逐条挑选，其中像 127.0.0.1 这类搬过去会指向远端自己的地址会显眼标红，可以在导入时就地改掉。
远程文件浏览与 Git
切到远程工作区后，工作区编辑器的文件树、编辑器、Git 面板、终端全部作用于远端：
- 文件树：浏览远端目录，支持新建 / 删除 / 重命名、右键菜单
- 目录选择器：带面包屑导航、历史记录、新建目录、隐藏文件切换，
~与$HOME会正确展开 - Git 操作：在远端仓库查看状态、diff、提交、切分支
- 远端终端：基于 tmux，开启了鼠标支持，滚轮可翻历史
远程一键安装 Node / CLI
远端机器没装环境也不要紧——Provider 面板提供一键安装：
- 安装 Node.js：可选版本，默认 22 LTS（应用要求 Node ≥ 20）
- 安装 AI CLI：选定版本后通过 SSH 在远端安装 Claude / Codex / Gemini / OpenCode / Antigravity / Grok 等
- 实时日志：安装过程的 SSH 输出实时显示在面板里，失败原因一目了然
安装历史里的版本 Tag 可点击，回填到版本选择框，方便重装或切换。
装在哪台机器上，取决于当前工作区
切到远程工作区后点安装，装的就是远端；这一点对所有工具一致，不会出现"点了安装却装到本机"的情况。
远端主机的 PATH 探测也做了归一：检测、安装、启动三处用同一套解析结果，不再各猜各的。若自动探测仍找不到，可以按主机手填工具路径。
故障排查
| 现象 | 排查方向 |
|---|---|
| 装了 CLI 却检测不到 | 环境探测用 login shell 执行；确认 CLI 在远端 PATH 中（重连后重试检测） |
| 远程 Claude 启动报 root 拒绝 | 远端以 root 运行时会自动注入 IS_SANDBOX=1 绕过限制 |
| 切换工具/档案不生效 | 确认当前处在目标远程工作区；远程切档案会写远端配置 |
| 终端鼠标滚轮无反应 | 远端 tmux 已默认开启鼠标支持，若仍无效尝试重连 |
| reopen 报 Session ID 已被占用 | 会话存在性检查已感知工作区，重连后重试 |
| 连接频繁断开 | 检查服务器是否休眠、网络稳定性；按提示重新连接 |
相关章节
- 工作区编辑器 — 文件树 / 代码编辑 / Git / 终端的完整能力
- 多 AI 工具统一管理 — 九家工具在本地与远程的检测与切换
- 配置档案管理 — API 档案如何按工作区隔离
- MCP Server 管理 — MCP 配置的工作区隔离