6.0 KiB
人類使用指南：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。
安裝
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
接著先設定 installer env，再安裝 vault password file：
cp -n install.env.example install.env
editor install.env
./scripts/install-vault-pass.sh --check-env
./scripts/install-vault-pass.sh
重點：先填 install.env。若 --check-env 顯示資訊不足，先補齊 INSTALL_VAULT_PASS_METHOD 與對應欄位，不要直接進互動流程。
installer 會先檢查：
~/.config/vault-pass.txt
如果已存在，會保留並驗證。若不存在，會讓你選 4 種方式：
- 建立新 vault password，並在需要時建立加密 placeholder vault。
- 手動輸入 vault-pass.txt 的內容。
- 輸入 vault-pass.txt 的 URL，讓 installer 自動下載。
- 解壓 repo 內既有的密碼保護檔
secrets/vault-pass.txt.zip。
若選第 4 種，請在你自己的 terminal 輸入 zip 密碼；Telegram / chat 不能輸入到 agent 的工具互動提示。
驗證：
./scripts/vault.sh view
建立安裝用密碼保護壓縮檔
維護者若要讓其他 agent / 機器安裝，先在已可解密的機器上執行：
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 檔：
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，再執行：
INSTALL_ENV_FILE=install.local.env ./scripts/install-vault-pass.sh --check-env
./scripts/install-vault-pass.sh
給 agent 的全自動安裝方式
如果目標是「AI agent 直接安裝，不要卡在互動輸入密碼」，請不要讓 agent 選互動 zip 解壓。改用環境變數指定方法：
# 一次性 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
cd ~/projects/agent-secret-vault
./scripts/vault.sh view
編輯 vault
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
./scripts/get-secret.sh gitea.api_token
./scripts/get-secret.sh openclaw_alice.http_nodes.gitea.password
用自然語言請 agent 操作 secrets
你可以直接對 agent 下這類命令：
查詢但不要顯示 secret
幫我確認 agent-secret-vault 裡有沒有 gitea.api_token，不要把 token 印出來。
Agent 應該只回報「有 / 沒有」與使用的 key path，不應顯示 token。
使用 secret 去登入或呼叫 API
用 agent-secret-vault 裡的 openclaw_alice.http_nodes.gitea 帳密登入 Gitea，登入成功後回報狀態，不要把帳密貼出來。
Agent 可以讀取 secret 並用於 browser/API，但不能把 secret value 回傳聊天。
新增 secret
幫我把新的 API token 加到 agent-secret-vault，key 放在 openclaw_alice.http_nodes.example_service.api_token；先 git pull，更新後驗證可讀，再 commit/push。不要在回報中顯示 token。
如果 token 需要由你提供，請用安全渠道或互動輸入；不要把高敏感 token 直接貼到公開群組。
修改 secret
把 agent-secret-vault 裡 openclaw_alice.http_nodes.gitea.password 更新成我等一下提供的新密碼；完成後只回報 commit hash 和驗證方式。
列出 key 結構
列出 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 不存在、權限不對、或內容不是正確密碼。
檢查：
ls -l ~/.config/vault-pass.txt
權限應為 600。
secrets/vault-pass.txt.zip 不存在
代表 repo 裡沒有安裝用的密碼保護壓縮檔。請由維護者建立並提交到私有 repo，或用其他安全方式提供 vault password file。
Gitea clone/push 失敗
檢查：
ssh -T -p 2203 git@gitea.cowbay.org
通常需要把該機器的 SSH public key 加到 Gitea。