OpenAlice 远程接入快速上手：通过 SSH 在私有 Linux/macOS 主机上运行 AI 交易 Runtime，GUI 留在本地

本指南面向这样的使用场景：OpenAlice 跑在一台只能通过 SSH 访问的私有 Linux 或 macOS 主机上（这台主机拥有自己的 AliceProjects、Workspaces、Agent 进程、凭据与可选的交易服务），而图形界面仍然留在你的本地电脑上。读完本文，你将掌握本地 CLI 的安装与校验、通过 CLI 或 GUI 注册远端 Machine、选中远端 AliceProject、以及日常的 status/stop/inspect 控制与安全边界——全程有仓库源码与测试佐证。

一、职责划分：远端主机与本地电脑各自拥有什么

在远程接入模式下，OpenAlice 的职责边界非常清晰：

• 远端主机拥有：AliceProjects、Workspaces、Agent 进程、凭据，以及可选的 UTA 交易服务。也就是docs/remote-access.md中定义的 "Runtime"（Guardian 拥有的进程树与用户状态，含 Alice、可选 UTA、可选 Connector Service、workspaces、PTY、用户自有 Agent CLI、调度与文件态状态）。
• 本地电脑拥有：CLI（含 GUI 中继）与它唯一选中的目标（一个 Machine + 一个运行中的 AliceProject）。

生命周期的细节与安全模型由 docs/remote-access.md 完整承载，本文是其用户侧的上手路径。远程接入的整体分层可以从remote-access.md的 "Layered Topology" 中看到全貌：

presentation plane browser | Electron | future Studio │ transport plane loopback HTTP/WS | Electron IPC | SSH loopback | future capability channel │ runtime/control plane Guardian lease + local control endpoint + Alice APIs │ execution plane Workspace files + PTYs + native Agent CLIs + tools + optional UTA

这个分层在排查延迟时尤其重要：SSH 浏览器会话中，浏览器是本地的，但 shell/TUI 与模型回路是远端的——按键要穿过网络到达远端 PTY，远端屏幕变化经 Workspace WebSocket 返回，而 HTML 布局、菜单、列表等仍是本地浏览器的活。

二、第 1 步：安装本地 CLI

使用官方安装脚本安装本地 CLI：

curl -fsSL https://openalice.ai/install | bash

安装完成后运行安装器打印的 shell 激活命令，然后校验 CLI 可用：

openalice --version

安装/渠道相关的细节（如--channel beta、--channel dev、--version <version>固定版本等）由 docs/cli-installer.md 承载。

SSH 目标侧需要满足两点前提：

1. OpenSSH 访问：目标主机需要能被普通ssh到达；
2. 平台前提：目标主机需要满足 OpenAlice 原生发布的平台前置条件。

OpenAlice 直接复用你日常的 SSH 配置——密钥、主机校验（host verification）、端口与ProxyJump都按普通 OpenSSH 语义工作。它不会在目标上安装 Agent Runtime CLI（Shell、Claude Code、Codex 等由用户自己维护，见remote-access.md的 "It does not install Agent Runtime CLIs" 与不变式 #9）。

三、第 2 步：注册一台 Machine

给目标主机起一个 SSH 别名（如果还没配过的话），并确认普通 SSH 能连通：

Host openalice-box HostName server.example.com User alice IdentityFile ~/.ssh/id_ed25519

3.1 通过 GUI 注册

1. 启动openalice；
2. 打开它的 Web GUI；
3. 进入Settings → General → Machines；
4. 选择Add Machine，输入openalice-box与标签Cloud，然后**探测（probe）**目标。

预览（preview）会在你批准注册之前列出将要执行的确切远端动作。也就是说，注册之前你就能看到 "将要安装什么、将要启动什么"，而不是黑盒操作。

3.2 通过 CLI 注册

ssh openalice-box openalice --remote openalice-box --plan openalice machine add openalice-box --label "Cloud"

