通过 SSH 控制远程节点

“远程节点”让一台 OcHub 桌面版控制没有桌面环境的机器。远端只需运行 OpenSSH； 如果尚未安装 ochcli，桌面版可以在确认后通过 SSH 一键安装。AI 编程工具、配置文件 和凭据仍然留在远端执行环境中。

它尤其适合 WSL、Linux 开发机、远程工作站：以后更换 API 端点时，不必每次都先 SSH 登录、寻找配置文件再手动修改。直接在 OcHub 里选择那台机器，然后切换远端已经 存在的连接即可。

为什么使用远程节点

远程节点既保留开发环境的边界，又提供统一的图形控制入口：

• 无需手改远端配置，即可切换开发机上的 Claude Code、Codex、OpenCode 等工具。
• 连接前就能看到节点是否在线、ochcli 版本和运行平台。
• 应用前预览具体会改写哪个远端配置。
• 启停远端 OcHub 网关，并运行远端诊断。
• 复用已有的 OpenSSH 别名、SSH Agent、ProxyJump、系统钥匙串和硬件密钥。

关闭 OcHub 不会把工具迁回本机。切换动作改写的是所选远程节点上工具的原生配置， 因此远端工具之后仍会继续使用新连接。

当前版本可以管理什么

远程节点目前支持：

工作区下拉会作用于现有的业务页面；页面中的数据库、工具配置、会话、路径和网络请求 都属于所选节点。桌面自身的语言、托盘、登录启动、主题，以及“在 Finder 中打开” 这类操作仍属于控制端，这是有意保留的设备边界。

OcHub 不会提供任意 Shell 执行，也不会自动建立 Gateway 数据面隧道。桌面端可与旧节点 协商它们已经广告的能力；完整工作区需要新版远端 ochcli。缺少 CLI 或版本过旧时， 连接行会给出明确原因，并可直接安装或升级受管版本。

使用前提

请准备好：

• 控制端安装 OcHub Desktop 0.4.22 或更高版本。
• 控制端能使用系统 ssh 和 ssh-keyscan。
• 远端运行可访问的 OpenSSH Server。
• 远端用户目录可写，以便 OcHub 一键安装受管 ochcli；也可以预先手动安装。
• SSH 密钥或 Agent 鉴权可以在不交互输入密码的情况下完成。OcHub 使用 BatchMode=yes 连接。
• 如果要切换连接，远端 OcHub 数据库中至少已有一个 Provider。

先在控制端终端验证 OcHub 将要使用的同一条路径：

ssh -V
ssh -o BatchMode=yes devbox ochcli remote probe

把 devbox 替换为你的 SSH 别名。第二条命令应直接返回节点、Runtime、版本、Policy 和 Capability 信息，不能再询问密码或私钥口令。

在远端安装 ochcli

通常不需要先登录远端安装。先按后文添加 SSH 节点；如果探测结果是“远端尚未安装 OcHub CLI”，点击安装。OcHub 会检测系统和 CPU 架构，在桌面端下载并验证官方签名， 再经已固定主机密钥的 SSH 连接上传。安装只写入当前 SSH 用户的目录，不使用 sudo， 不会开放端口。完成后会启动 Owner、用远程协议验证实际版本，并把稳定绝对路径保存到 节点记录中，因此非交互 Shell 的 PATH 没有 ~/.local/bin 也能正常连接。

版本过旧、文件没有执行权限或 CPU 架构不匹配时，同一个入口会显示为升级并重新安装 正确平台的受管版本。无法使用桌面下载地址或自动安装不支持的平台时，再使用下面的手动 方式。

从最新发布页下载适合远端平台的 无桌面 CLI 压缩包。包内只有一个 ochcli。Linux 或 WSL 可以这样安装：

tar -xzf OcHub_*_linux_x86_64_cli.tar.gz
chmod +x ochcli
./ochcli node install

ochcli version
ochcli node status
ochcli remote probe

安装器会在用户目录中保留各版本，通过稳定的 current 入口原子切换当前版本，并提供 ~/.local/bin/ochcli。平台可用时会安装 launchd 或 systemd 用户服务；没有 systemd 的 WSL 会使用后台 Owner，WSL 重启后由下一次 SSH 会话重新启动。

请确保非交互 SSH 的 PATH 包含 ~/.local/bin。添加节点时也可以填写受管 ochcli 的绝对路径，这是解决“ochcli not found”最可靠的方法。

如果远端工具已经有可用的实时配置，连接前先把它导入远端 OcHub 数据库：

ochcli app list
ochcli provider import-live --app codex
ochcli provider list --app codex

