agent-secret-vault/docs/agent-integration.md

Agent 整合指南

本 vault 供本地 AI agent（Hermes、OpenClaw、cron worker 等）安全存取機密資訊使用。

基本資訊

• vault 位置：~/projects/agent-secret-vault/secrets/vault.yml
• vault password 位置：~/.config/vault-pass.txt
• 加密格式：ansible-vault（AES256）

Agent 讀取 secrets 的方法

方法 1：用 vault.sh 腳本（推薦）

cd ~/projects/agent-secret-vault

# 檢視 vault 內容
./scripts/vault.sh view

# 解密到暫存檔（用完記得刪）
./scripts/vault.sh decrypt /tmp/vault.yml

# 讀特定 section
python3 - <<'PY'
import yaml
with open('/tmp/vault.yml') as f:
    data = yaml.safe_load(f)
    print(data['gitea']['api_token'])
PY

rm -f /tmp/vault.yml

方法 2：用 get-secret 工具（最快）

如果你有 scripts/get-secret.sh：

./scripts/get-secret.sh gitea.api_token

方法 3：用 render-env.sh（適合 worker）

# 渲染成 env 檔
./scripts/render-env.sh gitea > /tmp/gitea.env
source /tmp/gitea.env
# 現在 $GITEA_API_TOKEN 可用
rm /tmp/gitea.env

常見錯誤

1. vault password file 不存在

解決：

cd ~/projects/agent-secret-vault
./scripts/vault.sh init

2. permission denied

確認：

chmod 600 ~/.config/vault-pass.txt

3. ansible-vault not found

確認已安裝 ansible：

which ansible-vault

重要原則

1. 不要把解密後的 vault 明文寫進 log
2. 不要把 secrets 直接寫進 prompt
3. 用完暫存檔立刻刪除
4. 不要把 vault-pass.txt 提交到 git

現有 secrets 清單

vault 內目前有這些 section：

• gitea：開發用 Gitea 帳號（ Hermestest 用）
• openclaw_alice：Alice 的完整 secrets（15+ 服務）

取用時用 dot notation：

• gitea.api_token
• openclaw_alice.http_nodes.gitea.password

如果要新增 secrets

1. 先解密：

   ./scripts/vault.sh decrypt /tmp/vault.yml
   

2. 編輯：

   vim /tmp/vault.yml
   

3. 重新加密：

   ./scripts/vault.sh encrypt /tmp/vault.yml
   cp /tmp/vault.yml secrets/vault.yml
   

4. commit 並 push