| name | openclaw-add-secret |
| description | Add a new secret to the OpenClaw keychain and update the appropriate launcher/secrets script |
Add Secret to Keychain
Add a new secret with keychain service $0 and environment variable $1.
Reference
Read ~/.openclaw/workspace/skills/06-security-model.md for the full security model.
Setup Detection
OPENCLAW_REPO=$(readlink ~/.openclaw/openclaw.json 2>/dev/null | sed 's|/.openclaw/openclaw.json||')
TIER_CONFIGS=(~/.openclaw/configs/openclaw-*.json)
[[ -f "${TIER_CONFIGS[0]}" ]] && MULTI_GATEWAY=true || MULTI_GATEWAY=false
Steps
-
Ask the user for the secret value. Do NOT echo it back after they provide it.
-
Determine tier (multi-gateway only): Ask the user which tier this secret belongs to. List available tiers:
for cfg in ~/.openclaw/configs/openclaw-*.json; do
basename "$cfg" | sed 's/openclaw-//;s/.json//'
done
- Store in keychain:
security add-generic-password -s "$0" -a "openclaw" -w "<VALUE>" ~/.openclaw/openclaw.keychain-db
Multi-gateway naming convention
- Keychain service:
openclaw-<tier>-<service-name> (lowercase, hyphens)
- Env var:
OPENCLAW_<SERVICE_NAME> (uppercase, underscores)
Single-gateway naming convention
- Keychain service:
openclaw.<service-name> (lowercase, hyphens)
- Env var:
OPENCLAW_<SERVICE_NAME> (uppercase, underscores)
- Update the secrets loader script:
Multi-gateway
Add export line to the tier's launcher script at $OPENCLAW_REPO/.openclaw/scripts/start-<tier>.sh (before the exec block):
export $1=$(kc "$0")
The launcher script uses a kc() helper to read from keychain. Follow the existing pattern in the file.
Single-gateway
Add export line to $OPENCLAW_REPO/.openclaw/scripts/openclaw-secrets.sh (before the exec block):
export $1=$(security find-generic-password -s "$0" -w "$KC")
- Update openclaw-env.sh (optional, for shell access) — Add export line to
$OPENCLAW_REPO/.openclaw/scripts/openclaw-env.sh:
export $1=$(security find-generic-password -s "$0" -w "$KC" 2>/dev/null)
Note: openclaw-env.sh uses 2>/dev/null on all lookups for silent failure.
- Update secrets.sh — Add to the SECRETS array in
$OPENCLAW_REPO/secrets.sh:
"$0|$1|<description>"
- Stow and restart:
rm -f ~/.openclaw/cron/jobs.json
cd "$OPENCLAW_REPO" && stow --no-folding -t ~ .
Multi-gateway
launchctl kickstart -k gui/$(id -u)/ai.openclaw.gateway.<tier>
Single-gateway
launchctl kickstart -k gui/$(id -u)/ai.openclaw.gateway
- Verify the secret can be read. For multi-gateway, use the launcher script to load env vars:
bash ~/.openclaw/scripts/start-<tier>.sh printenv "$1" | wc -c
For single-gateway:
source ~/.openclaw/scripts/openclaw-env.sh && printenv "$1" | wc -c
Should output a non-zero character count.
Important
- NEVER echo the secret value back to the user
- NEVER write the secret value to any file (only the keychain)