把 codex 换成实际的应用 ID。需要新增更多远端连接时运行 ochcli provider add --help。密钥应直接在远端输入，不要通过桌面控制连接复制。

不需要再下载第二个 daemon 二进制，也无需手工启动。受管的同一个 ochcli 会运行 持久 Owner；正常的第一次远程会话会在需要时启动它。

准备 SSH 连接

在控制端电脑的 SSH 配置中添加一个明确的别名：

Host devbox
    HostName 192.0.2.40
    User alice
    Port 22
    IdentityFile ~/.ssh/id_ed25519
    ServerAliveInterval 30

OcHub 会读取 ~/.ssh/config 和其中的 Include 文件。在 Windows 上，它指的是 %USERPROFILE%\.ssh\config，不是 WSL 内的 /home/<user>/.ssh/config。添加弹窗 只列出明确的 Host 别名；纯通配符段仍可提供默认值，但不会单独显示成一台机器。

ProxyJump、SSH Agent、系统钥匙串、ControlMaster 和硬件密钥仍由系统 OpenSSH 处理。 打开 OcHub 前，先确认下面的命令成功：

ssh -o BatchMode=yes devbox ochcli remote probe

添加并连接节点

1. 在 OcHub 侧栏打开远程节点。
2. 点击添加。OcHub 会读取控制端的 SSH 配置，并列出发现的明确别名。
3. 选择一个别名后点击添加，或使用左下角的手动添加。
4. 手动添加时填写节点名称、SSH 目标、用于扫描密钥的真实主机名或 IP、SSH 端口，以及 远端 ochcli 路径。
5. OcHub 会运行 ssh-keyscan，显示每种主机密钥类型和 SHA256 指纹。请通过云控制台、 管理员或其他可信渠道核对。
6. 只有指纹一致时才点击信任并连接。

确认后的密钥保存在 OcHub 专用的 ~/.ochub/ssh/known_hosts 中，并使用私有权限。 你原有 ~/.ssh/known_hosts 里的记录仍然有效。OcHub 不会静默使用 StrictHostKeyChecking=no。

随后，连接列表会显示实时在线状态、ochcli 版本、平台和上次成功连接时间。侧栏顶部 的工作区下拉可以在这台 Mac和已保存的远程节点之间切换。

连接失败时，列表显示翻译后的故障类型，例如 CLI 未安装、节点需要升级、桌面端需要 升级、SSH 鉴权失败、主机密钥变化、连接超时或系统库不兼容。点击查看详情可查看 处理建议、SSH 退出码和原始诊断；原始错误不会再挤占连接行。可自动恢复的 CLI 问题会 同时显示安装或升级。

如果所选节点离线、SSH 握手超时或能力协商失败，业务页面会立即清空该节点的缓存数据， 并禁用远端写操作。OcHub 绝不会自动回退到这台 Mac 执行；请先重新连接节点，再继续 Provider、网关、设置、同步、工具或更新操作。

切换工作区后，请把页面中的路径理解为所选节点上的路径。例如 Tools 中的 SQL 导入 /srv/backup/OcHub.sql、Settings 中的数据目录，以及同步/备份文件都在远端解析， 不会使用控制端的 HOME。只有文件选择器、打开网页、打开 Finder 和桌面偏好仍在控制端。

一键更新远程节点

节点支持受管更新时，连接行会显示已安装的 ochcli 版本和更新入口。OcHub 会先读取 节点版本与目标平台，再获取经过签名的 headless.json 发布清单。弹窗提供三种策略：

• 自动选择：节点能访问对应发布文件时直接下载，否则使用桌面中继。
• 在节点下载：让远端节点自行下载签名后的可执行文件。
• 通过本机中继：桌面端下载并校验正确平台的文件，再通过 SSH 传给节点。

中继不会只信任桌面端：节点会再次核对目标节点 ID、平台、字节数、SHA-256 和发布签名。 两条路径都会原子切换稳定的 current 入口、重启 Owner，并检查它报告的新版本；健康 检查失败会自动恢复上一个版本。也可以在节点手动回滚：

ochcli --yes node rollback

安装更新默认已由策略允许。如果要禁用，请设置 allowUpdateInstall = false 并重新连接。 早于受管更新功能的旧节点可以直接在连接行点击升级完成首次受管安装； 后续版本再使用更新弹窗的直连/中继策略。受管安装和自更新目前支持 macOS 和 Linux （包括 WSL）。

切换远端节点上的连接

