远程 SSH 工作区

把一台远程服务器变成你的 AI 编程工作台——通过 SSH 连上远端主机，直接在服务器上运行 Claude Code / Codex / heng-agent / OpenCode 等 CLI，浏览远端文件、操作远端 Git，所有配置（API 档案 / MCP / Hooks）按工作区独立隔离，本地与远程互不污染。

视频演示：远程 SSH 多机开发 + 多开崩溃自恢复 + 浏览器自动化

完整演示远程工作区的连接、切换与实操，配合本页文字一起看更直观。

在哔哩哔哩观看

为什么需要远程工作区

很多代码并不在本机：部署在云服务器上的项目、公司内网的开发机、家里的 NAS / 软路由。过去你得先 SSH 进去、手动装好 CLI、配好 API Key，才能在远端用 AI 编程。远程工作区把这一整套流程搬进图形界面：

就近运行：AI 工具在代码所在的机器上运行，读写文件、执行命令零延迟，不需要把代码拉回本地
环境隔离：每个工作区（本地 / 远程主机 A / 远程主机 B）有各自的 API 档案、MCP、Hooks，切换工作区即切换整套环境
统一界面：远端会话和本地会话在同一个窗口里，标签栏、状态栏、额度统计一视同仁

工作区的概念

工作区（Workspace）是「一套运行环境」的抽象：

工作区类型	运行位置	配置存储位置
本地	你的电脑	`~/.claude` 等本机目录
远程主机	SSH 连接的远端服务器	远端的 `~/.claude` 等目录

窗口顶部的工作区切换器用来在本地与各远程主机之间切换。切到某个远程工作区后，新建会话、Provider 面板、API 档案、文件浏览全部自动指向该远端主机。

添加远程主机

「设置 → 远程 SSH」→「添加远程主机」（也可以在工作区切换列表里选「连接到新远程主机…」）：

字段	说明	示例
别名	工作区显示名，自取	`dev-server` / `阿里云开发机`
主机地址	IP 或域名	`192.168.1.20` / `dev.example.com`
端口	SSH 端口	`22`
用户名	登录用户	`root` / `ubuntu`
认证方式	密码或 SSH 私钥文件	见下方
代理（可选）	远程主机访问外网的方式，见远程主机的网络代理	`http://127.0.0.1:7890`

添加时即可配密码

添加主机的同时就能填写密码，点「添加并连接」保存后立即发起连接，省去"先添加再单独连"的两步操作；不想现在填可以留空，之后点「连接」时再输入。拿不准能不能连上，可以先点「测试连接」。

连接与认证

支持两种 SSH 认证方式：

方式	配置	适用
密码	填写登录密码。默认只用于本次连接、不进数据库；勾选「记住密码」后存入系统凭据存储（Windows 凭据管理器 / macOS 钥匙串），下次自动登录	临时机器、内网开发机
私钥	指定私钥文件路径（应用只记路径，私钥本身不离开 `~/.ssh/`），私钥加了密就填 Passphrase，也可选择记住	云服务器、安全要求高的环境

首次连接陌生主机时会弹出服务器指纹，请你在服务器上核对一致后点「信任并继续」；之后若服务器指纹变了会再次提示确认，防止中间人攻击。

连接过程随时可以取消 —— 连不上时不必干等几十秒，等锁、握手、重试退避、认证四个阶段都能中断。

打开已有的远程会话时也会自动重连，不会因为「远程主机未连接」而打不开。

连接状态与重新连接

切到一台远程主机后，连接与检测远端工具通常要十几秒，界面上全程有反馈：

时机	你会看到
连接中	工作区切换器上该主机后面显示「连接中…」，状态点呼吸；鼠标悬停可点「取消连接」
连接失败	右上角弹出「远程主机连接失败」通知，写明原因，带「重新连接」和「去设置」两个按钮，不会自动消失
缺少密码	自动连接没拿到凭据时提示「远程主机需要密码」，点「去设置」填写后再连

断线提示

远程 SSH 连接可能因网络波动、服务器休眠而断开。断线时终端会给出明确指引，可在工作区切换器、终端内或主机设置三处重新连接。

远程主机的网络代理

服务器上的 CLI 要访问 api.anthropic.com 这类外网地址时，可以在主机卡片的地球按钮里（添加主机时的「代理（可选）」也是这一项）选择出网方式：

