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.txt commit 到 git
不要把解密後完整 YAML 貼到 chat/log
Agent 回報時只回報 key path、commit hash、驗證方式，不回報 secret value

3.8 KiB Raw Permalink Blame History Unescape Escape