1. 在工作区下拉或远程节点连接列表中选择目标节点。
2. 连接后，选择要修改的远端应用。
3. 找到远端已有的 Provider，点击预览切换。
4. 核对目标节点、SSH 别名、当前连接、目标连接、配置路径和 Revision。
5. 点击确认应用。
6. 刷新，或在远端工具中发起一条短请求，验证新连接。

真正应用前，OcHub 会再次检查 Revision。如果工具或其他进程在预览后修改了配置，本次 应用会被拒绝，不会覆盖新状态。请刷新节点、检查新的当前状态，再重新生成预览。

写操作还带有 Idempotency Key 和远端 Operation Journal。如果应用过程中 SSH 断开， 请先重连并查看最近操作，再决定是否重试；协议可以返回已记录结果，而不是盲目重复 执行同一次写入。

操作远端网关与诊断

节点详情会显示远端网关状态。启动网关会在远端 Owner 中运行它；停止只影响该节点。 这适合 AI 工具已经指向 WSL 或开发机本地回环网关的场景。

SSH 控制会话不会把远端网关自动暴露给控制端。如果确实需要从控制端访问，请先确认 远端端口，再另开一条显式隧道：

ssh -N -L 8765:127.0.0.1:<remote-port> devbox

运行诊断会合并远端 ochcli doctor 结果与 SSH 会话诊断。最近操作会显示远端 Actor、时间、Operation ID 和结果，但不会把 Provider Secret 复制到桌面端。

WSL 配置示例

如果 Windows 上运行 OcHub Desktop，并控制某个 WSL 发行版：

1. 在 WSL 内安装并启动 OpenSSH Server：

   sudo apt update
   sudo apt install openssh-server
   sudo service ssh start

   如果该发行版启用了 systemd，也可用 sudo systemctl enable --now ssh 代替最后一条命令。

2. 按前文说明，在 WSL 内用 ochcli node install 安装单个 ochcli。

3. 配置从 Windows 到 WSL Linux 用户的密钥鉴权。

4. 把别名写入 Windows %USERPROFILE%\.ssh\config：

   Host wsl-dev
       HostName 127.0.0.1
       User <your-wsl-user>
       Port 22
       IdentityFile ~/.ssh/id_ed25519

5. 在 PowerShell 测试：

   ssh -o BatchMode=yes wsl-dev ochcli remote probe

6. 在 OcHub 的远程节点弹窗里添加 wsl-dev。

如果 Windows 本身已占用 22 端口，请让 WSL sshd 使用其他端口，并同步修改 SSH 别名。WSL 发行版停止或 sshd 未运行时，节点会显示离线；连接前先启动发行版和 SSH 服务。OcHub 使用 Windows OpenSSH，不会自动调用 wsl.exe 唤醒发行版。

这样 Claude Code 或 Codex 可以完整留在 WSL 中运行——Linux 路径、凭据、会话和进程 都不迁移——但切换 Provider 变成桌面端的两次点击。

安全与远端策略

远程节点不会新增 HTTP/TCP 管理监听端口。SSH 负责传输加密、主机认证和用户认证； OcHub 只在 SSH 进程的 stdin/stdout 上运行白名单化的 ochcli remote serve --stdio 协议。请求是类型化操作，不是 Shell 命令字符串。

默认策略允许读取状态、运行诊断、切换 Provider（含新 Secret）、管理网关生命周期和安装更新； 备份恢复默认关闭。在远端查看有效策略：

ochcli remote policy show
ochcli remote policy validate

可选策略文件位于 ~/.ochub/remote.toml。只读节点可以这样配置：

schemaVersion = 1
enabled = true
allowWrite = false
allowGatewayLifecycle = false
allowBackupRestore = false
allowUpdateInstall = false

设置 enabled = false 可以完全拒绝远程节点会话。普通 SSH 账号仍然拥有对应 Unix 用户 的全部权限；只有把 SSH Key 限制为 OcHub Forced Command 时，Policy 才会成为强制的 授权边界。具体部署方式和协议细节见 远程节点设计与安全模型。

如果需要从桌面执行恢复数据库或导入 SQL/cc-switch 数据，请在远端策略中 显式开启恢复能力。安装更新默认已开启，也可以在配置中显式声明：

allowBackupRestore = true
allowUpdateInstall = true

桌面端会通过加密 SSH 会话读取明文密钥，编辑器与本机工作区一致。未修改的脱敏占位符 仍会保留远端原值，不会把 ****** 写回配置。策略变更在下一次 SSH 控制会话生效。

故障排查与当前限制

从 OcHub 移除节点只会删除控制端的连接记录，不会删除远端 Provider、工具配置、 ~/.ochub、daemon 或网关数据。