选项	什么时候用
直连	服务器自己能直接访问外网
服务器自己的代理	填一个服务器能用的代理地址（站在服务器的角度，如服务器本机的 `http://127.0.0.1:7890` 或公网代理）
通过本地电脑代理	服务器自己连不上外网时，借用你电脑上「设置 → 网络」里配好的代理出网

保存后在下次启动远程会话时生效。

在远端运行 AI 工具

切换到远程工作区后，新建会话的流程与本地完全一致，区别在于：

运行位置：AI 编程 CLI（Claude / Codex / heng-agent / Grok / Kimi / CodeBuddy / Pi 等）在远端服务器上启动，而非本机
项目路径：新建会话时的"浏览"按钮走 SSH 目录浏览，选择的是远端目录
会话历史：读取的是远端机器上的会话记录

各 Provider 的工具检测、认证状态、版本管理在远程工作区下都会经 SSH 指向远端环境，状态栏的额度统计也支持远程主机（通过把 statusline 部署到远端 ~/.claude）。

远程会话读取：十家全覆盖

远程会话现在和本地一样，标题会自动更新、重开标签页能还原历史。十家 Provider 的会话落盘格式各不相同，AICoder 分别做了适配（Gemini CLI 已停服，远端的历史会话仍可读取）：

Provider	远端读取方式
Claude / Gemini	读远端会话记录文件
Codex	扫远端 rollout 文件（不调 CLI，更快也更稳）
OpenCode	调远端 CLI 查询
Grok	读远端 `summary.json`
Kimi	读远端索引
CodeBuddy / Pi / Antigravity	各按其落盘结构读取
heng-agent	读远端 `~/.heng-agent/sessions/` 下的会话文件（只取头尾一小段，不把整段对话拉回来）

远程会话与本机打通

AI 跑在服务器上，但很多东西在你的电脑上：智码的工具、内置浏览器、你刚截的图。下面这几条让两边接得上。

远程会话也能用智码的 MCP 工具

跑在远程主机上的 Claude Code 会自动接上你电脑上智码的 MCP 服务——内置浏览器、会话与用量数据、代码片段这些工具在远端同样能用。例如让服务器上的 AI 用你电脑上的内置浏览器打开页面、验证改动效果。每次新开远程会话时自动配置，不需要手动操作。

为了安全，远端拿到的是只限这台主机工作区的受限权限：

远端 AI 能做	远端 AI 不能做
用内置浏览器打开网页、点击、读取、截图	读写你电脑上其他项目的文件
查看这台远程主机工作区的会话与用量	在你电脑上启动项目任务或新会话
使用代码片段等	通过浏览器上传 / 打开你电脑上的文件，或把下载存到你电脑的指定目录

注意：

目前只给远端的 Claude Code 自动配置；其他 CLI 在远端暂时用不到这些工具
带过去的只有智码自己的 MCP 工具，你在本机给 CLI 配的其他 MCP 服务器不会带到远端（MCP 按工作区隔离，见下文）

拖拽文件与粘贴图片

在远程会话里拖入文件、粘贴截图时，智码会先把文件传到服务器，再把服务器上的路径交给 CLI——服务器上的 AI 能直接读到，而不是拿到一个服务器上并不存在的本机路径。

传输时窗口顶部提示「正在上传到远程服务器…（1/3）文件名」，完成后提示「已上传 N 个文件到远程服务器」
文件暂存在服务器家目录下的 .tauri-cc-uploads 文件夹，保留 7 天后自动清理；为了能直接写进命令行，文件名会改成只含英文字母、数字和少量符号的形式（中文名会被替换）
暂不支持拖入整个文件夹
上传失败的文件不会写进输入框；图文一起粘贴时如果图片没传上去，文字照常粘贴，并提示「文本已粘贴，图片没进去」

内置浏览器经远程主机出网

内置浏览器可以新开一个网络出口在远程主机上的「隧道标签页」：页里的 localhost 和任意端口都指向那台服务器，访问外网也从服务器出去。在浏览器工具栏点主页按钮，选「主机别名的 localhost」即可，详见内置浏览器自动化 · 经远程主机出网。

接管服务器上的外部会话

