vaultwarden-skill（金库看守技能）

Vaultwarden Skill

Manage secrets in Vaultwarden via wrapper scripts. All scripts handle session state, caching, logging, and error handling — do not call bw directly.

CLI Version Requirement — CRITICAL

Bitwarden CLI 2024.x+ breaks Vaultwarden authentication with User Decryption Options are required.

# Install the required version
npm install -g @bitwarden/cli@2023.10.0

# Verify
bw --version  # must show 2023.10.0

vw-unlock.sh will hard-exit if an incompatible version is detected.

Setup (run once)

bw config server https://vaultwarden.mbojer.dk

Required Environment Variables

Set in OpenClaw config, never stored in vault:

Collection Scoping — Personal vs Org Vaults

Personal Vaultwarden accounts cannot access collections via API key — this is a Bitwarden limitation, not a bug in this skill. bw list collections returns [] on personal vaults.

The skill handles this automatically: if no collection is found, all operations fall back to unscoped (full vault) queries. For org accounts, set VW_COLLECTION_NAME or VW_COLLECTION_ID to scope operations to a specific collection.

Session Management

vw-unlock.sh    # authenticate and unlock — run before any vault operation
vw-lock.sh      # lock vault and clear all caches
vw-status.sh    # check connection and session state
vw-sync.sh      # sync local cache with server — run if vault modified externally

Session token stored in $VW_SESSION_DIR/.bw_session (chmod 600). Collection ID cached in $VW_SESSION_DIR/.collection_id — invalidated on lock and sync. Read cache stored in $VW_SESSION_DIR/cache/ — TTL controlled by VW_CACHE_TTL.

Read Operations

All reads are collection-scoped to $VW_COLLECTION_NAME. Frequently-read items are cached with a TTL to reduce API calls.

vw-list.sh [query]               # list items in openclaw collection, optional search
vw-get.sh <name|id>              # full item JSON
vw-get-pass.sh <n>               # password only (collection-scoped, cached)
vw-get-user.sh <n>               # username only (collection-scoped, cached)
vw-get-field.sh <n> <field>      # single custom field value
vw-get-totp.sh <n>               # current TOTP code (not cached — codes expire)

Write Operations

Write operations invalidate the read cache automatically.

echo <pass> | vw-create-login.sh <n> <user>     # create login item (password via stdin)
echo <content> | vw-create-note.sh <n>           # create secure note (content via stdin)
echo <value> | vw-update.sh <id> <field>         # update field: password|username|notes|custom:<n>
vw-delete.sh <id> <expected name>                # move to trash — requires both ID and name to match
vw-rotate-pass.sh <name|id> [length]             # generate new password and update atomically

Capture rotated password cleanly (status goes to stderr):

NEW_PASS=$(vw-rotate-pass.sh "MyService")

Rules

• Always run vw-unlock.sh before vault operations, vw-lock.sh when done
• Run vw-sync.sh before reads if vault was modified via web UI or another client
• Always use item ID (not name) for vw-update.sh and vw-delete.sh
• vw-delete.sh moves items to trash — not permanent. Empty trash via web UI if needed
• All secret values must be passed via stdin — never as CLI arguments
• Never log or output raw secret values — only names, IDs, and operation results
• If any script exits non-zero, stop and report — do not retry silently
• All operations are scoped to $VW_COLLECTION_NAME when a collection is available. Personal vaults (no org) fallback to full vault — no collection required

Error Reference