Secrets

기준일: 2026-07-26
공식 기준: Secrets

Secrets 문서는 OpenClaw 공식 문서(cli/secrets)를 한국어로 정리한 가이드입니다. CLI reference for openclaw secrets (reload, audit, configure, apply) 명령·설정 키·코드 예시는 공식 문서를 그대로 보존하며, 해석과 절차 안내는 한국어로 제공합니다. 최종 동작은 설치된 CLI 버전과 공식 원문을 확인하세요.

핵심 요약

CLI reference for openclaw secrets (reload, audit, configure, apply)

한국어 가이드 범위: cli/secrets 경로의 설정·명령·제약·예시를 학습용으로 재구성합니다.

문서 구성

공식 문서의 주요 섹션은 다음과 같습니다.

• Reload runtime snapshot
• Audit
• Configure (interactive helper)
• Exec provider safety
• Apply a saved plan
• Why no rollback backups
• 예제
• 관련 문서

상세 내용

openclaw secrets

Manage SecretRefs and keep the active runtime snapshot healthy.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

주요 항목:

• audit --check returns 1 on findings.
• Unresolved refs return 2 (regardless of --check).

Command	Role
reload	Gateway RPC (secrets.reload): re-resolves refs and atomically publishes the owner-aware runtime snapshot (no config writes); eligible owner failures may publish as cold or stale warnings
audit	Read-only scan of config/auth/generated-model stores and legacy residues for plaintext, unresolved refs, and precedence drift (exec refs skipped unless --allow-exec)
configure	Interactive planner for provider setup, target mapping, and preflight (requires a TTY)
apply	Executes a saved plan (--dry-run validates only and skips exec checks by default; write mode rejects exec-containing plans unless --allow-exec), then scrubs targeted plaintext residues

openclaw secrets audit --check
openclaw secrets configure
openclaw secrets apply --from /tmp/openclaw-secrets-plan.json --dry-run
openclaw secrets apply --from /tmp/openclaw-secrets-plan.json
openclaw secrets audit --check
openclaw secrets reload

Reload runtime snapshot

Uses gateway RPC method secrets.reload. Healthy owners refresh independently. Eligible failed owners become stale only when their ref identities, provider definitions, and complete non-secret owner contract are unchanged; new or changed failures become cold. This degraded activation succeeds and reports warningCount. Strict or unmapped failures return an error and preserve the previously active snapshot.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

openclaw secrets reload
openclaw secrets reload --json
openclaw secrets reload --url ws://127.0.0.1:18789 --token <token>

Audit

The .env scan covers the effective state directory and the directory containing the active config. When both paths name the same file, it is scanned once.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

주요 항목:

