# 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`](docs/human-guide.md)
- Agent 安裝 Runbook：[`docs/agent-install-runbook.md`](docs/agent-install-runbook.md)
- Agent 整合補充：[`docs/agent-integration.md`](docs/agent-integration.md)
- Vault 基礎說明：[`docs/secret-vault.md`](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` 指定。

## 安裝流程（先設定 env）

安裝前請先設定 `install.env`，再檢查 env 是否足夠，最後才正式安裝：

```bash
cp -n install.env.example install.env
editor install.env
./scripts/install-vault-pass.sh --check-env
./scripts/install-vault-pass.sh
```

`install.env` 範例：

```bash
# 例：用一次性 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`，不要直接進互動選單：

```bash
INSTALL_ENV_FILE=install.local.env ./scripts/install-vault-pass.sh --check-env
INSTALL_ENV_FILE=install.local.env ./scripts/install-vault-pass.sh
```

## 常用指令

```bash
# 安裝 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