비밀 정보 관리

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

​

목표와 런타임 모델

• 해석은 요청 경로에서 지연 처리되지 않고, 활성화 중에 즉시 수행됩니다.
• 실질적으로 활성 상태인 SecretRef를 해석할 수 없으면 시작이 빠르게 실패합니다.
• 다시 로드는 원자적 교체를 사용합니다. 전체 성공이거나, 마지막으로 정상 확인된 스냅샷을 유지합니다.
• SecretRef 정책 위반(예: OAuth 모드 인증 프로필과 SecretRef 입력 결합)은 런타임 교체 전에 활성화를 실패시킵니다.
• 런타임 요청은 활성 메모리 내 스냅샷에서만 읽습니다.
• 첫 번째 구성 활성화/로드가 성공한 후에는, 성공적인 다시 로드가 스냅샷을 교체할 때까지 런타임 코드 경로가 해당 활성 메모리 내 스냅샷을 계속 읽습니다.
• 발신 전달 경로도 해당 활성 스냅샷에서 읽습니다(예: Discord 응답/스레드 전달 및 Telegram 작업 전송). 전송할 때마다 SecretRefs를 다시 해석하지 않습니다.

​

활성 표면 필터링

• 활성화된 표면: 해석되지 않은 참조가 시작/다시 로드를 차단합니다.
• 비활성 표면: 해석되지 않은 참조가 시작/다시 로드를 차단하지 않습니다.
• 비활성 참조는 SECRETS_REF_IGNORED_INACTIVE_SURFACE 코드와 함께 치명적이지 않은 진단을 내보냅니다.

​

Gateway 인증 표면 진단

• active: SecretRef가 유효 인증 표면의 일부이며 해석되어야 합니다.
• inactive: 다른 인증 표면이 우선하거나 원격 인증이 비활성화/비활성 상태이므로 이 런타임에서 SecretRef가 무시됩니다.

​

온보딩 참조 사전 검사

• Env 참조: env var 이름을 검증하고 설정 중 비어 있지 않은 값이 보이는지 확인합니다.
• Provider 참조(file 또는 exec): Provider 선택을 검증하고, id를 해석하며, 해석된 값 유형을 확인합니다.
• Quickstart 재사용 경로: gateway.auth.token이 이미 SecretRef인 경우, 온보딩은 동일한 빠른 실패 게이트를 사용하여 probe/dashboard 부트스트랩 전에 이를 해석합니다(env, file, exec 참조).

​

SecretRef 계약

{ source: "env" | "file" | "exec", provider: "default", id: "..." }

{ source: "env", provider: "default", id: "OPENAI_API_KEY" }

{ source: "file", provider: "filemain", id: "/providers/openai/apiKey" }

{ source: "exec", provider: "vault", id: "providers/openai/apiKey" }

​

Provider 구성

{
  secrets: {
    providers: {
      default: { source: "env" },
      filemain: {
        source: "file",
        path: "~/.openclaw/secrets.json",
        mode: "json", // or "singleValue"
      },
      vault: {
        source: "exec",
        command: "/usr/local/bin/openclaw-vault-resolver",
        args: ["--profile", "prod"],
        passEnv: ["PATH", "VAULT_ADDR"],
        jsonOnly: true,
      },
    },
    defaults: {
      env: "default",
      file: "filemain",
      exec: "vault",
    },
    resolution: {
      maxProviderConcurrency: 4,
      maxRefsPerProvider: 512,
      maxBatchBytes: 262144,
    },
  },
}

{ "protocolVersion": 1, "provider": "vault", "ids": ["providers/openai/apiKey"] }

{ "protocolVersion": 1, "values": { "providers/openai/apiKey": "<openai-api-key>" } } // pragma: allowlist secret

{
  "protocolVersion": 1,
  "values": {},
  "errors": { "providers/openai/apiKey": { "message": "not found" } }
}

​

Exec 통합 예시

{
  secrets: {
    providers: {
      onepassword_openai: {
        source: "exec",
        command: "/opt/homebrew/bin/op",
        allowSymlinkCommand: true, // required for Homebrew symlinked binaries
        trustedDirs: ["/opt/homebrew"],
        args: ["read", "op://Personal/OpenClaw QA API Key/password"],
        passEnv: ["HOME"],
        jsonOnly: false,
      },
    },
  },
  models: {
    providers: {
      openai: {
        baseUrl: "https://api.openai.com/v1",
        models: [{ id: "gpt-5", name: "gpt-5" }],
        apiKey: { source: "exec", provider: "onepassword_openai", id: "value" },
      },
    },
  },
}

{
  secrets: {
    providers: {
      vault_openai: {
        source: "exec",
        command: "/opt/homebrew/bin/vault",
        allowSymlinkCommand: true, // required for Homebrew symlinked binaries
        trustedDirs: ["/opt/homebrew"],
        args: ["kv", "get", "-field=OPENAI_API_KEY", "secret/openclaw"],
        passEnv: ["VAULT_ADDR", "VAULT_TOKEN"],
        jsonOnly: false,
      },
    },
  },
  models: {
    providers: {
      openai: {
        baseUrl: "https://api.openai.com/v1",
        models: [{ id: "gpt-5", name: "gpt-5" }],
        apiKey: { source: "exec", provider: "vault_openai", id: "value" },
      },
    },
  },
}

