Infisical Migration

OpenClaw → Infisical Secret Migration

Move an OpenClaw instance off plaintext .env secrets onto self-hosted Infisical, and wire the Docker stack to inject them at runtime via a wrapper. Verify external CLI syntax with docs-research (Infisical CLI: https://infisical.com/docs/cli/overview).

Replace <name> with the instance name as it appears on this host (acme, demo, sandbox, … — read them from the live compose projects, never from this page; empty for the default openclaw).

Scope

• In scope: plaintext API keys/tokens in .env and inline secrets referenced by openclaw.json SecretRefs.
• Out of scope: OAuth credentials and CLI-backend tokens (openai-codex:default, Claude CLI tokens). These stay in OpenClaw's encrypted store / auth-profiles.json — never push them to Infisical. See provider-auth.

Prerequisites

• A machine identity (<machine-identity>) exists in Infisical with at least Viewer on the target project (one identity serves all instances).
• Host creds at /etc/openclaw/infisical.env (mode 600): INFISICAL_CLIENT_ID + INFISICAL_CLIENT_SECRET. Never commit this file.
• infisical CLI installed on the host.
• Reference working instance to copy from: <compose-root>/openclaw-<reference>/.
• Self-hosted domain default: https://infisical.example.com.

Step 1 — Identify the keys to migrate

# SecretRef ids referenced by openclaw.json
grep -oP '"id":\s*"\K[A-Z_][A-Z0-9_]+' "$OPENCLAW_INSTANCE_DIR/openclaw.json" | sort -u

# Keys present in the instance .env (names only)
grep -oE '^[A-Z_][A-Z0-9_]*=' "$OPENCLAW_INSTANCE_DIR/.env" 2>/dev/null | tr -d '='

Also pull in any inline secrets flagged by the security-audit skill. The union of these is the set that must exist in Infisical before any plaintext is stripped.

Step 2 — Authenticate and push to Infisical

source /etc/openclaw/infisical.env
export INFISICAL_TOKEN=$(infisical login --method=universal-auth \
  --client-id="$INFISICAL_CLIENT_ID" --client-secret="$INFISICAL_CLIENT_SECRET" \
  --domain="$INFISICAL_DOMAIN" --plain --silent)

# Push secrets (typically into the 'prod' environment)
infisical secrets set KEY1=VALUE1 KEY2=VALUE2 \
  --projectId="$PROJECT_ID" --env=prod --domain="$INFISICAL_DOMAIN" --token="$INFISICAL_TOKEN"

# Verify they list back
infisical secrets \
  --projectId="$PROJECT_ID" --env=prod --domain="$INFISICAL_DOMAIN" --token="$INFISICAL_TOKEN"

infisical secrets set accepts multiple KEY=VALUE pairs (and KEY=@/path/to/file for file-backed values). Read each value from the existing .env — never echo secret values into chat context.

Step 3 — Server files

Create .infisical.conf in the project dir:

cat > <compose-root>/openclaw-<name>/.infisical.conf <<EOF
INFISICAL_DOMAIN=https://infisical.example.com
INFISICAL_PROJECT_ID=<PROJECT_ID>
INFISICAL_ENV=prod
INFISICAL_DISABLE_UPDATE_CHECK=true
EOF
chmod 600 <compose-root>/openclaw-<name>/.infisical.conf

Copy the wrapper script from the reference instance:

mkdir -p <compose-root>/openclaw-<name>/scripts
cp <compose-root>/openclaw-<reference>/scripts/openclaw-with-infisical \
   <compose-root>/openclaw-<name>/scripts/openclaw-with-infisical
chmod +x <compose-root>/openclaw-<name>/scripts/openclaw-with-infisical

Step 4 — Patch Dockerfile

Before USER node:

RUN npm install -g @infisical/cli
COPY --chmod=0755 scripts/openclaw-with-infisical /usr/local/bin/openclaw-with-infisical

Replace the ENTRYPOINT at the end:

ENTRYPOINT ["tini", "-s", "--", "/usr/local/bin/openclaw-with-infisical"]
CMD ["node", "openclaw.mjs", "gateway", "--allow-unconfigured"]

Step 5 — Patch docker-compose.yml

For both services (openclaw-gateway-<name> and openclaw-cli-<name>), set env_file:

env_file:
  - .env
  - /etc/openclaw/infisical.env
  - .infisical.conf

For the CLI service only, replace entrypoint:

entrypoint: ["tini", "-s", "--", "/usr/local/bin/openclaw-with-infisical", "node", "dist/index.js"]

Step 6 — Build and start

cp <compose-root>/openclaw-<name>/.env <compose-root>/openclaw-<name>/.env.bak-pre-infisical
cd <compose-root>/openclaw-<name>
docker compose build openclaw-gateway-<name>
docker compose down && docker compose up -d
docker compose logs openclaw-gateway-<name> --tail=50

Success indicators: Injecting N Infisical secrets, [gateway] ready, no SecretRefResolutionError, no crash-loop.

On crash-loop with SecretRefResolutionError: a key is missing in Infisical — either add the key, or disable the skill that needs it in openclaw.json with "enabled": false.

Step 7 — Strip plaintext residue

Reduce .env to infrastructure-only vars:

OPENCLAW_IMAGE=openclaw:<name>
OPENCLAW_CONFIG_DIR=<instance-dir>
OPENCLAW_WORKSPACE_DIR=<instance-dir>/workspace
OPENCLAW_GATEWAY_PORT=<port>
OPENCLAW_BRIDGE_PORT=<port>
OPENCLAW_GATEWAY_BIND=lan
OPENCLAW_TZ=UTC

Migrate the Anthropic API key in auth-profiles.json from a literal to a SecretRef:

"keyRef": { "source": "env", "provider": "default", "id": "ANTHROPIC_API_KEY" }

Validate JSON, remove an internal .openclaw-<name>/.env if it contains only secrets, then restart:

python3 -c "import json; json.load(open('<instance-dir>/agents/main/agent/auth-profiles.json')); print('OK')"
cd <compose-root>/openclaw-<name> && docker compose down && docker compose up -d

Step 8 — Verify

docker compose exec openclaw-gateway-<name> openclaw secrets audit --check

Expected: plaintext=1, unresolved=0, shadowed=0, legacy=0. The remaining plaintext=1 is models.json:providers.codex.apiKey (sentinel "codex-app-server", not a real secret — false positive, do not touch). Then send a message to the instance's bot and confirm it replies. When working, remove the backup: rm <compose-root>/openclaw-<name>/.env.bak-pre-infisical.

Troubleshooting matrix

Maintenance commands

Critical rules

• Before stripping .env, ensure every SecretRef target exists in Infisical (Step 1 grep).
• Never commit .infisical.conf or /etc/openclaw/infisical.env.
• OAuth credentials (openai-codex:default, Claude CLI tokens) stay in OpenClaw's encrypted store — out of scope (see provider-auth).
• After OpenClaw version upgrades, re-run openclaw secrets audit --check to catch new SecretRef surfaces (see release-migration).
• Never print secret values into chat context — work with key names.