196 lines
5.0 KiB
Markdown
196 lines
5.0 KiB
Markdown
# 人類使用指南：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
|
||
```
|
||
|
||
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；交給安裝者時用另外的安全渠道。
|
||
|
||
## 給 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
|
||
```
|
||
|
||
不要把 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。
|