메인 콘텐츠로 건너뛰기

​
openclaw secrets

openclaw secrets는 SecretRef를 관리하고 active runtime snapshot을 건강하게 유지하는 데 사용합니다. Command roles:
  • reload: gateway RPC(secrets.reload)로 ref를 다시 resolve하고, 전체 성공 시에만 runtime snapshot을 교체합니다. (config write 없음)
  • audit: config, auth, generated-model store, legacy residue를 read-only로 스캔하여 plaintext, unresolved ref, precedence drift를 찾습니다.
  • configure: provider setup, target mapping, preflight를 위한 interactive planner입니다. (TTY 필요)
  • apply: 저장된 plan을 실행합니다. (--dry-run은 validation만) 이후 대상 plaintext residue를 scrub합니다.
권장 operator loop: 
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
CI/gate용 exit code:
  • audit --check는 finding이 있으면 1을 반환합니다.
  • unresolved ref는 2를 반환합니다.
Related:

​
Reload runtime snapshot

secret ref를 다시 resolve하고 runtime snapshot을 atomic하게 교체합니다. 
openclaw secrets reload
openclaw secrets reload --json
Notes:
  • gateway RPC method secrets.reload를 사용합니다.
  • resolution이 실패하면 gateway는 마지막 known-good snapshot을 유지하고 오류를 반환합니다. (partial activation 없음)
  • JSON response에는 warningCount가 포함됩니다.

​
Audit

OpenClaw state에서 다음을 스캔합니다.
  • plaintext secret storage
  • unresolved ref
  • precedence drift (auth-profiles.json credential이 openclaw.json ref를 가리는 경우)
  • generated agents/*/agent/models.json residue (provider apiKey 값과 민감한 provider header)
  • legacy residue (legacy auth store entry, OAuth reminder)
Header residue 참고:
  • 민감한 provider header 탐지는 이름 기반 heuristic입니다. (authorization, x-api-key, token, secret, password, credential 등)
openclaw secrets audit
openclaw secrets audit --check
openclaw secrets audit --json
Exit behavior:
  • --check는 finding이 있으면 non-zero로 종료합니다.
  • unresolved ref는 더 높은 우선순위의 non-zero code로 종료합니다.
Report shape highlights:
  • status: clean | findings | unresolved
  • summary: plaintextCount, unresolvedRefCount, shadowedRefCount, legacyResidueCount
  • finding code:
    • PLAINTEXT_FOUND
    • REF_UNRESOLVED
    • REF_SHADOWED
    • LEGACY_RESIDUE

​
Configure (interactive helper)

provider와 SecretRef 변경을 interactive하게 구성하고 preflight를 실행한 뒤, 원하면 바로 apply합니다. 
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
Flow:
  • 먼저 provider setup (secrets.providers alias의 add/edit/remove)
  • 다음 credential mapping (field를 선택하고 {source, provider, id} ref 할당)
  • 마지막으로 preflight와 optional apply
Flags:
  • --providers-only: secrets.providers만 구성하고 credential mapping은 건너뜁니다.
  • --skip-provider-setup: provider setup을 건너뛰고 기존 provider에 credential을 매핑합니다.
  • --agent <id>: auth-profiles.json target discovery와 write 범위를 하나의 agent store로 제한합니다.
Notes:
  • interactive TTY가 필요합니다.
  • --providers-only와 --skip-provider-setup은 함께 사용할 수 없습니다.
  • configure는 openclaw.json과 선택한 agent 범위의 auth-profiles.json에서 secret-bearing field를 대상으로 합니다.
  • configure는 picker flow에서 새로운 auth-profiles.json mapping을 직접 만드는 것도 지원합니다.
  • canonical supported surface: SecretRef Credential Surface
  • apply 전에 preflight resolution을 수행합니다.
  • 생성된 plan은 기본적으로 scrub option(scrubEnv, scrubAuthProfilesForProviderTargets, scrubLegacyAuthJson)이 모두 활성화됩니다.
  • scrub된 plaintext value에 대해 apply 경로는 되돌릴 수 없습니다.
  • --apply가 없더라도 preflight 뒤에는 Apply this plan now?를 묻습니다.
  • --apply가 있고 --yes가 없으면, 되돌릴 수 없다는 추가 확인을 한 번 더 묻습니다.
Exec provider safety note:
  • Homebrew 설치는 종종 /opt/homebrew/bin/* 아래 symlink binary를 노출합니다.
  • 필요할 때만 allowSymlinkCommand: true를 켜고, trustedDirs(예: ["/opt/homebrew"])와 함께 사용하세요.
  • Windows에서 provider path의 ACL verification을 할 수 없으면 OpenClaw는 fail-closed로 동작합니다. 신뢰하는 경로에 한해서만 해당 provider에 allowInsecurePath: true를 설정해 우회하세요.

​
Apply a saved plan

이전에 생성한 plan을 적용하거나 preflight만 실행합니다. 
openclaw secrets apply --from /tmp/openclaw-secrets-plan.json
openclaw secrets apply --from /tmp/openclaw-secrets-plan.json --dry-run
openclaw secrets apply --from /tmp/openclaw-secrets-plan.json --json
plan contract detail(허용 target path, validation rule, failure semantic): apply가 갱신할 수 있는 대상:
  • openclaw.json (SecretRef target + provider upsert/delete)
  • auth-profiles.json (provider-target scrubbing)
  • legacy auth.json residue
  • 값이 migration된 ~/.openclaw/.env의 known secret key

​
Why no rollback backups

secrets apply는 이전 plaintext 값을 담은 rollback backup을 의도적으로 만들지 않습니다. 안전성은 엄격한 preflight와, failure 시 best-effort in-memory restore를 수행하는 atomic-ish apply에서 나옵니다.

​
Example

openclaw secrets audit --check
openclaw secrets configure
openclaw secrets audit --check
audit --check가 여전히 plaintext finding을 보고하면, 남은 target path를 수정하고 audit를 다시 실행하세요.