# 人類使用指南：agent-secret-vault

這份文件給人類維護者看：如何安裝、操作，以及如何用自然語言指示 agent 管理 secrets。

## 這是什麼

`agent-secret-vault` 是本地 AI agent 共用的機密資料 repo。

- 加密資料：`secrets/vault.yml`
- 加密格式：Ansible Vault
- 解密鑰匙：`~/.config/vault-pass.txt`
- Repo：`ssh://git@gitea.cowbay.org:2203/hermes/agent-secret-vault.git`

`secrets/vault.yml` 可以進 git；`~/.config/vault-pass.txt` 不可以進 git。

## 安裝

```bash
sudo apt update
sudo apt install -y git ansible unzip

mkdir -p ~/projects
cd ~/projects
git clone ssh://git@gitea.cowbay.org:2203/hermes/agent-secret-vault.git
cd agent-secret-vault
```

接著安裝 vault password file：

```bash
./scripts/install-vault-pass.sh --check-env
./scripts/install-vault-pass.sh
```

installer 會先檢查：

```text
~/.config/vault-pass.txt
```

如果已存在，會保留並驗證。若不存在，會讓你選 4 種方式：

1. 建立新 vault password，並在需要時建立加密 placeholder vault。
2. 手動輸入 vault-pass.txt 的內容。
3. 輸入 vault-pass.txt 的 URL，讓 installer 自動下載。
4. 解壓 repo 內既有的密碼保護檔 `secrets/vault-pass.txt.zip`。

若選第 4 種，請在你自己的 terminal 輸入 zip 密碼；Telegram / chat 不能輸入到 agent 的工具互動提示。

驗證：

```bash
./scripts/vault.sh view
```

## 建立安裝用密碼保護壓縮檔

維護者若要讓其他 agent / 機器安裝，先在已可解密的機器上執行：

```bash
cd ~/projects/agent-secret-vault
./scripts/create-vault-pass-archive.sh
git add secrets/vault-pass.txt.zip
git commit -m "Add vault password archive"
git push
```

腳本會要求互動輸入 zip 密碼。這個 zip 密碼不要寫進 repo、chat 或 log；交給安裝者時用另外的安全渠道。

## 安裝時設定 vault-pass

安裝流程建議先填 repo 內的 env 檔：

```bash
cd ~/projects/agent-secret-vault
cp -n install.env.example install.env
editor install.env
./scripts/install-vault-pass.sh --check-env
./scripts/install-vault-pass.sh
```

`install.env` 可設定：

- `INSTALL_VAULT_PASS_METHOD=url` + `VAULT_PASS_URL=...`
- `INSTALL_VAULT_PASS_METHOD=archive` + `VAULT_PASS_ZIP_PASSWORD_FILE=...`
- `INSTALL_VAULT_PASS_METHOD=manual` + `VAULT_PASS_CONTENT=...`
- `INSTALL_VAULT_PASS_METHOD=create`

若 env 內含真實 secrets，不要 commit。可改用 `install.local.env`，再執行：

```bash
INSTALL_ENV_FILE=install.local.env ./scripts/install-vault-pass.sh --check-env
./scripts/install-vault-pass.sh
```

## 給 agent 的全自動安裝方式

如果目標是「AI agent 直接安裝，不要卡在互動輸入密碼」，請不要讓 agent 選互動 zip 解壓。改用環境變數指定方法：

```bash
# 一次性 URL 下載
INSTALL_VAULT_PASS_METHOD=url \
VAULT_PASS_URL="https://example.com/one-time/vault-pass.txt" \
./scripts/install-vault-pass.sh

# 或：zip 密碼放在本機安全檔案
INSTALL_VAULT_PASS_METHOD=archive \
VAULT_PASS_ZIP_PASSWORD_FILE=/secure/path/zip-password.txt \
./scripts/install-vault-pass.sh --check-env
./scripts/install-vault-pass.sh
```

不要把 zip 密碼或 vault-pass 內容貼在聊天裡；應由目標機器的 secret manager、一次性 URL 或本機安全檔提供。

## 常用人工操作

### 查看 vault

```bash
cd ~/projects/agent-secret-vault
./scripts/vault.sh view
```

### 編輯 vault

```bash
cd ~/projects/agent-secret-vault
git pull --ff-only
./scripts/vault.sh edit
git add secrets/vault.yml
git commit -m "Update secrets"
git push
```

### 讀單一 secret

```bash
./scripts/get-secret.sh gitea.api_token
./scripts/get-secret.sh openclaw_alice.http_nodes.gitea.password
```

## 用自然語言請 agent 操作 secrets

你可以直接對 agent 下這類命令：

### 查詢但不要顯示 secret

```text
幫我確認 agent-secret-vault 裡有沒有 gitea.api_token，不要把 token 印出來。
```

Agent 應該只回報「有 / 沒有」與使用的 key path，不應顯示 token。

### 使用 secret 去登入或呼叫 API

```text
用 agent-secret-vault 裡的 openclaw_alice.http_nodes.gitea 帳密登入 Gitea，登入成功後回報狀態，不要把帳密貼出來。
```

Agent 可以讀取 secret 並用於 browser/API，但不能把 secret value 回傳聊天。

### 新增 secret

```text
幫我把新的 API token 加到 agent-secret-vault，key 放在 openclaw_alice.http_nodes.example_service.api_token；先 git pull，更新後驗證可讀，再 commit/push。不要在回報中顯示 token。
```

如果 token 需要由你提供，請用安全渠道或互動輸入；不要把高敏感 token 直接貼到公開群組。

### 修改 secret

```text
把 agent-secret-vault 裡 openclaw_alice.http_nodes.gitea.password 更新成我等一下提供的新密碼；完成後只回報 commit hash 和驗證方式。
```

### 列出 key 結構

```text
列出 agent-secret-vault 目前有哪些 top-level sections 和 key 名稱，不要顯示任何 password/token/secret/private_key 的值。
```

## Agent 應遵守的回報格式

完成更新後，agent 回報應包含：

- 更新的 key path
- repo path
- commit hash
- 驗證方式，例如 `./scripts/get-secret.sh <key>` 成功

不應包含：

- secret value
- vault password
- 解密後完整 YAML

## 故障排除

### `Decryption failed`

通常是 `~/.config/vault-pass.txt` 不存在、權限不對、或內容不是正確密碼。

檢查：

```bash
ls -l ~/.config/vault-pass.txt
```

權限應為 `600`。

### `secrets/vault-pass.txt.zip` 不存在

代表 repo 裡沒有安裝用的密碼保護壓縮檔。請由維護者建立並提交到私有 repo，或用其他安全方式提供 vault password file。

### Gitea clone/push 失敗

檢查：

```bash
ssh -T -p 2203 git@gitea.cowbay.org
```

通常需要把該機器的 SSH public key 加到 Gitea。