三个命令各司其职：

• ssh openalice-box：先独立确认普通 SSH 通路（这也是remote-access.md的建议——先能独立验证ssh <target>，再诊断 OpenAlice）。
• openalice --remote openalice-box --plan：只读计划，不产生任何远端改动。它会报告 SSH 目标与解析出的远端平台/架构、检测到的远端 OpenAlice CLI 路径/版本/逻辑发布身份、控制协议兼容性、Server 状态与内容身份、以及建议的安装/更新/启动动作等（见remote-access.md"Managed Remote Bootstrap and Compatibility"）。
• openalice machine add openalice-box --label "Cloud"：探测主机 → 展示并确认所需的安装/启动动作 → 检查 Runtime 健康 →然后才保存 SSH 档案。

--yes只能在已经审阅过那些动作之后使用，用于非交互式自动化确认。一个任意的 SSH 地址在通过这次注册之前，永远不是 GUI 目标——这是安全设计，不是疏漏。

注册时，如果目标缺少匹配的原生 OpenAlice 版本，会在需要时安装匹配版本；但 Agent Runtime 可执行文件与 SSH 凭据始终是用户自有的。已注册的 Machine 可以在同一个 Settings 区域里重新探测（re-probe）并升级。

3.3 源码级的 Machine 档案实现

openalice machine子命令的实现位于 packages/cli/src/machine-command.ts，支持的动作有list | add | rename | remove | enable | disable | inspect。machine add的完整选项包括：

Machine 档案存放在Supervisor 根目录下的machines.json（packages/cli/src/machine-registry.ts），位于每一个可选 AliceProject home 之外，不随某个 complete home 移动，也不属于 Electron 浏览器档案。持久化形态（docs/data-locations.md 有明确记录）大致如下：

{ "schemaVersion": 1, "machines": { "cloud": { "id": "0123456789abcdef0123456789abcdef", "displayName": "Cloud", "sshTarget": "alice@cloud", "enabled": true } } }

关键点：档案只包含连接元数据（不透明 id、显示名、OpenSSH 目标、可选端口、本地 identity 文件路径、启用状态），绝不包含密码、私钥字节、口令（passphrase）、主机密钥、agent 材料或远端凭据。写入时以0600权限先写临时文件再原子 rename（writeMachineRegistry），读侧有严格的 schema 校验。OpenSSH 配置、agent、ProxyJump与主机密钥策略始终保持权威。

四、第 3 步：选择远端 AliceProject

运行openalice，它的 TUI 会启动本地 Web 中继（relay）。然后在 TUI 中打开 Web GUI，进入Settings → General → Where Alice is working，选择Cloud及其一个运行中的 AliceProject。

要点：

• 使用同一个中继的浏览器标签页共享同一个选择；
• 不带 TUI 纯 GUI 运行时，使用openalice relay；
• 浏览器始终停留在本地中继的 origin 上，永远不会直连远端 Runtime 端口；
• 中继负责打开并拥有通往所选中后端的SSH 环回隧道；
• 切换到另一台 Machine 或 AliceProject不会停止之前的 Runtime；
• 关闭浏览器不会停止远端 Runtime；关闭本地中继才会结束它的隧道。

这与main.ts的命令路由一致（packages/cli/src/main.ts）：裸openalice进入 TUI，--remote/--machine走 CLI 命令路径，openalice relay提供无 TUI 的同一 Web 控制器。

4.1 中继的实现细节

packages/cli/src/web-relay.ts 的类注释第一行就是 "One local browser relay owns exactly one active Machine/AliceProject"。它维护一个活动目标ActiveTarget与一个递增的generation；切换时会先验证候选的 AliceProject 身份，成功后关闭旧 WebSocket、递增 generation、reload 所有标签页——切换永远不会停止旧 Runtime。

SSH 隧道的实际参数由 packages/cli/src/ssh-connect.mjs 的buildSshArgs构建：

