시크릿 적용 계획 규약

이 페이지는 openclaw secrets apply가 적용하는 엄격한 규약을 정의합니다.

대상이 이 규칙과 일치하지 않으면, 설정을 변경하기 전에 적용이 실패합니다.

계획 파일 형식

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 인증 정보 표면

대상 유형 동작

일반 규칙:

target.type은 인식된 유형이어야 하며 정규화된 target.path 형태와 일치해야 합니다.

기존 계획에 대한 호환성 별칭이 계속 수용됩니다:

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를 포함하세요.

실패 동작

대상이 유효성 검사에 실패하면, 다음과 같은 오류로 적용이 종료됩니다:

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

잘못된 계획에 대해서는 쓰기가 수행되지 않습니다.

런타임 및 감사 범위 참고

Ref 전용 auth-profiles.json 항목(keyRef/tokenRef)은 런타임 확인 및 감사 범위에 포함됩니다.
secrets apply는 지원되는 openclaw.json 대상, 지원되는 auth-profiles.json 대상, 선택적 스크럽 대상을 기록합니다.

운영자 확인

# 쓰기 없이 계획 유효성 검사
openclaw secrets apply --from /tmp/openclaw-secrets-plan.json --dry-run

# 실제 적용
openclaw secrets apply --from /tmp/openclaw-secrets-plan.json

잘못된 대상 경로 메시지로 적용이 실패하면, openclaw secrets configure로 계획을 다시 생성하거나 위에서 지원되는 형태로 대상 경로를 수정하세요.