agent-secret-vault/README.md

Agent Secret Vault

本 repo 專門管理本地 AI agent / worker 需要的機密資料。

核心設計

• 使用 ansible-vault 加密 secrets/vault.yml
• 加密後的 secrets/vault.yml 可以進 git
• vault password file 放在本機：~/.config/vault-pass.txt
• 新機器可透過 repo 內的密碼保護壓縮檔 secrets/vault-pass.txt.zip 安裝 password file
• 多個 agent 透過統一腳本讀取 secrets，不各自發明 credential 管理方式

主要文件

• 人類使用指南：docs/human-guide.md
• Agent 安裝 Runbook：docs/agent-install-runbook.md
• Agent 整合補充：docs/agent-integration.md
• Vault 基礎說明：docs/secret-vault.md

安裝設定檔

Repo 內提供：

• install.env.example：給人類/agent 複製參考
• install.env：空值 placeholder，可在安裝前填入 INSTALL_VAULT_PASS_METHOD、VAULT_PASS_URL、VAULT_PASS_ZIP_PASSWORD_FILE 等設定

install.env 不應填入真實 secrets 後再 commit；若要保存本機私密設定，使用 install.local.env 並透過 INSTALL_ENV_FILE=install.local.env 指定。

全自動 agent 安裝

# 例：用一次性 URL 安裝 vault-pass.txt
INSTALL_VAULT_PASS_METHOD=url \
VAULT_PASS_URL="https://example.com/one-time/vault-pass.txt" \
./scripts/install-vault-pass.sh

常用指令

# 安裝 vault password file（會要求輸入壓縮檔密碼）
./scripts/install-vault-pass.sh

# 維護者建立密碼保護壓縮檔
./scripts/create-vault-pass-archive.sh

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

# 編輯 vault
./scripts/vault.sh edit

# 讀單一 secret
./scripts/get-secret.sh openclaw_alice.http_nodes.gitea.password

安全原則

• 不要把 ~/.config/vault-pass.txt commit 到 git
• 不要把解密後完整 YAML 貼到 chat/log
• Agent 回報時只回報 key path、commit hash、驗證方式，不回報 secret value