`remote` 模块：远程机器管理

🔵 remote 模块维护机器清单，并通过 SSH/SCP 为代理提供对机器的受限访问：主机列表、执行命令、传输文件和检查可达性——均受每台机器的策略约束。私钥不存储在清单中，也不会出现在 API 响应中。

该模块属于标准发行版（config/modules.enabled → remote）。

51.1 清单

机器由文档描述：slug、host、port、user、标签、认证方式和策略。清单存储在 DuckDB（logs/machines.db）中，并从 config/remote/machines.yaml 播种：首次打开数据库时，如果尚不存在具有该 slug 的机器，则从文件添加记录。通过 API/工具所做的修改保存在数据库中，重新部署时不会被覆盖。

# config/remote/machines.yaml
machines:
  - slug: web-1
    host: 10.0.0.10
    user: deploy
    tags: [prod, web]
    known_hosts: accept_new      # strict | accept_new | insecure
    auth:
      type: key_secret           # agent | key_file | key_secret | password_secret
      name: WEB1_SSH_KEY
    policy:
      mode: allowlist            # deny | readonly | allowlist | full
      allow: ["uptime", "systemctl status *", "df -h"]
      deny: ["rm -rf *"]
      require_approval: false

数据库路径和种子路径可通过变量 AGENT_OS_REMOTE_DB 和 AGENT_OS_REMOTE_MACHINES 覆盖。

51.2 执行策略 {#policy}

policy.mode 定义了对机器允许执行的操作：

模式	行为
`deny`（默认）	禁止执行，仅清单
`readonly`	仅允许 `allow` 中的命令（与 `allowlist` 相同的检查；名称用于说明意图）
`allowlist`	仅允许 `allow` 中的命令
`full`	除 `deny` 中的命令外全部允许

allow/deny 是使用 * 和 ? 的模板（匹配命令的整行）。deny 始终优先于 allow。在 require_approval: true 下，调用必须传递 approved: true——否则代理在获得明确同意之前不会执行命令。

默认情况下，机器处于 deny 模式——fail-closed：在策略未设置之前，机器仅作为清单记录可用。文件（ssh_upload/ssh_download）仅在 mode: full 下允许。

51.3 认证

`auth.type`	说明
`agent`	本地 ssh-agent / `~/.ssh/config`（默认）
`key_file`	磁盘上私钥的路径（支持 `~`）
`key_secret`	按名称 `name` 存储在密钥中的私钥
`password_secret`	密钥中的密码（运行器目前尚不支持密码 SSH）

命名凭据通过宿主端口 agent_os.Secrets（名称允许列表）读取，因此该模块声明了能力 agent_os.Secrets。密钥引用既来自 YAML 种子，也来自数据库中的记录——清单的这两个入口是等价的。

51.4 工具

该模块添加 8 种工具（参见工具参考）：

`kind`	用途
`machine_list`	机器列表（可选过滤器 `tag`）
`machine_get`	按 `slug` 获取单台机器
`machine_upsert`	创建/更新机器
`machine_delete`	删除机器
`ssh_exec`	在机器上执行命令
`ssh_upload`	上传文件到机器（SCP）
`ssh_download`	从机器下载文件（SCP）
`remote_health`	可达性检查

示例：

kind: ssh_exec
name: run_on_machine
description: Выполнить команду на управляемой машине

51.5 HTTP API

清单管理 API（位于管理认证之后，参见 HTTP API）：

Endpoint	描述
`GET /v1/machines`	机器列表 🔒
`POST /v1/machines`	创建/更新机器（请求体为文档）🔒
`GET /v1/machines/:slug`	单台机器 🔒
`PUT /v1/machines/:slug`	更新机器（slug 来自路径）🔒
`DELETE /v1/machines/:slug`	删除机器 🔒

响应使用机器的“已编辑”表示（redacted()）：密钥名称和密钥本身永远不会被泄露。

51.6 安全

执行——通过 shell-out 调用系统 ssh/scp，使用 BatchMode=yes、ConnectTimeout=15、keepalive 和主机密钥检查（known_hosts）。
命令在启动之前由策略检查；deny 具有优先级。
密钥不存储在清单中；密钥通过 agent_os.Secrets 读取。
来自密钥的密钥材料化为具有 0600 权限的临时文件。

51.7 本地测试

与任何工具一样，引擎可以在没有服务器的情况下运行：

AGENT_OS_REMOTE_MACHINES=config/remote/machines.yaml \
AGENT_OS_REMOTE_DB=/tmp/machines.db \
./bin/agent-os tool config/agents/<agent>/tools/<tool>.yaml '{"slug":"web-1","command":"uptime"}'

51.8 限制

仅支持 linked 模块（DLL 稍后支持）。
密码认证尚未接入（需要 askpass）。
REST API 覆盖清单；代理可通过工具执行命令（同步路由不会阻塞在 SSH 上）。
没有后台健康轮询（计划通过 agent_os.Tasks 实现）。

remote 模块：远程机器管理