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.

bash

# 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)#

bash

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

Required Environment Variables#

Set in OpenClaw config, never stored in vault:

VariablePurposeBW_CLIENTIDAPI key client IDBW_CLIENTSECRETAPI key client secretBW_PASSWORDMaster password for unlockVW_COLLECTION_NAMECollection name to scope to (default: openclaw) — org accounts onlyVW_COLLECTION_IDHardcode collection ID — use if name lookup fails (org accounts only)VW_SESSION_DIRSession token dir (default: /run/openclaw/vw)VW_LOG_FILEAudit log path (default: /var/log/openclaw/vaultwarden.log)VW_CACHE_TTLRead cache TTL in seconds (default: 60, set 0 to disable)

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#

bash

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.

bash

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.

bash

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):

bash

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#

ErrorFixbw CLI X.X.X is incompatible``npm install -g @bitwarden/cli@2023.10.0``User Decryption Options are requiredSame as above — wrong CLI versionno active sessionRun vw-unlock.sh``session invalid or expiredRun vw-unlock.sh``collection not foundCheck VW_COLLECTION_NAME, run vw-sync.sh``name mismatchVerify item ID with vw-get.sh before deletingcustom field does not existCheck field name with vw-get.sh``server not configuredRun bw config server https://vaultwarden.mbojer.dk``API key login failedCheck BW_CLIENTID and BW_CLIENTSECRET