openclaw secrets로 안전하게 비밀번호 관리하기

코드 여기저기에 흩어져 있는 API 키나 설정 파일에 노출된 plaintext 비밀번호 때문에 불안했던 적이 있나요? 보안을 위해 비밀번호를 관리하려고 해도, 어디에 어떤 값이 남아 있는지 일일이 찾아내고 수정하는 과정은 매우 번거롭고 실수하기 쉽습니다.

openclaw secrets는 이러한 고민을 해결하기 위해 만들어졌습니다. SecretRef를 관리하고 런타임 스냅샷을 건강하게 유지하며, 설정 파일에 남아 있는 민감한 정보를 안전하게 정리할 수 있도록 도와줍니다.

필요한 것

• OpenClaw CLI 설치
• 대화형 설정을 위한 TTY 환경 (터미널)
• 관리 권한이 있는 API 또는 Gateway 접근 권한

빠른 시작

가장 권장하는 표준 운영 루프는 다음과 같습니다. 5분 안에 보안 검사부터 적용까지 마칠 수 있습니다.

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

주요 기능 알아보기

1. Audit: 보안 취약점 스캔

audit 명령어는 OpenClaw의 상태를 스캔하여 보안 위험 요소를 찾아냅니다.

• plaintext 저장소 확인: 암호화되지 않은 비밀번호가 있는지 확인합니다.
• unresolved refs: 해결되지 않은 참조가 있는지 검사합니다.
• precedence drift: auth-profiles.json의 자격 증명이 openclaw.json의 참조를 가리고 있는지 확인합니다.
• 잔여 데이터(residues) 탐지: 생성된 모델 파일이나 과거의 인증 기록에 남아 있는 API 키나 민감한 헤더를 찾아냅니다.

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

--check 플래그를 사용하면 취약점이 발견될 때 종료 코드 1을 반환하므로 CI/CD 파이프라인에서 활용하기 좋습니다.

2. Configure: 대화형 설정 도우미

configure는 가이드에 따라 Provider를 설정하고 SecretRef 변경 사항을 구성하는 대화형 도구입니다.

openclaw secrets configure
openclaw secrets configure --plan-out /tmp/openclaw-secrets-plan.json
openclaw secrets configure --apply --yes

이 명령어는 먼저 Provider를 설정하고, 그 다음 자격 증명을 매핑한 뒤, 마지막으로 preflight 검사를 수행합니다. --agent <id> 플래그를 사용하면 특정 에이전트로 범위를 제한할 수도 있습니다.

3. Apply: 변경 사항 적용

저장된 계획(plan)을 실행하여 실제 파일에 반영합니다.

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

apply를 실행하면 openclaw.json, auth-profiles.json 등이 업데이트되며, 기존에 남아 있던 plaintext 값들은 안전하게 제거(scrub)됩니다. 보안을 위해 apply는 이전 plaintext 값을 포함하는 롤백 백업을 생성하지 않습니다.

4. Reload: 런타임 스냅샷 갱신

설정이 완료되었다면 Gateway에 반영해야 합니다.

openclaw secrets reload

이 명령어는 Gateway RPC(secrets.reload)를 호출하여 참조를 다시 확인하고 런타임 스냅샷을 원자적으로 교체합니다. 만약 참조 확인에 실패하면 기존의 정상적인 스냅샷을 유지하여 서비스 중단을 방지합니다.

문제 해결

• audit —check 실행 시 종료 코드 1이 발생해요: plaintext 비밀번호나 잔여 데이터가 발견되었다는 뜻입니다. 보고된 경로를 확인하여 수정하세요.
• 종료 코드 2가 발생해요: 해결되지 않은(unresolved) 참조가 있습니다. Provider 설정이나 ID가 정확한지 확인하세요.
• Windows에서 경로 보안 검사 실패가 떠요: ACL 확인을 사용할 수 없는 경로라면 해당 Provider에 allowInsecurePath: true를 설정하여 보안 검사를 우회할 수 있습니다.
• macOS Homebrew 바이너리를 사용하고 싶어요: /opt/homebrew/bin/*과 같은 심볼릭 링크를 사용하려면 allowSymlinkCommand: true를 설정하고, trustedDirs에 ["/opt/homebrew"]를 추가하세요.

설정 과정에서 도움이 필요하다면 언제든 AI Setup Assistant에게 물어보세요.

다음 단계

• Secrets Management
• SecretRef Credential Surface
• Security Guide
• Secrets Apply Plan Contract