`openclaw secrets`

openclaw secrets를 사용하여 SecretRef를 관리하고 활성 런타임 스냅샷을 건강하게 유지합니다.

명령 역할:

reload: 게이트웨이 RPC(secrets.reload)로 참조를 다시 확인하고 완전 성공 시에만 런타임 스냅샷을 교체합니다 (설정 쓰기 없음).
audit: 구성/인증/생성된 모델 스토어 및 레거시 잔존물에서 평문, 미확인 참조, 우선순위 드리프트를 읽기 전용으로 스캔합니다.
configure: 프로바이더 설정, 대상 매핑, 사전 검증을 위한 대화형 플래너 (TTY 필요).
apply: 저장된 플랜을 실행하고(--dry-run으로 검증만 가능) 대상 평문 잔존물을 정리합니다.

권장 운영 루프:

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/게이트 종료 코드 참고:

audit --check는 발견 시 1을 반환합니다.
미확인 참조는 2를 반환합니다.

런타임 스냅샷 리로드

시크릿 참조를 다시 확인하고 런타임 스냅샷을 원자적으로 교체합니다.

openclaw secrets reload
openclaw secrets reload --json

참고사항:

게이트웨이 RPC 메서드 secrets.reload를 사용합니다.
확인에 실패하면 게이트웨이는 마지막으로 알려진 정상 스냅샷을 유지하고 오류를 반환합니다 (부분 활성화 없음).
JSON 응답에 warningCount가 포함됩니다.

감사

OpenClaw 상태에서 다음을 스캔합니다:

평문 시크릿 저장
미확인 참조
우선순위 드리프트 (auth-profiles.json 인증 정보가 openclaw.json 참조를 가리는 경우)
생성된 agents/*/agent/models.json 잔존물 (프로바이더 apiKey 값 및 민감한 프로바이더 헤더)
레거시 잔존물 (레거시 인증 스토어 항목, OAuth 알림)

헤더 잔존물 참고:

민감한 프로바이더 헤더 감지는 이름 휴리스틱 기반입니다 (authorization, x-api-key, token, secret, password, credential 등의 일반적인 인증/인증 정보 헤더 이름 및 조각).

openclaw secrets audit
openclaw secrets audit --check
openclaw secrets audit --json

종료 동작:

--check는 발견 시 0이 아닌 코드로 종료합니다.
미확인 참조는 더 높은 우선순위의 0이 아닌 코드로 종료합니다.

보고서 형태 하이라이트:

status: clean | findings | unresolved
summary: plaintextCount, unresolvedRefCount, shadowedRefCount, legacyResidueCount
발견 코드:
- PLAINTEXT_FOUND
- REF_UNRESOLVED
- REF_SHADOWED
- LEGACY_RESIDUE

구성 (대화형 도우미)

프로바이더와 SecretRef 변경 사항을 대화형으로 구성하고, 사전 검증을 실행하고, 선택적으로 적용합니다:

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

플로우:

프로바이더 설정 먼저 (secrets.providers 별칭에 대한 add/edit/remove).
인증 정보 매핑 다음 (필드 선택 및 {source, provider, id} 참조 할당).
사전 검증 및 선택적 적용 마지막.

플래그:

--providers-only: secrets.providers만 구성, 인증 정보 매핑 건너뛰기.
--skip-provider-setup: 프로바이더 설정을 건너뛰고 기존 프로바이더에 인증 정보 매핑.
--agent <id>: auth-profiles.json 대상 검색 및 쓰기를 하나의 에이전트 스토어로 범위 지정.

참고사항:

대화형 TTY가 필요합니다.
--providers-only와 --skip-provider-setup은 함께 사용할 수 없습니다.
configure는 선택된 에이전트 범위에 대해 openclaw.json의 시크릿 필드와 auth-profiles.json을 대상으로 합니다.
configure는 선택기 플로우에서 직접 새로운 auth-profiles.json 매핑 생성을 지원합니다.
정식 지원 범위: SecretRef Credential Surface.
적용 전 사전 검증을 수행합니다.
생성된 플랜은 기본적으로 정리 옵션이 활성화됩니다 (scrubEnv, scrubAuthProfilesForProviderTargets, scrubLegacyAuthJson 모두 활성).
적용 경로는 정리된 평문 값에 대해 단방향입니다.
--apply 없이도 사전 검증 후 이 플랜을 지금 적용하시겠습니까?라고 묻습니다.
--apply가 있고 --yes가 없으면 추가 되돌릴 수 없음 확인을 요청합니다.

실행 프로바이더 안전 참고:

Homebrew 설치는 종종 /opt/homebrew/bin/* 아래에 심볼릭 링크된 바이너리를 노출합니다.
신뢰할 수 있는 패키지 관리자 경로에 필요한 경우에만 allowSymlinkCommand: true를 설정하고, trustedDirs (예: ["/opt/homebrew"])와 함께 사용하세요.
Windows에서 프로바이더 경로에 대한 ACL 검증을 사용할 수 없는 경우, OpenClaw는 안전하게 실패합니다. 신뢰할 수 있는 경로에 한해 해당 프로바이더에 allowInsecurePath: true를 설정하여 경로 보안 검사를 우회할 수 있습니다.

저장된 플랜 적용

이전에 생성된 플랜을 적용하거나 사전 검증합니다:

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

플랜 계약 세부 사항 (허용되는 대상 경로, 검증 규칙, 실패 의미론):

Secrets Apply Plan Contract

apply가 업데이트할 수 있는 항목:

openclaw.json (SecretRef 대상 + 프로바이더 업서트/삭제)
auth-profiles.json (프로바이더 대상 정리)
레거시 auth.json 잔존물
~/.openclaw/.env에서 마이그레이션된 알려진 시크릿 키

롤백 백업이 없는 이유

secrets apply는 의도적으로 이전 평문 값을 포함하는 롤백 백업을 생성하지 않습니다.

안전성은 엄격한 사전 검증 + 실패 시 최선의 인메모리 복원을 통한 원자적 적용에서 옵니다.

예시

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

audit --check가 여전히 평문 발견을 보고하는 경우, 보고된 나머지 대상 경로를 업데이트하고 감사를 다시 실행하세요.