English简体中文繁體中文日本語EspañolPortuguês (BR)한국어DeutschFrançaisالعربيةItalianoTiếng ViệtNederlandsTürkçeУкраїнськаBahasa IndonesiaPolskiفارسیไทย

CLI commands

시크릿

openclaw secrets

openclaw secrets를 사용해 SecretRefs를 관리하고 활성 런타임 스냅샷을 정상 상태로 유지하세요.

명령 역할:

  • reload: ref를 다시 확인하고 완전히 성공했을 때만 런타임 스냅샷을 교체하는 gateway RPC(secrets.reload)입니다(config 쓰기 없음).
  • audit: 평문, 확인되지 않은 ref, 우선순위 드리프트에 대해 구성/auth/생성된 모델 저장소와 레거시 잔여물을 읽기 전용으로 스캔합니다(--allow-exec를 설정하지 않으면 exec ref는 건너뜀).
  • configure: provider 설정, 대상 매핑, 사전 점검을 위한 대화형 planner입니다(TTY 필요).
  • apply: 저장된 plan을 실행합니다(검증만 하려면 --dry-run, dry-run은 기본적으로 exec 검사를 건너뛰고, 쓰기 모드는 --allow-exec를 설정하지 않으면 exec가 포함된 plan을 거부함). 이후 대상 평문 잔여물을 스크럽합니다.

권장 운영 루프:

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

plan에 exec SecretRefs/providers가 포함되어 있으면 dry-run과 쓰기 apply 명령 모두에 --allow-exec를 전달하세요.

CI/게이트용 종료 코드 참고:

  • audit --check는 항목이 있으면 1을 반환합니다.
  • 확인되지 않은 ref는 2를 반환합니다.

관련 항목:

런타임 스냅샷 다시 로드

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

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

참고:

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

옵션:

  • --url <url>
  • --token <token>
  • --timeout <ms>
  • --json

감사

다음 항목에 대해 OpenClaw 상태를 스캔합니다.

  • 평문 시크릿 저장
  • 확인되지 않은 ref
  • 우선순위 드리프트(auth-profiles.json 자격 증명이 openclaw.json ref를 가리는 경우)
  • 생성된 agents/*/agent/models.json 잔여물(provider apiKey 값 및 민감한 provider 헤더)
  • 레거시 잔여물(레거시 auth 저장소 항목, OAuth reminder)

헤더 잔여물 참고:

  • 민감한 provider 헤더 감지는 이름 휴리스틱 기반입니다(일반적인 auth/credential 헤더 이름과 authorization, x-api-key, token, secret, password, credential 같은 조각).
openclaw secrets audit
openclaw secrets audit --check
openclaw secrets audit --json
openclaw secrets audit --allow-exec

종료 동작:

  • --check는 항목이 있으면 0이 아닌 코드로 종료합니다.
  • 확인되지 않은 ref는 더 높은 우선순위의 0이 아닌 코드로 종료합니다.

보고서 형태 핵심:

  • status: clean | findings | unresolved
  • resolution: refsChecked, skippedExecRefs, resolvabilityComplete
  • summary: plaintextCount, unresolvedRefCount, shadowedRefCount, legacyResidueCount
  • 항목 코드:
    • PLAINTEXT_FOUND
    • REF_UNRESOLVED
    • REF_SHADOWED
    • LEGACY_RESIDUE

구성(대화형 헬퍼)

대화형으로 provider 및 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

흐름:

  • 먼저 provider 설정(secrets.providers 별칭에 대해 add/edit/remove)
  • 다음으로 자격 증명 매핑(필드 선택 후 {source, provider, id} ref 할당)
  • 마지막으로 사전 점검 및 선택적 적용

플래그:

  • --providers-only: secrets.providers만 구성하고 자격 증명 매핑은 건너뜀
  • --skip-provider-setup: provider 설정을 건너뛰고 기존 providers에 자격 증명을 매핑
  • --agent <id>: auth-profiles.json 대상 탐색 및 쓰기를 하나의 에이전트 저장소로 범위 제한
  • --allow-exec: 사전 점검/적용 중 exec SecretRef 검사를 허용(provider 명령을 실행할 수 있음)

참고:

  • 대화형 TTY가 필요합니다.
  • --providers-only와 --skip-provider-setup은 함께 사용할 수 없습니다.
  • configure는 openclaw.json의 시크릿 포함 필드와 선택한 에이전트 범위의 auth-profiles.json을 대상으로 합니다.
  • configure는 picker 흐름에서 직접 새 auth-profiles.json 매핑 생성도 지원합니다.
  • 정식 지원 표면: SecretRef 자격 증명 표면
  • 적용 전에 사전 점검 확인을 수행합니다.
  • 사전 점검/적용에 exec ref가 포함되면 두 단계 모두 --allow-exec를 유지하세요.
  • 생성된 plan은 기본적으로 스크럽 옵션(scrubEnv, scrubAuthProfilesForProviderTargets, scrubLegacyAuthJson 모두 활성화)을 포함합니다.
  • apply 경로는 스크럽된 평문 값에 대해 단방향입니다.
  • --apply 없이도 CLI는 사전 점검 후 Apply this plan now?를 계속 묻습니다.
  • --apply 사용 시(--yes 없음) CLI는 추가로 되돌릴 수 없는 확인을 묻습니다.
  • --json은 plan + 사전 점검 보고서를 출력하지만, 명령에는 여전히 대화형 TTY가 필요합니다.

Exec provider 안전 참고:

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

저장된 plan 적용

이전에 생성한 plan을 적용하거나 사전 점검합니다.

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

Exec 동작:

  • --dry-run은 파일을 쓰지 않고 사전 점검을 검증합니다.
  • dry-run에서는 기본적으로 exec SecretRef 검사를 건너뜁니다.
  • 쓰기 모드는 --allow-exec가 설정되지 않으면 exec SecretRefs/providers가 포함된 plan을 거부합니다.
  • 어느 모드에서든 exec provider 검사/실행에 opt in하려면 --allow-exec를 사용하세요.

plan 계약 세부 정보(허용된 대상 경로, 검증 규칙, 실패 의미):

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

  • openclaw.json(SecretRef 대상 + provider upsert/delete)
  • auth-profiles.json(provider 대상 스크럽)
  • 레거시 auth.json 잔여물
  • 값이 마이그레이션된 ~/.openclaw/.env의 알려진 시크릿 키

롤백 백업이 없는 이유

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

안전성은 엄격한 사전 점검 + 실패 시 최선의 노력 방식 메모리 복원을 포함한 거의 원자적 적용에서 나옵니다.

예시

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

audit --check가 여전히 평문 항목을 보고하면, 남아 있는 보고 대상 경로를 업데이트하고 감사를 다시 실행하세요.

관련