ssh-op

使用 ssh-op 帮助程序脚本将 1Password (op) 中的 SSH 私钥加载到内存中的 ssh 代理中，然后运行 ​​​​ssh。在连接到需要 1Password 托管密钥的主机、对 ssh-op 进行故障排除或通过配置 1Password 保管库/项目并将 SSH 主机别名添加到 ~/.ssh/config 来加入新计算机时使用。

# ssh-op

`ssh-op` is a wrapper around `ssh` that:

- ensures an `ssh-agent` exists for the current shell
- loads an SSH key from 1Password via `op read ... | ssh-add -`
- then `exec`s `ssh` with your arguments

## Prerequisites

Fail-fast checks you can run:

```bash
command -v op ssh ssh-agent ssh-add
op whoami
```

If `op whoami` fails:

- Sign in to 1Password CLI (desktop integration / account sign-in), **or**
- If using a service account flow, ensure `OP_SERVICE_ACCOUNT_TOKEN` is set.

## Configuration (portable)

Machine-specific config lives alongside the skill:

- Example (do not edit): `~/.openclaw/skills/ssh-op/config.env.example`
- Real (machine-specific): `~/.openclaw/skills/ssh-op/config.env`

Required keys:

- `SSH_OP_VAULT_NAME` — 1Password vault containing the key
- `SSH_OP_ITEM_TITLE` — 1Password item title

Optional keys:

- `SSH_OP_KEY_FIELD` — defaults to `private key`
- `SSH_OP_KEY_FINGERPRINT_SHA256` — if set, skip re-loading when already in `ssh-agent`
- `SSH_OP_HOSTS_FILE` — defaults to `hosts.conf` (ssh config snippet filename)

SSH host entries (optional) live in:

- `~/.openclaw/skills/ssh-op/hosts.conf`

## Initialization / installation / onboarding

### Preferred (chat-first)

Because the primary interface is chat (Telegram), the preferred onboarding flow is:

1. Ask Boss the required questions in chat.
2. Write the real config file: `config.env`.
3. Run a smoke test (e.g. `ssh-op --help` and a safe `ssh-op -T <alias>`).

### Optional (terminal)

If you are running in a real terminal, you can use the interactive onboarding script:

```bash
~/.openclaw/skills/ssh-op/scripts/onboard.sh
```

(If you want a step-by-step runbook, see `references/onboarding.md`.)

### 1) Put the executable on PATH

Canonical executable lives inside the skill:

- `~/.openclaw/skills/ssh-op/scripts/ssh-op`

For convenience, create a symlink:

```bash
mkdir -p ~/.local/bin
ln -sf ~/.openclaw/skills/ssh-op/scripts/ssh-op ~/.local/bin/ssh-op
```

### 2) Configure which key to load

Run onboarding to populate the real config:

```bash
~/.openclaw/skills/ssh-op/scripts/onboard.sh
```

(Or edit `config.env` manually and set `SSH_OP_VAULT_NAME` / `SSH_OP_ITEM_TITLE`.)

Then validate:

```bash
ssh-op --help
# try a safe ssh command (or any host alias you have configured)
ssh-op -T <host-alias>
```

### 3) (Optional) Manage ~/.ssh/config host aliases

1. Put desired `Host` entries in `hosts.conf`
2. Apply them idempotently (adds/updates a managed block):

```bash
~/.openclaw/skills/ssh-op/scripts/ensure_ssh_config.py
```

This will update `~/.ssh/config` between:

- `# BEGIN ssh-op (managed)`
- `# END ssh-op (managed)`

## Usage

```bash
ssh-op <ssh-args...>
```

Examples:

```bash
ssh-op my-host-alias
ssh-op -T my-host-alias
ssh-op -L 8080:localhost:8080 my-host-alias
```

## Notes / behavior

- No private key is written to disk.
- `ssh-agent` lifetime is tied to the current shell unless you export `SSH_AUTH_SOCK` / `SSH_AGENT_PID`.

## Executables / bin placement

- Keep the canonical executable in the skill folder (`scripts/ssh-op`).
- Use a symlink (e.g. `~/.local/bin/ssh-op`) for convenience.

---

