# 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 腳本（推薦）

```bash
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`：

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

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

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

## 常見錯誤

### 1. vault password file 不存在

解決：
```bash
cd ~/projects/agent-secret-vault
./scripts/vault.sh init
```

### 2. permission denied

確認：
```bash
chmod 600 ~/.config/vault-pass.txt
```

### 3. ansible-vault not found

確認已安裝 ansible：
```bash
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. 先解密：
   ```bash
   ./scripts/vault.sh decrypt /tmp/vault.yml
   ```

2. 編輯：
   ```bash
   vim /tmp/vault.yml
   ```

3. 重新加密：
   ```bash
   ./scripts/vault.sh encrypt /tmp/vault.yml
   cp /tmp/vault.yml secrets/vault.yml
   ```

4. commit 並 push