{
  secrets: {
    providers: {
      sops_openai: {
        source: "exec",
        command: "/opt/homebrew/bin/sops",
        allowSymlinkCommand: true, // required for Homebrew symlinked binaries
        trustedDirs: ["/opt/homebrew"],
        args: ["-d", "--extract", '["providers"]["openai"]["apiKey"]', "/path/to/secrets.enc.json"],
        passEnv: ["SOPS_AGE_KEY_FILE"],
        jsonOnly: false,
      },
    },
  },
  models: {
    providers: {
      openai: {
        baseUrl: "https://api.openai.com/v1",
        models: [{ id: "gpt-5", name: "gpt-5" }],
        apiKey: { source: "exec", provider: "sops_openai", id: "value" },
      },
    },
  },
}

​

MCP 서버 환경 변수

{
  plugins: {
    entries: {
      acpx: {
        enabled: true,
        config: {
          mcpServers: {
            github: {
              command: "npx",
              args: ["-y", "@modelcontextprotocol/server-github"],
              env: {
                GITHUB_PERSONAL_ACCESS_TOKEN: {
                  source: "env",
                  provider: "default",
                  id: "MCP_GITHUB_PAT",
                },
              },
            },
          },
        },
      },
    },
  },
}

​

Sandbox SSH 인증 자료

{
  agents: {
    defaults: {
      sandbox: {
        mode: "all",
        backend: "ssh",
        ssh: {
          target: "user@gateway-host:22",
          identityData: { source: "env", provider: "default", id: "SSH_IDENTITY" },
          certificateData: { source: "env", provider: "default", id: "SSH_CERTIFICATE" },
          knownHostsData: { source: "env", provider: "default", id: "SSH_KNOWN_HOSTS" },
        },
      },
    },
  },
}

• OpenClaw는 각 SSH 호출 중에 지연 처리하지 않고, 샌드박스 활성화 중에 이러한 ref를 해석합니다.
• 해석된 값은 제한적인 권한이 적용된 임시 파일에 기록되며 생성된 SSH config에서 사용됩니다.
• 유효한 샌드박스 백엔드가 ssh가 아니면 이러한 ref는 비활성 상태로 유지되며 시작을 차단하지 않습니다.

​

지원되는 자격 증명 표면

• SecretRef 자격 증명 표면

​

필수 동작 및 우선순위

• ref가 없는 필드: 변경되지 않음.
• ref가 있는 필드: 활성 표면에서는 활성화 중에 필수입니다.
• 평문과 ref가 모두 있으면 지원되는 우선순위 경로에서는 ref가 우선합니다.
• 수정 마스킹 센티널 __OPENCLAW_REDACTED__는 내부 config 수정 마스킹/복원용으로 예약되어 있으며, 제출된 config 데이터의 리터럴 값으로는 거부됩니다.

• SECRETS_REF_OVERRIDES_PLAINTEXT (런타임 경고)
• REF_SHADOWED (auth-profiles.json 자격 증명이 openclaw.json ref보다 우선할 때의 감사 결과)

• serviceAccountRef가 평문 serviceAccount보다 우선합니다.
• 형제 ref가 설정되어 있으면 평문 값은 무시됩니다.

​

활성화 트리거

• 시작(사전 검사 및 최종 활성화)
• Config reload hot-apply path
• Config reload restart-check path
• secrets.reload를 통한 수동 reload
• 편집을 저장하기 전 제출된 config 페이로드 내 활성 표면 SecretRef 해석 가능성을 확인하는 Gateway config write RPC 사전 검사(config.set / config.apply / config.patch)

• 성공하면 스냅샷을 원자적으로 교체합니다.
• 시작 실패는 Gateway 시작을 중단합니다.
• 런타임 reload 실패는 마지막으로 정상 확인된 스냅샷을 유지합니다.
• Write-RPC 사전 검사 실패는 제출된 config를 거부하고 디스크 config와 활성 런타임 스냅샷을 모두 변경하지 않습니다.
• 아웃바운드 helper/tool 호출에 명시적인 호출별 채널 토큰을 제공해도 SecretRef 활성화는 트리거되지 않습니다. 활성화 지점은 시작, reload, 명시적 secrets.reload로 유지됩니다.

​

성능 저하 및 복구 신호

• SECRETS_RELOADER_DEGRADED
• SECRETS_RELOADER_RECOVERED

• 성능 저하: 런타임은 마지막으로 정상 확인된 스냅샷을 유지합니다.
• 복구됨: 다음 활성화 성공 후 한 번 방출됩니다.
• 이미 성능 저하 상태인 동안 반복되는 실패는 경고를 기록하지만 이벤트를 스팸으로 방출하지 않습니다.
• 시작 fail-fast는 런타임이 활성 상태가 된 적이 없으므로 성능 저하 이벤트를 방출하지 않습니다.

​

명령 경로 해석

• 백엔드 시크릿 순환 후 스냅샷 새로 고침은 openclaw secrets reload가 처리합니다.
• 이러한 명령 경로에서 사용되는 Gateway RPC 메서드: secrets.resolve.

​

감사 및 구성 워크플로

openclaw secrets audit --check

openclaw secrets configure

openclaw secrets audit --check

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

​

단방향 안전 정책

• write mode 전에 사전 검사가 성공해야 합니다.
• commit 전에 런타임 활성화가 검증됩니다.
• apply는 원자적 파일 교체와 실패 시 best-effort restore를 사용해 파일을 업데이트합니다.

​

레거시 auth 호환성 참고 사항

• 런타임 자격 증명 소스는 해석된 인메모리 스냅샷입니다.
• 레거시 static api_key 항목은 발견되면 정리됩니다.
• OAuth 관련 호환성 동작은 별도로 유지됩니다.

​

Web UI 참고

​

관련 항목

• 인증 — auth 설정
• CLI: secrets — CLI 명령
• 환경 변수 — 환경 우선순위
• SecretRef 자격 증명 표면 — 자격 증명 표면
• Secrets Apply Plan Contract — 계획 계약 세부 정보
• 보안 — 보안 태세