• plaintext secret storage
• unresolved refs
• precedence drift (auth-profiles.json credentials shadowing openclaw.json refs)
• generated agents/*/agent/models.json residues (provider apiKey values and sensitive provider headers)
• legacy residues (legacy auth store entries, OAuth reminders)
• status: clean | findings | unresolved
• resolution: refsChecked, skippedExecRefs, resolvabilityComplete
• summary: plaintextCount, unresolvedRefCount, shadowedRefCount, legacyResidueCount
• finding codes: PLAINTEXT_FOUND, REF_UNRESOLVED, REF_SHADOWED, LEGACY_RESIDUE

openclaw secrets audit
openclaw secrets audit --check
openclaw secrets audit --json
openclaw secrets audit --allow-exec

Configure (interactive helper)

Build provider and SecretRef changes interactively, run preflight, and optionally apply:

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

주요 항목:

• --providers-only: configure secrets.providers only, skip credential mapping
• --skip-provider-setup: skip provider setup, map credentials to existing providers
• --agent <id>: scope auth-profiles.json target discovery and writes to one agent store
• --allow-exec: allow exec SecretRef checks during preflight/apply (may execute provider commands)
• Requires an interactive TTY.
• Targets secret-bearing fields in openclaw.json plus auth-profiles.json for the selected agent scope; canonical supported surface: SecretRef Credential Surface.
• Supports creating new auth-profiles.json mappings directly in the picker flow.
• Runs preflight resolution before apply.
• Generated plans default to scrub options enabled (scrubEnv, scrubAuthProfilesForProviderTargets, scrubLegacyAuthJson). Apply is one-way for scrubbed plaintext values.
• --plan-out refuses to create a plan whose UTF-8 serialized form exceeds 16 MiB (16,777,216 bytes), matching the apply --from input limit.
• Without --apply, the CLI still prompts Apply this plan now? after preflight.
• With --apply (and no --yes), the CLI prompts an extra irreversible-migration confirmation.
• --json prints the plan + preflight report, but still requires an interactive TTY.

openclaw secrets configure
openclaw secrets configure --plan-out /tmp/openclaw-secrets-plan.json
openclaw secrets configure --apply --yes
openclaw secrets configure --providers-only
openclaw secrets configure --skip-provider-setup
openclaw secrets configure --agent ops
openclaw secrets configure --json

Exec provider safety

Homebrew installs often expose symlinked binaries under /opt/homebrew/bin/*. Set allowSymlinkCommand: true only when needed for trusted package-manager paths, paired with trustedDirs (for example ["/opt/homebrew"]). On Windows, if ACL verification is unavailable for a provider path, OpenClaw fails closed; for trusted paths only, set allowInsecurePath: true on that provider to bypass the path security check.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

Apply a saved plan

--dry-run validates preflight without writing files; exec SecretRef checks are skipped by default in dry-run. Write mode rejects plans containing exec SecretRefs/providers unless --allow-exec. Use --allow-exec to opt in to exec provider checks/execution in either mode.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

주요 항목:

• openclaw.json (SecretRef targets + provider upserts/deletes)
• auth-profiles.json (provider-target scrubbing)
• legacy auth.json residues
• .env files in the effective state and active-config directories, for known secret keys whose values were migrated

openclaw secrets apply --from /tmp/openclaw-secrets-plan.json
openclaw secrets apply --from /tmp/openclaw-secrets-plan.json --allow-exec
openclaw secrets apply --from /tmp/openclaw-secrets-plan.json --dry-run
openclaw secrets apply --from /tmp/openclaw-secrets-plan.json --dry-run --allow-exec
openclaw secrets apply --from /tmp/openclaw-secrets-plan.json --json

Why no rollback backups

secrets apply intentionally does not write rollback backups containing old plaintext values. Safety comes from strict preflight plus atomic-ish apply, with best-effort in-memory restore on failure.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

예제

If audit --check still reports plaintext findings, update the remaining reported target paths and rerun audit.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

openclaw secrets audit --check
openclaw secrets configure
openclaw secrets audit --check

관련 문서

주요 항목:

• CLI reference
• Secrets management
• Vault SecretRefs

실습 체크리스트

1. 공식 문서와 로컬 버전을 대조합니다: https://docs.openclaw.ai/cli/secrets
2. 관련 CLI는 openclaw --help 및 하위 명령 --help로 옵션을 확인합니다.
3. 설정 변경 시 openclaw config / openclaw doctor로 유효성을 검사합니다.
4. Gateway·채널·플러그인 변경 후에는 필요 시 Gateway를 재시작합니다.

자주 쓰는 명령·설정 예시

openclaw secrets audit --check
openclaw secrets configure
openclaw secrets apply --from /tmp/openclaw-secrets-plan.json --dry-run
openclaw secrets apply --from /tmp/openclaw-secrets-plan.json
openclaw secrets audit --check
openclaw secrets reload

openclaw secrets reload
openclaw secrets reload --json
openclaw secrets reload --url ws://127.0.0.1:18789 --token <token>

openclaw secrets audit
openclaw secrets audit --check
openclaw secrets audit --json
openclaw secrets audit --allow-exec

openclaw secrets configure
openclaw secrets configure --plan-out /tmp/openclaw-secrets-plan.json
openclaw secrets configure --apply --yes
openclaw secrets configure --providers-only
openclaw secrets configure --skip-provider-setup
openclaw secrets configure --agent ops
openclaw secrets configure --json

openclaw secrets apply --from /tmp/openclaw-secrets-plan.json
openclaw secrets apply --from /tmp/openclaw-secrets-plan.json --allow-exec
openclaw secrets apply --from /tmp/openclaw-secrets-plan.json --dry-run
openclaw secrets apply --from /tmp/openclaw-secrets-plan.json --dry-run --allow-exec
openclaw secrets apply --from /tmp/openclaw-secrets-plan.json --json

openclaw secrets audit --check
openclaw secrets configure
openclaw secrets audit --check

관련 링크

• 공식 원문: cli/secrets
• OpenClaw 문서 홈

이 가이드는 공식 문서를 한국어 학습용으로 재구성한 것입니다. 옵션 기본값·플래그 이름은 설치 버전에 따라 달라질 수 있습니다.