## 中文说明

# ssh-op

`ssh-op` 是 `ssh` 的一个包装器，它会：

- 确保当前 shell 存在一个 `ssh-agent`
- 通过 `op read ... | ssh-add -` 从 1Password 加载 SSH 密钥
- 然后用你的参数 `exec` 执行 `ssh`

## 先决条件

可运行的快速失败检查：

```bash
command -v op ssh ssh-agent ssh-add
op whoami
```

如果 `op whoami` 失败：

- 登录 1Password CLI（桌面集成 / 账户登录），**或者**
- 如果使用服务账户流程，确保已设置 `OP_SERVICE_ACCOUNT_TOKEN`。

## 配置（可移植）

机器相关的配置与该技能放在一起：

- 示例（请勿编辑）：`~/.openclaw/skills/ssh-op/config.env.example`
- 实际（机器相关）：`~/.openclaw/skills/ssh-op/config.env`

必需的键：

- `SSH_OP_VAULT_NAME` — 包含该密钥的 1Password 保管库
- `SSH_OP_ITEM_TITLE` — 1Password 项目标题

可选的键：

- `SSH_OP_KEY_FIELD` — 默认为 `private key`
- `SSH_OP_KEY_FINGERPRINT_SHA256` — 如果设置，当密钥已在 `ssh-agent` 中时跳过重新加载
- `SSH_OP_HOSTS_FILE` — 默认为 `hosts.conf`（ssh 配置片段文件名）

SSH 主机条目（可选）位于：

- `~/.openclaw/skills/ssh-op/hosts.conf`

## 初始化 / 安装 / 入门

### 首选方式（聊天优先）

由于主要界面是聊天（Telegram），首选的入门流程是：

1. 在聊天中向 Boss 询问所需问题。
2. 写入实际配置文件：`config.env`。
3. 运行冒烟测试（例如 `ssh-op --help` 和一个安全的 `ssh-op -T <alias>`）。

### 可选方式（终端）

如果你在真实的终端中运行，可以使用交互式入门脚本：

```bash
~/.openclaw/skills/ssh-op/scripts/onboard.sh
```

（如果你想要一份分步操作手册，请参阅 `references/onboarding.md`。）

### 1) 将可执行文件放入 PATH

规范的可执行文件位于该技能内部：

- `~/.openclaw/skills/ssh-op/scripts/ssh-op`

为方便起见，创建一个符号链接：

```bash
mkdir -p ~/.local/bin
ln -sf ~/.openclaw/skills/ssh-op/scripts/ssh-op ~/.local/bin/ssh-op
```

### 2) 配置要加载的密钥

运行入门流程以填充实际配置：

```bash
~/.openclaw/skills/ssh-op/scripts/onboard.sh
```

（或手动编辑 `config.env` 并设置 `SSH_OP_VAULT_NAME` / `SSH_OP_ITEM_TITLE`。）

然后验证：

```bash
ssh-op --help
# 尝试一个安全的 ssh 命令（或任何你已配置的主机别名）
ssh-op -T <host-alias>
```

### 3)（可选）管理 ~/.ssh/config 主机别名

1. 将所需的 `Host` 条目放入 `hosts.conf`
2. 幂等地应用它们（添加/更新一个受管块）：

```bash
~/.openclaw/skills/ssh-op/scripts/ensure_ssh_config.py
```

这将更新 `~/.ssh/config` 中以下两行之间的内容：

- `# BEGIN ssh-op (managed)`
- `# END ssh-op (managed)`

## 用法

```bash
ssh-op <ssh-args...>
```

示例：

```bash
ssh-op my-host-alias
ssh-op -T my-host-alias
ssh-op -L 8080:localhost:8080 my-host-alias
```

## 说明 / 行为

- 不会将任何私钥写入磁盘。
- 除非你导出 `SSH_AUTH_SOCK` / `SSH_AGENT_PID`，否则 `ssh-agent` 的生命周期与当前 shell 绑定。

## 可执行文件 / bin 放置

- 将规范的可执行文件保留在技能文件夹中（`scripts/ssh-op`）。
- 为方便起见，使用符号链接（例如 `~/.local/bin/ssh-op`）。