OpenClaw secrets apply: 계획 파일 검증 및 적용 가이드

비밀번호나 API 키 같은 민감한 정보를 관리하는 일은 언제나 긴장되는 작업이에요. 설정 파일 하나만 잘못 건드려도 서비스 전체가 마비될 수 있으니까요. openclaw secrets apply는 이런 실수를 방지하기 위해 아주 엄격한 규칙(Contract)을 적용하고 있어요.

설정이 이 규칙에 맞지 않으면, 시스템을 변경하기 전에 실행을 중단해서 안전을 보장합니다. 구체적으로 어떤 규칙들이 있는지 함께 살펴볼까요?

플랜 파일 형태

openclaw secrets apply --from <plan.json> 명령어는 targets 배열을 포함한 다음과 같은 구조의 데이터를 기대해요.

{
  version: 1,
  protocolVersion: 1,
  targets: [
    {
      type: "models.providers.apiKey",
      path: "models.providers.openai.apiKey",
      pathSegments: ["models", "providers", "openai", "apiKey"],
      providerId: "openai",
      ref: { source: "env", provider: "default", id: "OPENAI_API_KEY" },
    },
    {
      type: "auth-profiles.api_key.key",
      path: "profiles.openai:default.key",
      pathSegments: ["profiles", "openai:default", "key"],
      agentId: "main",
      ref: { source: "env", provider: "default", id: "OPENAI_API_KEY" },
    },
  ],
}

지원되는 타겟 범위

플랜 타겟은 다음 문서에 정의된 지원 가능한 자격 증명 경로에 대해서만 허용돼요.

• SecretRef Credential Surface

타겟 타입 동작 방식

가장 기본적인 규칙은 이렇습니다.

• target.type은 반드시 인식 가능한 값이어야 하며, 정규화된 target.path 형태와 일치해야 해요.

기존 플랜과의 호환성을 위해 아래와 같은 별칭(Alias)들도 계속 지원하고 있어요.

• models.providers.apiKey
• skills.entries.apiKey
• channels.googlechat.serviceAccount

경로 검증 규칙

각 타겟은 다음의 모든 항목을 통과해야 검증이 완료돼요.

• type은 인식 가능한 타겟 타입이어야 합니다.
• path는 비어 있지 않은 점(dot) 경로여야 합니다.
• pathSegments는 생략할 수 있지만, 만약 제공된다면 path와 정확히 일치하도록 정규화되어야 합니다.
• __proto__, prototype, constructor와 같이 금지된 세그먼트는 거부됩니다.
• 정규화된 경로는 해당 타겟 타입에 등록된 경로 형태와 일치해야 합니다.
• providerId나 accountId가 설정된 경우, 경로에 인코딩된 ID와 일치해야 합니다.
• auth-profiles.json 타겟은 agentId가 필수입니다.
• 새로운 auth-profiles.json 매핑을 생성할 때는 authProfileProvider를 포함해야 합니다.

실패 시 동작

타겟 검증에 실패하면, apply 명령은 다음과 같은 에러 메시지를 출력하며 종료돼요.

Invalid plan target path for models.providers.apiKey: models.providers.openai.baseUrl

플랜이 유효하지 않으면 그 어떤 데이터도 기록되지 않으니 안심하세요.

런타임 및 감사 범위 참고 사항

• keyRef나 tokenRef를 사용하는 참조 전용 auth-profiles.json 항목들도 런타임 해석 및 감사(Audit) 범위에 포함됩니다.
• secrets apply는 지원되는 openclaw.json 타겟, auth-profiles.json 타겟, 그리고 선택적인 scrub 타겟을 기록합니다.

운영자 확인 사항

실제로 데이터를 쓰기 전에 --dry-run 플래그를 사용해서 플랜을 미리 검증해 보는 것이 좋습니다.

# Validate plan without writes
openclaw secrets apply --from /tmp/openclaw-secrets-plan.json --dry-run

# Then apply for real
openclaw secrets apply --from /tmp/openclaw-secrets-plan.json

만약 잘못된 타겟 경로 메시지와 함께 apply가 실패한다면, openclaw secrets configure 명령어로 플랜을 다시 생성하거나 타겟 경로를 지원되는 형태로 수정해 주세요.

관련 문서

• Secrets Management
• CLI secrets
• SecretRef Credential Surface
• Configuration Reference

---

더 궁금한 점이 있나요? AI Setup Assistant에게 물어보세요!

다음 단계

• Secrets Management 이해하기
• CLI secrets 명령어 익히기