1Password CLI (Hardened)
Secure secret access via 1Password CLI (op) for OpenClaw agents. Service accounts are the canonical approach.
References
references/get-started.md — install + baseline setupreferences/cli-examples.md — safe command patternsreferences/troubleshooting.md — failure/recovery runbook
Security Rules (must follow)
- Prefer
op run over all alternatives for secret injection.
- Never enable shell tracing around secret commands (
set -x, bash -x).
- Never print secrets to stdout/logs (
echo, cat on secret values/files). printf piped directly to stdin of another command (e.g., printf ... | curl -H @-) is acceptable when the output never reaches a log or terminal.
- Never dump environment inside/after secret-bearing runs (
env, printenv, set).
- Never pass secrets as CLI args (arguments can appear in process lists).
- Never pipe secret output to logs/files (
tee, >, >>) unless explicitly writing a protected temporary file for op inject.
- Never pipe
op read output into logging pipelines.
- Use
op inject only with locked-down temp files: umask 077, chmod 600, trap cleanup.
- Never include secret values in chat, tool output, or agent responses. If a command outputs a secret, do not echo or reference its value.
Banned Flags/Patterns
--no-masking — never use in agent workflows. Masking redacts accidental secret output and must stay on.--reveal — never use in routine workflows. Outputs field values in cleartext.op signin --raw — outputs raw session token to stdout.- Bare
op read — never run without capturing into a variable. It prints secrets to stdout.
set -x — never enable around any op command.curl -v — verbose mode logs auth headers. Use curl -sSf instead.script / terminal recorders — session recording captures all secret output.
Untrusted Input
- Never interpolate user-provided or external text into shell commands without strict quoting.
- Always use
-- to separate op flags from command arguments.
- Vault/item/field names from untrusted sources must be validated (alphanumeric, hyphens, underscores, and spaces only).
- Never use
eval, backtick substitution, or string-built shell commands with secret references.
- If an item name looks suspicious (contains
$, backticks, semicolons, or pipes), stop and verify with the user.
Safe dynamic input template:
VAULT="my-vault"
ITEM="my-item"
# Validate: reject names with dangerous characters
for NAME in "$VAULT" "$ITEM"; do
if ! LC_ALL=C [[ "$NAME" =~ ^[a-zA-Z0-9\ _-]+$ ]]; then
echo "ERROR: invalid vault/item name: $NAME" >&2; exit 1
fi
done
VALUE="$(op read "op://${VAULT}/${ITEM}/password")"
# use $VALUE, then:
unset VALUE
Always double-quote variable expansions. Never build op:// references from untrusted input without validation. Reject names containing /, $, backticks, semicolons, pipes, or other shell metacharacters.
.env.tpl Security
- Treat as code: verify ownership, review changes, restrict permissions (
chmod 600).
- Do not accept
.env.tpl files from untrusted sources.
- Do not commit to public repos — references reveal vault/item structure.
- Add to
.gitignore if in a repo.
- After creating/editing:
chmod 600 .env.tpl
- Only define expected variable names — reject templates containing dangerous env vars (
PATH, LD_PRELOAD, BASH_ENV, NODE_OPTIONS, etc.).
Service Account Workflow (Primary)
Service accounts are the default for agents. No interactive auth needed.
1) Load and scope token
Load the token from your platform's secure store:
# macOS Keychain:
# security find-generic-password -a <account> -s OP_SERVICE_ACCOUNT_TOKEN -w
# Linux (GNOME Keyring / libsecret):
# secret-tool lookup service OP_SERVICE_ACCOUNT_TOKEN
# Last resort (interactive prompt, not automatable):
# read -rs OP_SERVICE_ACCOUNT_TOKEN
OP_SERVICE_ACCOUNT_TOKEN="$(__REPLACE_WITH_SECURE_STORE_COMMAND__)"
[ -z "$OP_SERVICE_ACCOUNT_TOKEN" ] && { echo "ERROR: token retrieval failed" >&2; exit 1; }
Preferred: single-command scope (token never persists in shell env):
OP_SERVICE_ACCOUNT_TOKEN="$OP_SERVICE_ACCOUNT_TOKEN" \
op run --env-file=.env.tpl -- <command>
unset OP_SERVICE_ACCOUNT_TOKEN
If multiple commands needed: export briefly with trap cleanup:
export OP_SERVICE_ACCOUNT_TOKEN
trap 'unset OP_SERVICE_ACCOUNT_TOKEN' EXIT
op run --env-file=.env.tpl -- <command-1>
op run --env-file=.env.tpl -- <command-2>
unset OP_SERVICE_ACCOUNT_TOKEN
2) Use .env.tpl + op run (preferred)
Create .env.tpl with 1Password references (not raw secrets):
API_KEY=op://my-vault/my-item/api-key
DB_PASSWORD=op://my-vault/my-item/password
Run:
op run --env-file=.env.tpl -- <command>
Masking is on by default and must stay on. Note: masking is defense-in-depth, not primary protection — transformed or partial secrets may evade redaction. The primary defense is never outputting secrets.
3) One-off fallback: op read
Use only when op run doesn't fit. Use a subshell for automatic cleanup:
(
trap 'unset VALUE' EXIT
VALUE="$(op read 'op://my-vault/my-item/field')"
# use $VALUE here — auto-cleaned on exit
)
For API calls, prefer op run with a wrapper script to avoid sh -c:
# api-call.sh (chmod +x)
#!/usr/bin/env bash
set -euo pipefail
printf "Authorization: Bearer %s\n" "$API_TOKEN" | curl -sSf -H @- https://api.example.com/resource
op run --env-file=.env.tpl -- ./api-call.sh
4) Diagnostics
All diagnostic output contains metadata (account emails, vault names, item IDs, URLs) that should be treated as sensitive in logged/recorded agent sessions.
op whoami
op vault list --format json
5) Service account lifecycle
- Scope is policy-driven: read-only vs read-write depends on configuration and vault permissions.
- If access fails: verify vault grants and item permissions.
- If token expired/revoked: regenerate in 1Password admin, update secure store, retry.
- Limitation: service accounts may not support item creation depending on org policy.
op inject (restricted use)
Use only when a file must be materialized temporarily:
set -euo pipefail
set +x
umask 077
TMP_FILE="$(mktemp)"
cleanup() { rm -f "$TMP_FILE"; }
trap cleanup EXIT ERR INT TERM HUP QUIT
op inject -i config.tpl -o "$TMP_FILE"
chmod 600 "$TMP_FILE"
# use "$TMP_FILE" briefly, then auto-cleanup via trap
Never persist injected secret files beyond immediate use.