在服务器终端里直接跑出来的 CLI 会话（不是在智码里创建的），也能在远程工作区里发现并接管（已停服的 Gemini CLI 不能再续聊，其余各家都支持），接管后像普通会话一样接着聊。远程主机上按工具逐家扫描，切换工具会重新扫描。入口与用法见多标签会话管理。

配置按工作区隔离

这是远程工作区的核心：每个工作区有独立的一整套配置，互不干扰。

配置项	隔离粒度
API Profile（API Key / OAuth 档案）	每个工作区独立列表，切档案写到对应机器的配置文件
MCP Server	各 CLI 的 MCP 按工作区隔离
Hooks	Claude Hooks 按工作区隔离
OAuth 登录态	切换工作区时清理本地 `ANTHROPIC_*` 环境变量，避免本地凭据泄漏到远端

在远程工作区里切换 API 档案、导入分享的配置档案、改 MCP，都会真正写到远端的 settings.json / ~/.claude.json，而不是本机。

远程主机上的账号：登录、保存、切换

各家 CLI 的官方账号也能直接在远程主机上登录和切换，凭据写在服务器上，档案归该远程工作区：

工具	在远程工作区里
Claude Code	「添加新账号」在内置终端里登录远端的 Claude，授权链接在你本机浏览器打开，凭据存到远程主机的 `~/.claude/`；OAuth 档案切换会真正写到远端
Codex	「添加新账号」在内置终端里发起远端登录：弹窗给出登录链接和「一次性码」，复制后在你本机浏览器完成授权即可，服务器上不需要浏览器、也不需要额外配置；授权成功后自动识别新账号，「保存为档案」后即可一键切换，凭据写到远程主机
Grok / Kimi / Pi	切换档案写到远端对应的配置文件，不再改到本机

添加账号前需要先连上该远程主机。远程登录时不显示「登录走代理」开关，联网走的是远程主机自己的出网设置（见远程主机的网络代理）。

MCP 配置：八家可视化管理

八家 CLI（Claude / Codex / Gemini / OpenCode / Kimi / Grok / Pi / CodeBuddy / Antigravity）的 MCP 服务器都能在远程主机上直接增删改，配置写到远端对应的文件。Pi 本身不带 MCP 能力，AICoder 会连同自研的桥接扩展一并写到远端。

原生配置编辑器读写远端

Provider 的原生配置文件编辑器（直接改 settings.json 这类文件）也接入了工作区 —— 切到远程主机时编辑的是远端文件。

未接通的入口一律停用

如果某个功能还没有远程实现，在远程工作区下会被明确停用而不是照常放行 —— 否则你以为在配远端，实际悄悄改了本机配置。

档案空态与从本地导入

远程主机第一次用时档案列表是空的，界面会说清「为什么是空的」，而不是让你以为配置丢了。新建会话时如果这台远程主机没配该工具的档案，也会提前提示。

「从本地导入」可以把本机配好的端点搬到远程主机：逐条挑选，其中像 127.0.0.1 这类搬过去会指向远端自己的地址会显眼标红，可以在导入时就地改掉。

远端会话的保持与重启

远端会话默认开启 tmux 持久化：关掉应用后服务器上的会话照常在跑，下次打开自动接回。主机卡片上的闪电按钮打开「远程会话」管理面板：

项目	说明
tmux 持久化	关掉后断开连接即结束会话，但每次都从新连接启动——服务器给你加了用户组、改了权限后能立刻生效。修改在下次启动远程会话时生效
远端活跃会话	列出本应用在这台主机上的会话，可逐个「结束」
重置远程会话	一次结束本应用在这台主机上的全部远程会话，用于「改了权限却不生效」；里面正在跑的编译、训练等任务会被中断，你自己手动开的 tmux 和其他同事的会话不受影响
旧版遗留会话	很早的版本建立的会话新版接不回来、会一直在后台跑，确认不需要后在这里清理

重启会话

会话标签右键菜单里的「重启会话」，在远程 tmux 会话上会真正重启：先结束服务器上原来的会话进程，再按原会话恢复，对话历史保留。CLI 卡住、改了配置要重启生效时直接用它。

远程文件浏览与 Git

切到远程工作区后，工作区编辑器的文件树、编辑器、Git 面板、终端全部作用于远端：