ssh -N -T -o ExitOnForwardFailure=yes -o ServerAliveInterval=30 -o ServerAliveCountMax=3 [-o BatchMode=yes] # 仅 fleet 探测等非交互场景 [-p <ssh-port>] [-i <identity-file>] -L 127.0.0.1:<local-port>:127.0.0.1:<remote-port> <destination>

隧道两端都绑定127.0.0.1，遵循普通 OpenSSH 的配置、agent、密钥、ProxyJump 与主机密钥校验，并且从不转发 Guardian 的控制端点。旧的 "直接 SSH 浏览器挂接"（direct browser attach）已经退役——connectSsh中对此直接抛错："Direct SSH browser attach is retired; use the local Web relay."

默认的远端 Web 端口为47331（parseRemoteArgs中的remotePort: 47331，见 packages/cli/src/remote.mjs），与 docs/data-locations.md 记录的 Web 端口探测语义一致（从 47331 起向上探测，避免并发 home 冲突）。

五、日常控制命令

openalice machine list openalice machine inspect Cloud openalice --machine Cloud status --json openalice --remote openalice-box --status openalice --remote openalice-box --stop

语义说明：

• --machine：把一条命令路由到已保存、已启用的档案（profile）；
• --remote：保留用于只读规划与显式 status/stop 控制；它过去的一次性浏览器挂接能力已退役；
• machine disable：阻止新的选择，但不会停止已经在运行的远端 Runtime（禁用只是本地元数据变更，不停止远端 Server、也不关闭既有隧道）。

openalice machine的完整命令面（packages/cli/src/machine-command.ts）：

openalice machine list [--json] openalice machine add alice@example.com --label "Cloud" --yes openalice machine rename <id-or-label> --label "Cloud production" --yes openalice machine disable <id-or-label> --yes openalice machine enable <id-or-label> --yes openalice machine remove <id-or-label> --yes openalice --machine <id-or-label> status --json openalice machine inspect [id-or-label] [--json]

machine remove只删除本地元数据（且需显式确认），从不删除远端数据。

5.1 探针与清册（inventory）行为

machine inspect使用同一个类型化清册（packages/cli/src/machine-inventory.ts）同时覆盖本地与远端 Machine。每次远端探测只发一条聚合 SSH 命令（远端执行openalice machine inspect local --json），远端命令只读它自己的 Supervisor AliceProject 注册表并探测已注册的 complete home——不会扫描任意远端目录。

清册中每个 Machine 的连接状态被规范化为：online/offline/unauthorized/incompatible（外加本地的local与过渡态checking）。可达性不是 Runtime 状态：一台online的 Machine 仍可能包含停止、不健康或由他人拥有的 Projects；一台不可达的 Machine 只作为一行offline出现在 fleet 结果中，不会让整个刷新失败。

出于安全，fleet 探测强制 OpenSSHBatchMode，避免密码/密钥口令/主机密钥提示卡住 Supervisor TUI——这些情况会变成unauthorized行；而交互式隧道命令保留正常的 OpenSSH 提示。清册响应是有界的：包含项目身份、product、home/port、规范化 Runtime 状态、组件健康与能力声明，但省略owner PID、token、日志、命令行、环境变量与凭据。

5.2--remote的完整选项

--remote的完整帮助见 packages/cli/src/remote.mjs 的formatRemoteHelp：

两条红线（源码中都有强制校验）：

• --yes绝不隐含--takeover——批准计划不等于替换 owner；
• --remote-session被显式拒绝——OpenAlice 没有 Herdr 风格的命名 server session，machine-command.ts直接抛错 "OpenAlice has no named server sessions. Use --project or --home on the target command."，而不是静默存储。

另外，--status与--stop不能混用、--plan/--takeover不能与--status/--stop组合（parseRemoteArgs中直接抛错）。远端 SSH 命令只会对一小撮可重试的传输故障（连接 reset/timeout/close、key-verifier 服务中断、kex_exchange_identification/ssh_exchange_identification失败等）做重试——remote.mjs顶部的TRANSIENT_SSH_PATTERNS就是这份允许清单；任意远端命令失败从不重试。

