---
title: 远程主机
description: 在另一台机器上跑 Agent 的操作那一半——添加主机、测试线路、为什么密码不够用、Set Up 究竟装了什么，以及怎么读那一行说明机器是否就绪的话。
x-i18n:
source_path: remote-hosts.mdx
source_hash: 1fcd19ff49d2a6931c564b23c1d609d4816871b65c50e14b95a1a411105e5dfb
generated_at: 2026-09-19
---
[设备](/zh-CN/docs/devices)讲的是模型：一台机器就是一台你能 `ssh` 上去的机器，其余的一切
都归到它下面。这一页是那个真正干活的页面的操作手册——**设置 ▸ 远程主机**，一台机器一行，
每一行打开那台机器自己的页面。
在进细节之前，先知道它的形状。一台机器同时是两样东西：一条**线路**（你怎么到它）和一个
**身份**（它上面装了什么）。你没法在一台连不上的机器上装任何东西，所以这个页面就按这个
顺序读，下面也是。
## 添加一台主机 [#adding-a-host]
Termio 读 `~/.ssh/config`，并且从不背着你改写它。任何你已经能 `ssh` 上去的机器，Termio
就能连上——没有什么要导入的。
- **文件 ▸ 连接到…** 列出你配置里 Termio 还没打过交道的别名。选一个就会在那儿打开一个
终端。
- **添加主机…**——在**文件 ▸ 新建 SSH 连接**的末尾，也在远程主机页面上——为一台还不在你
配置里的机器追加一个 `Host` 配置块。先填地址；名字就是你之后跟在 `ssh` 后面打的那个。
如果你别的主机已经共用同一个用户和密钥，那一对会直接给你选，而不用重打。
这样加的主机之后就是一个普通的 `~/.ssh/config` 条目。机器页面上有一行
**Host 配置块 ▸ 编辑**，
打开的正是它被定义的那个条目，这样配置始终是答案唯一待的地方。
## 测试线路 [#testing-the-route]
**连接方式**这一节会说明目标地址，以及 `ssh` 会怎么登录——要么用你配置里指定的密钥，要么
用「`ssh` 自己会提供的那些密钥」。旁边是一个**测试**按钮。它会给出四种结果之一，最后一种
带的是 `ssh` 自己给的原因，而不是一个固定标签：
| 结果 | 含义 |
| --- | --- |
| 可连接 | `ssh` 连上并通过了认证。没什么要修的。 |
| 需要密码 | 这台主机提供的是密码认证。唯一一种有一键修法的失败——见下面。 |
| 认证失败 | 它应答了，但拒绝了这套凭据。是密钥的问题，不是网络的问题。 |
| `ssh` 给出的原因 | 其余所有情况——被拒绝、超时、未知主机——按 `ssh` 自己的话报出来。 |
测试用的是这台机器自己的别名，和应用其他部分连它的方式一样。如果 `ssh mybox` 在你的终端
里就失败，这里也会失败——Termio 不携带任何自己的凭据。
## 为什么密码不够用 [#why-a-password-isnt-enough]
一台需要密码的主机，只会让你打开一个普通终端，别的都不行。这不是什么策略选择——这是算出来
的。承载会话、文件树、搜索和 Git 面板的那些连接全都是非交互式运行的（`BatchMode=yes`），
也就是说它们永远没法回答一个提示。密码只在有个人坐在那儿打字的地方管用，在其他任何地方
都不管用。
所以这个页面把话说明白，并就地给出修法：**设置密钥…** 会在一个终端里用 Termio 要用的那把
密钥跑 `ssh-copy-id`。主机在那儿问你一次密码，之后每条路都能连上它了。如果 `~/.ssh` 里
没有一把 `ssh` 会自己提供的密钥，那一行会说出来，并先把你指向 `ssh-keygen`。
密钥是你自己的，命令也是标准的那个。Termio 从不保存密码，从不内嵌 SSH 实现，也从不把
凭据写到 `ssh` 和你的钥匙串本来就放它们的地方之外。
## 把它设置好 [#setting-it-up]
把一台机器准备好是一条真实的依赖链——先把 server 放上去，再弄清它有哪些 Agent 命令行工具，
再把 Termio 的 hooks 和技能写进它们里面。把这些做成四个互相独立的状态显示出来，会让「选一台
机器」变成一场基础设施排障，所以这个页面只承诺**一个结果**，把那些梯级放在它下面：
| 那一行说 | 含义 |
| --- | --- |
| **设置这台主机** | 还什么都没问过，或者有一级卡住了。按**设置**。 |
| **检查中…** | 它在跑，并且会说出自己正在哪一级。 |
| **已就绪** | 那台机器上的 Agent 能跑——并且在集成开关打开时，能把状态汇报回这里。 |
| **更新已就绪** | 新的 server 已经放好了，正在跑的那个因为手上有活儿而把它挡着。 |
按**设置**会走完整条梯子：通过 SSH 把 `termiod` 复制进 `~/.local/bin`、探测你的 Agent
命令行工具，然后按**设置 ▸ Agent** 上那两个开关的要求，把 hooks 和技能对齐——该装的装，
该删的删。两个都关着时它有意什么也不装，那一行也就只承诺那里的 Agent 能跑。不需要 root，
不需要包管理器，也不用往你的 shell 配置里加任何东西。
某一级失败时，那一行会点名**那一级**，而不是说「设置失败」——而且只说第一级。一台没有
`termiod` 的机器同样没有 hooks，把两件事都说出来，只会让你去修结果而不是修原因。
某个 Agent 命令行工具没装在那儿，并不会挡住**就绪**。那是关于那个 Agent 的事实，不是这台
机器的毛病——这台机器已经准备好跑它真正有的那些 Agent 了。
## 那台机器上的 Agent [#agents-on-that-box]
一台远程机器的页面上有一个 **Agents** 链接——「*这台机器*有什么」——这和**设置 ▸ Agents**
问的是同一个问题，只是换了个轴。打开它你会看到：
- **命令路径。** 一个 Agent 一行，下面是这台机器自己的答案：*已安装*、*未安装*，或者
*无法检查*。路径留空，就按那台机器的登录 shell 的方式启动这个 Agent；当二进制装在它的
配置没加进来的位置时，就把路径填上（`/opt/homebrew/bin/codex`）。哪些 Agent 会出现在
这里，仍然由**设置 ▸ Agents** 决定。
- **Termio 安装的内容。** Termio 写进那台机器上每个 Agent 配置里的东西——**Hooks**（让
Agent 汇报自己的状态）和**技能**。一个**重新安装 Hooks 和技能**按钮修好这两样；手改过
其中一个之后，或者状态点不动了的时候，就用它。
一台机器拿到的技能，和本机拿到的不是同一个。这里的 Agent 学的是 `termio sessions`，
限定在它自己的项目里；一台机器上的 Agent 学的是 `termiod list`、`create`、`send` 和
`kill`，作用范围是整台机器——因为那才是那边真正存在的命令。
*无法检查*是有意留的第三个答案，而且它从来不是 Agent 的毛病：它的意思是 Termio 连不上这台
机器去问。把它报成「未安装」，会让你去重装一个本来就在的命令行工具；报成「已安装」，则是
在承诺一次根本发生不了的启动。
这两个开关本身——**Agent 实时状态**和**会话控制**——在**设置 ▸ Agents** 上，因为想不想
要这个功能是一种偏好。而它装到哪儿是一次机器操作，所以那件事在这里发生，一台机器一次。
参见[状态 hooks 与会话控制](/zh-CN/docs/session-control)。
## 让一台主机保持最新 [#keeping-a-host-current]
同一个**设置**按钮就是更新。它从任何状态都能用——什么都没装、一个旧版本、一个正在跑的
daemon 还没接过去的版本——而且如果新的那个不应答，它会把旧的二进制放回去。机器页面显示的是
它真正在跑的版本。
一次会打断正在进行的工作的更新不会被执行。那一行会写**更新就绪**，点名那个挡着它的会话，
并在旁边给出**仍然更新**。放着不管，新版本会在 daemon 下一次自己停下来时接手。你自己闲着的
终端从不挡更新；一条还在跑的命令或者一个干到一半的 Agent 才会。
从命令行来看，同一次对账就是一个动词：
```bash
termiod deploy --host mybox
```
不管从什么状态开始，它都结束在同一个状态，所以对一台看起来不对劲的机器跑它是安全的。参见
[Termio server](/zh-CN/docs/server)。
## 一台主机不应答了 [#when-a-host-stops-answering]
从外往里查——先 `ssh`，再 daemon，最后 Termio：
```bash
ssh mybox true # SSH 本身通不通？
termiod list --host mybox # 那边的 server 在应答吗？
termiod deploy --host mybox # 重装并校验一遍
```
连接断了只是把你脱离，不会杀掉任何东西。会话在那台机器上、在它的 daemon 里，重新附着会
恢复屏幕——参见[什么会留下来](/zh-CN/docs/persistence)。如果重启之后它们是真的没了，那台
机器缺的是一个服务：`termiod service install`。
设备切换器会用 `ssh` 自己的话来报告一台连不上的机器，而不是默不作声，所以你读到的失败就是
`ssh` 遇到的失败。更多症状和对应的检查在[问题排查](/zh-CN/docs/troubleshooting)里。
模型：一台机器是什么，以及有什么能连过去。
`termiod` 本身——怎么装、怎么让它一直活着、怎么看它。
这两个开关的文件会落到你设置过的每一台机器上。