文件树：浏览远端目录，支持新建 / 删除 / 重命名、右键菜单
目录选择器：带面包屑导航、历史记录、新建目录、隐藏文件切换，~ 与 $HOME 会正确展开
Git 操作：在远端仓库查看状态、diff、提交、切分支
远端终端：基于 tmux，开启了鼠标支持，滚轮可翻历史；中文输入与显示正常（服务器默认编码不是 UTF-8 时会自动处理）

远端终端跟随你的登录 shell（v5.1.6+）

远程会话的宿主 shell 会按远端用户真实的登录 shell 来起，不再一律写死 bash。

zsh 用户（包括绝大多数 oh-my-zsh 用户）此前拿到的永远是 bash：PATH、nvm 前缀、别名全写在 ~/.zshrc 里，bash 一行都读不到，于是远端明明装好的 CLI 一跑就是 command not found。现在会读到正确的配置。

远程文件传输（SFTP，v5.2.0+）

以前远程工作区只有终端，传个文件得自己敲 scp；主界面直连远程主机时更是连入口都没有。现在内嵌工作区栏里有一个「远程文件」视图：

能力	说明
浏览	面包屑导航 + 大小 / 时间 / 权限三列（面板窄到一定程度会逐级隐藏列）
上传 / 下载	分片流式传输，带进度显示，可中途取消
在工作区打开	右键菜单直接把远端文件在编辑器里打开
改权限	chmod 弹窗，八进制输入与 rwx 勾选矩阵双向联动，实时预览 `-rwxr-xr-x`
增删改名	新建目录、删除、重命名、复制远端路径

传输中断不会留下半个文件

上传下载先写 .part 临时文件，完成后原子替换成目标名。中途取消或断线都会清掉 .part，不会留下一个看起来正常、其实只有一半的文件。

在本地工作区下这个视图是置灰而不是隐藏——让你知道有这个能力，切到远程主机就能用。

远程一键安装 Node / CLI

远端机器没装环境也不要紧——Provider 面板提供一键安装：

安装 Node.js：可选版本，默认 22 LTS（应用要求 Node ≥ 20）
安装 AI CLI：选定版本后通过 SSH 在远端安装 Claude / Codex / heng-agent / OpenCode / Antigravity / Grok 等
实时日志：安装过程的 SSH 输出实时显示在面板里，失败原因一目了然

安装历史里的版本 Tag 可点击，回填到版本选择框，方便重装或切换。

装在哪台机器上，取决于当前工作区

切到远程工作区后点安装，装的就是远端；这一点对所有工具一致，不会出现"点了安装却装到本机"的情况。

远端主机的 PATH 探测也做了归一：检测、安装、启动三处用同一套解析结果，不再各猜各的。若自动探测仍找不到，可以按主机手填工具路径。

故障排查

现象	排查方向
装了 CLI 却检测不到	环境探测用 login shell 执行；确认 CLI 在远端 PATH 中（重连后重试检测）
远程 Claude 启动报 root 拒绝	远端以 root 运行时会自动注入 `IS_SANDBOX=1` 绕过限制
切换工具/档案不生效	确认当前处在目标远程工作区；远程切档案会写远端配置
终端鼠标滚轮无反应	远端 tmux 已默认开启鼠标支持，若仍无效尝试重连
reopen 报 Session ID 已被占用	会话存在性检查已感知工作区，重连后重试
连接频繁断开	检查服务器是否休眠、网络稳定性；按提示重新连接
一直停在「连接中…」	悬停工作区切换器上的该主机点「取消连接」，检查主机地址、端口与防火墙后再点「重新连接」
远程终端里输入中文变成下划线	新版已自动处理（远端终端强制 UTF-8，服务器默认编码不是 UTF-8 时自动补上）；老会话仍有问题时右键「重启会话」
mac 上远程终端拖选文字一松手就消失	远端程序开了鼠标功能时会接管拖选，按住 Option 再拖选即可复制
远程会话里的 AI 说没有智码的工具	目前只给远端 Claude Code 自动接入；确认服务器的 SSH 服务没有关闭转发功能（sshd 配置里的 `AllowTcpForwarding`），然后新开一个会话
拖进来的文件夹没有传上去	暂不支持整个文件夹，改为选中其中的文件拖入，或用「远程文件」视图上传
远程主机改了用户组 / 权限后不生效	在主机卡片的「远程会话」面板里「重置远程会话」，或关闭 tmux 持久化