六、把项目搬到远端：project transfer

如果希望把一个静止的本地 AliceProject复制到已注册的 SSH Machine 上成为一个全新的 complete home，可以使用project transfer（packages/cli/src/project-command.ts）：

openalice project transfer \ --from research \ --to-machine cloud-dev \ --to-project research-cloud \ --to-home /home/alice/.openalice-research \ --session-owner-policy keep-blocked \ --plan

• --plan先盘点：报告可移植文件/字节总量、目标所需空闲空间、无密钥凭据类别、被排除的 Session/Runtime 文件，以及精确 Session 的定时 Issues；
• apply 需要源项目已停止（或显式传--stop-source），且拒绝被占用的项目 key 或 Home；
• 可移植：便携配置、活跃与已离开的 Workspace 仓库、Workspace id、生命周期记录、以及"合法"的 AI/行情数据/券商/Connector 凭据（经 SSH 私有流传输，并在接收端用新建的目标密钥重新封存，源封存密钥绝不复制）；
• 不迁移：Guardian 状态、Runtime 负载、端口、Web auth 与 sessions、headless/native 会话状态、resume 身份、原生 Agent 登录与配置、未跟踪的 Session 档案；顶层bin/与cli/目录、安装器锁/缓存、越界/绝对符号链接作为机器本地内容排除；
• 定时 Issues 的 owner 策略必须显式选择keep-blocked或new-then-resume（两者之外的值直接抛错）。

传输使用带版本、有界的 SSH stdin 流（packages/cli/src/project-transfer.ts 与project-transfer-ssh.ts/project-transfer-stream.ts），接收端校验规范化路径、条目类型、符号链接包含关系、大小、校验和、可用空间与事务身份，先写 owner 私有的兄弟 staging Home，再原子发布并注册；--without-credentials可剥离密钥字段后保留可移植 AI/行情配置。发布成功后会留下匹配的 receipt（.openalice-transfer-receipt.json），使注册重试具备幂等性。

七、安全边界与持久化语义

remote-quickstart.md给出了两条硬性安全底线，remote-access.md用一整章 "HTTP and Browser Security" 支撑：

1. 绝不直接发布远端 Runtime 端口（Alice 与 Guardian 控制端点从不绑定公网 TCP）；
2. 绝不为远程访问禁用认证——OPENALICE_DISABLE_AUTH=1永远不是一条远程访问指令。

SSH 让远端 HTTP 请求从环回地址到达，因此"来自环回"不足以构成授权。浏览器契约还包括：UI、HTTP API 与 PTY WebSocket 共享隧道的本地环回 origin；Alice 只对三类调用者接受无登录本地行为（无Origin的本地 CLI/server 调用、经过校验的环回浏览器 origin、精确的app://openalice打包 origin）；公开 web origin 不能因为隧道开着就继承 localhost 信任；有状态请求与 WebSocket 升级保持 origin 校验。本地中继还会拒绝非精确 Host 与跨域变更请求、剥离浏览器转发头、按 Machine/Project 命名空间隔离后端 cookie，其控制路由只接受已注册 key 而非裸 SSH 目的地或命令。

持久数据属于远端 AliceProject home。如果那台机器是临时的（ephemeral），要把这个 home 挂载到持久存储上。remote-access.md的 "Persistence Semantics" 表格明确回答了"断开后什么还活着"：

OpenAlice不会把 server detach 宣传成"崩溃级终端持久化"；会话溯源与原生 CLI resume 由 docs/conversation-provenance.md 管理，终端 scrollback 持久化是另一项独立隐私决策。

八、架构不变式与交付阶段

remote-access.md明确列出十条架构不变式，核心几条（对使用方最有感知）：

