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；安裝前先填入 vault-pass 來源設定
常用變數說明：
| 變數 | 用途 | 範例 |
|---|---|---|
VAULT_PASS_FILE |
最後要產生/使用的 vault password file 路徑 | $HOME/.config/vault-pass.txt |
INSTALL_VAULT_PASS_METHOD |
指定安裝方式；可填 create、manual、url、archive |
url |
VAULT_PASS_URL |
當 method=url 時，從這個 URL 下載 vault-pass.txt |
https://example.com/one-time/vault-pass.txt |
VAULT_PASS_ZIP_PASSWORD_FILE |
當 method=archive 時，讀取 zip 密碼的本機檔案路徑；比直接寫密碼安全 |
/secure/path/zip-password.txt |
VAULT_PASS_ZIP_PASSWORD |
當 method=archive 時，直接提供 zip 密碼；只適合安全 shell，不建議寫進可提交檔案 |
... |
VAULT_PASS_CONTENT |
當 method=manual 時，直接提供 vault-pass.txt 內容；高風險，只適合受控環境 |
... |
VAULT_PASS_ARCHIVE |
覆寫密碼保護 zip 的路徑；預設是 secrets/vault-pass.txt.zip |
/path/to/vault-pass.txt.zip |
安裝方式含義：
create：產生新的 vault password；只適合全新 vault，既有 vault 無法解密時不會自動覆蓋。manual：由人類輸入或用VAULT_PASS_CONTENT提供 vault password 內容。url：從VAULT_PASS_URL下載vault-pass.txt；適合一次性 URL / 內網安全下載。archive：從密碼保護 zip 解出vault-pass.txt；密碼可放在VAULT_PASS_ZIP_PASSWORD_FILE或VAULT_PASS_ZIP_PASSWORD。
install.env 不應填入真實 secrets 後再 commit；若要保存本機私密設定，使用 install.local.env 並透過 INSTALL_ENV_FILE=install.local.env 指定。
安裝流程（先設定 env）
安裝前請先設定 install.env，再檢查 env 是否足夠，最後才正式安裝：
cp -n install.env.example install.env
editor install.env
./scripts/install-vault-pass.sh --check-env
./scripts/install-vault-pass.sh
install.env 範例：
# 例：用一次性 URL 安裝 vault-pass.txt
INSTALL_VAULT_PASS_METHOD="url"
VAULT_PASS_URL="https://example.com/one-time/vault-pass.txt"
全自動 agent 安裝
Agent / CI 也應優先設定 install.env 或 INSTALL_ENV_FILE，不要直接進互動選單：
INSTALL_ENV_FILE=install.local.env ./scripts/install-vault-pass.sh --check-env
INSTALL_ENV_FILE=install.local.env ./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.txtcommit 到 git - 不要把解密後完整 YAML 貼到 chat/log
- Agent 回報時只回報 key path、commit hash、驗證方式，不回報 secret value