1Password Service Account

Securely inject secrets from 1Password into agent workflows. Uses service accounts with op run/.env.tpl as the primary pattern, op read as fallback. Includes hardened security rules, input validation, and troubleshooting for auth/permission failures. Use when accessing API keys, credentials, or any 1Password secret.

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 setup
• references/cli-examples.md — safe command patterns
• references/troubleshooting.md — failure/recovery runbook

Security Rules (must follow)

1. Prefer op run over all alternatives for secret injection.
2. Never enable shell tracing around secret commands (set -x, bash -x).
3. 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.
4. Never dump environment inside/after secret-bearing runs (env, printenv, set).
5. Never pass secrets as CLI args (arguments can appear in process lists).
6. Never pipe secret output to logs/files (tee, >, >>) unless explicitly writing a protected temporary file for op inject.
7. Never pipe op read output into logging pipelines.
8. Use op inject only with locked-down temp files: umask 077, chmod 600, trap cleanup.
9. 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:

bash

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:

bash

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

bash

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:

bash

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

text

API_KEY=op://my-vault/my-item/api-key
DB_PASSWORD=op://my-vault/my-item/password

Run:

bash

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:

bash

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

bash

# 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

bash

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.

bash

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:

bash

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.