1. 拥有文件的那台机器，同时拥有 Workspace、原生 Agent 进程、工具执行、provider 请求与交易边界；
2. Guardian 是一个OPENALICE_HOME的最终单写者与进程树权威，新 CLI 命令不得发明并行锁；
3. UTA 保持可选——Server、远端 status、浏览器 Chat 与非交易工作在 lite/只读模式下必须可用；
4. Alice 只绑定127.0.0.1；内部 MCP/CLI、UTA、Connector、控制与 PTY 端口永不为远程访问而公网化；
5. SSH 只负责认证与加密传输，不静默授予安装/更新/启动/接管/停止的同意权；
6. 断开浏览器、Electron 渲染器、CLI 或 SSH 隧道不会停止 detached Server；
7. --takeover是唯一替换另一已记录 Guardian owner 的命令行权限。

交付被划分为 Stage 0–5：Stage 0（relay 内实现的 SSH 传输）、Stage 1（原生server run/start/status/stop生命周期）、Stage 2（受管 Bun 原生远端：machine addplan/apply 编排、无 Node/Bun/源码/构建工具运行安装的 release、远端 Server 启动/复用、选择目标时建立 relay 的 SSH 环回隧道、断开后 Server 存活）均已实现；Stage 3（终端传输优化）按需构建；Stage 5（release 签名/可复现构建加固）进行中。

九、验证路径与验收

当远程相关行为变更时，remote-access.md的 "Verification Route" 要求：

1. 使用隔离的OPENALICE_HOME根，绝不在正常 home 上演练恢复；
2. CLI 负载变更后跑pnpm test:system:installer（package.json）；
3. 生命周期/所有权/信号/锁/控制端点变更时跑 Guardian 恢复用例矩阵；
4. 真实 localhost 路由验证 Workspace 终端与 loginless 环回 Origin 契约；
5. 对一次性 SSH/Docker 主机跑pnpm test:system:remote（node scripts/remote-ssh-smoke.mjs），覆盖 default-no、安装负载一致性、detach 持久化、重连与结构化停止。

仓库里就有这份可重复的 Docker 验收装置：scripts/remote-smoke/Dockerfile 的最终运行阶段是debian:bookworm-slim——只装bash ca-certificates curl git openssh-server python3，没有 Node、没有 Bun、没有 Agent Runtime；scripts/remote-smoke/entrypoint.sh 启动纯 pubkey 的 sshd 与本地安装源 HTTP 服务，验证"无 Node 主机上完成 native 下载、安装、多进程启动、AliceProject 传输与隧道环回"这条受管远端主线。

十、参考文档索引

• docs/remote-quickstart.md — 本文源头，用户侧上手路径
• docs/remote-access.md — 远端 Runtime 架构主人指南（生命周期、SSH 传输、控制契约、安全、验收矩阵）
• docs/cli-installer.md — 本地 CLI 安装、渠道、激活与回滚
• docs/cli-supervisor.md — TUI/Supervisor 与 relay 的命令契约
• docs/local-runtime.md — 本地 Runtime 生命周期
• docs/managed-workspace-runtime.md — 受管 Workspace Runtime 与 Electron 分离模式
• docs/data-locations.md —machines.json等数据落盘位置与形态
• docs/conversation-provenance.md — 会话溯源与原生 Agent resume
• docs/reference/herdr-remote-architecture.md — 设计参考对比（研究资料）

核心实现入口：openalice machine（packages/cli/src/machine-command.ts）、Machine 档案（packages/cli/src/machine-registry.ts）、类型化清册（packages/cli/src/machine-inventory.ts）、受管远端编排（packages/cli/src/remote.mjs）、SSH 隧道（packages/cli/src/ssh-connect.mjs）、本地 Web 中继（packages/cli/src/web-relay.ts）、GUI 侧 plan/apply（packages/cli/src/machine-management.ts）与项目迁移（packages/cli/src/project-transfer.ts）。