> ## Documentation Index
> Fetch the complete documentation index at: https://docs2.openclaw.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 시크릿

# `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을 거부함). 이후 대상 평문 잔여물을 스크럽합니다.

권장 운영 루프:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
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`를 반환합니다.

관련 항목:

* 시크릿 가이드: [시크릿 관리](/ko/gateway/secrets)
* 자격 증명 표면: [SecretRef 자격 증명 표면](/ko/reference/secretref-credential-surface)
* 보안 가이드: [보안](/ko/gateway/security)

## 런타임 스냅샷 다시 로드

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

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
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` 같은 조각).

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
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 변경을 구성하고, 사전 점검을 실행한 뒤, 선택적으로 적용합니다.

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
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 자격 증명 표면](/ko/reference/secretref-credential-surface)
* 적용 전에 사전 점검 확인을 수행합니다.
* 사전 점검/적용에 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을 적용하거나 사전 점검합니다.

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
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 계약 세부 정보(허용된 대상 경로, 검증 규칙, 실패 의미):

* [시크릿 적용 Plan 계약](/ko/gateway/secrets-plan-contract)

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

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

## 롤백 백업이 없는 이유

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

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

## 예시

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
openclaw secrets audit --check
openclaw secrets configure
openclaw secrets audit --check
```

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

## 관련

* [CLI 참조](/ko/cli)
* [시크릿 관리](/ko/gateway/secrets)