# 远程 SSH 模式 选中一个「远程 SSH」容器后，AiCode 进入远程工作区模式：AI 的**读写文件、执行命令、运行终端均发生在远程服务器上**，`~/workspace` 映射到服务器上的指定目录，手机仅作为操作界面。 适用于服务器上已有完整工具链，或需要 AI 直接修改远程项目的场景。 ## 前置：先建一个 SFTP 通道 远程 SSH 复用「连接与同步」页中 **SFTP** 通道的连接信息（主机、端口、用户名、密码），需先在该页建好一个 SFTP 连接，见[工作区同步](https://aicode.murk.top/md/guide/sync.md)。 FTP 通道不支持执行命令，不会出现在可选列表中。 ## 新建远程 SSH 容器 在「设置 → 容器与镜像」点击右上角 +，选「远程 SSH」： - **名称**：配置的别名。 - **SSH 连接通道**：下拉选择一个已配置的 SFTP 通道。无可用通道时，界面提示先前往「连接与同步」页配置，且保存按钮不可用。 - **远程工作区路径**：服务器上的目录，AI 的 `~/workspace` 映射到此。选中通道时会自动填入默认值 `~/.aicode/workspaces`（按服务器上该用户的真实 home 解析，如 root 用户为 `/root/.aicode/workspaces`），可修改。 保存后在列表中选中即生效。 认证方式沿用所选 SFTP 通道的配置，支持**密码认证**与**SSH 私钥认证**（含带密码保护的私钥）。 ## 连接行为 - **自动连接**：App 启动时若当前为远程模式，会在后台自动连接；连接失败不会阻塞界面，首次执行命令时会重试。 - **保活与自动重连**：连接后每 30 秒发送一次心跳，防止空闲断连；断线后由后台自动重连（5 秒起、最长 30 秒的退避间隔），App 回到前台时也会立即重试一次。 - **状态显示**：对话页顶部显示「SSH：已连接 / 连接中 / 连接失败 / 未连接」。未连接时消息区显示等待提示。 - **两条独立连接**：文件读写走 SFTP，终端与命令走 exec，各占一条 SSH 连接、互不影响；文件通道异常时自动重建，不中断正在运行的命令。 - **路径自举**：远程工作区路径不存在时自动创建；若该目录下无任何子目录，会自动创建一个名为 `default` 的工作区，保证 AI 始终有可用的 `~/workspace`。 ## 本地数据与跟随执行环境的数据 远程模式下命令、文件、终端与工作区均在服务器上。大多数配置仍存于手机本地；少数「执行环境资源」则跟随环境、以远端为准： | 项目 | 说明 | | --- | --- | | 聊天历史、模型与供应商配置、API Key、应用设置 | 全部本地 | | 记忆（memory） | 本地。项目级记忆按「项目名 + 服务器标识」隔离，不同服务器上的同名工作区不会混淆 | | 全局技能、子代理与面板脚本 | **跟随执行环境**：远程模式下读写**服务器**上的 `~/.aicode/skills/`、`~/.aicode/agents/`、`~/.aicode/scripts/`，与本地模式的那份互相独立 | | 项目级技能与子代理 | 直接读写**服务器工作区**中的 `<工作区>/.aicode/skills/`、`agents/`，可随代码库提交到 git | | 项目级配置（工具授权规则 / MCP / 技能与子代理的停用名单） | 手机本地。远程模式按「项目名 + 服务器标识」隔离在 App 私有目录下，不写入服务器 | | MCP 服务器 | HTTP 类型由 App 直接连接；stdio 类型运行在「默认容器」上（见下），不在远程服务器 | | 日志与工具输出 | 本地 | 连接成功后，AiCode 会将内置文档同步到服务器的 `~/.aicode/docs/`，远程模式下 AI 也可查阅这些说明文档。 ## 默认容器 远程模式下仍有部分功能需在本地运行，例如 stdio 类型的 MCP server。它们运行在**默认容器**上，默认为内置 Alpine，可在容器列表下方的「默认容器」分组中改为任意本地容器。 切换容器（包括切到远程 SSH）后，所有 stdio MCP 会自动断开并用新容器重连；HTTP MCP 不依赖容器，不受影响。 ## Git 署名与凭据的去向 Git 页面中保存的**署名**会写入当前执行环境——远程模式下即写入服务器的 git 配置。 **凭据**以手机本地的凭据文件为唯一来源。远程模式下可在凭据页开启「自动注入凭证」（按服务器分别记忆，首次进入时询问），将凭据同步到服务器，且仅对工作区目录下的仓库生效，不影响服务器上其它目录的仓库，也不改动服务器用户的全局 git 配置。