비밀 정보 관리

OpenClaw는 지원되는 자격 증명을 구성에 평문으로 저장하지 않아도 되도록 추가형 SecretRef를 지원합니다.

목표와 런타임 모델

시크릿은 메모리 내 런타임 스냅샷으로 해석됩니다.

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

이렇게 하면 시크릿 제공자 장애가 주요 요청 경로에 영향을 주지 않습니다.

에이전트 접근 경계

SecretRef는 지원되는 구성 및 생성된 모델 표면에 자격 증명이 지속 저장되지 않도록 보호하지만, 프로세스 격리 경계는 아닙니다. 에이전트가 읽을 수 있는 경로의 디스크에 평문 자격 증명이 남아 있으면, 에이전트는 파일 또는 셸 도구로 해당 파일을 검사해 API 수준의 수정 처리를 우회할 수 있습니다.

에이전트가 접근할 수 있는 파일이 범위에 포함되는 프로덕션 배포에서는 다음이 모두 참일 때에만 SecretRef 마이그레이션이 완료된 것으로 간주하세요.

• 지원되는 자격 증명이 평문 값 대신 SecretRef를 사용합니다.
• 레거시 평문 잔여물이 openclaw.json, auth-profiles.json, .env, 생성된 models.json 파일에서 제거되었습니다.
• 마이그레이션 후 openclaw secrets audit --check가 깨끗합니다.
• 남아 있는 지원되지 않는 자격 증명 또는 순환 자격 증명이 운영 체제 격리, 컨테이너 격리 또는 외부 자격 증명 프록시로 보호됩니다.

이것이 audit/configure/apply 워크플로가 단순한 편의 헬퍼가 아니라 보안 마이그레이션 게이트인 이유입니다.

활성 표면 필터링

SecretRef는 실질적으로 활성 상태인 표면에서만 검증됩니다.

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

Gateway 인증 표면 진단

SecretRef가 gateway.auth.token, gateway.auth.password, gateway.remote.token 또는 gateway.remote.password에 구성되면 Gateway 시작/다시 로드가 표면 상태를 명시적으로 기록합니다.

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

이 항목은 SECRETS_GATEWAY_AUTH_SURFACE와 함께 기록되며 활성 표면 정책에서 사용한 이유를 포함하므로, 자격 증명이 왜 활성 또는 비활성으로 처리되었는지 확인할 수 있습니다.

온보딩 참조 사전 점검

온보딩이 대화형 모드로 실행되고 SecretRef 저장소를 선택하면 OpenClaw는 저장하기 전에 사전 점검 검증을 실행합니다.

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

검증이 실패하면 온보딩은 오류를 표시하고 다시 시도할 수 있게 합니다.

SecretRef 계약

모든 곳에서 하나의 객체 형태를 사용하세요:

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

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

"${OPENAI_API_KEY}""$OPENAI_API_KEY"

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

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

제공자 구성

secrets.providers 아래에 제공자를 정의합니다.

{  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,      },      "team-secrets": {        source: "exec",        pluginIntegration: {          pluginId: "acme-secrets",          integrationId: "secret-store",        },      },    },    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" } }}

파일 기반 API 키

구성 env 블록에 file:... 문자열을 넣지 마세요. env 블록은 리터럴이며 재정의하지 않으므로 file:...은 해석되지 않습니다.

대신 지원되는 자격 증명 필드에 file SecretRef를 사용하세요.

{  secrets: {    providers: {      xai_key_file: {        source: "file",        path: "~/.openclaw/secrets/xai-api-key.txt",        mode: "singleValue",      },    },  },  models: {    providers: {      xai: {        apiKey: { source: "file", provider: "xai_key_file", id: "value" },      },    },  },}

mode: "singleValue"의 경우 SecretRef id는 "value"입니다. mode: "json"의 경우 "/providers/xai/apiKey" 같은 절대 JSON 포인터를 사용하세요.

SecretRef를 허용하는 구성 필드는 SecretRef 자격 증명 표면을 참조하세요.

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: {      bws: {        source: "exec",        command: "/usr/local/bin/openclaw-bws-resolver.mjs",        passEnv: ["BWS_ACCESS_TOKEN", "BWS_SERVER_URL", "PATH", "BWS_BIN"],        jsonOnly: true,      },    },  },  models: {    providers: {      openai: {        baseUrl: "https://api.openai.com/v1",        models: [{ id: "gpt-5", name: "gpt-5" }],        apiKey: {          source: "exec",          provider: "bws",          id: "openclaw/providers/openai/apiKey",        },      },    },  },}

openclaw secrets audit --allow-exec

{  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" },      },    },  },}

#!/usr/bin/env nodeconst { spawnSync } = require("node:child_process"); let stdin = "";process.stdin.setEncoding("utf8");process.stdin.on("data", (chunk) => {  stdin += chunk;});process.stdin.on("error", (err) => {  process.stderr.write(`${err.message}\n`);  process.exit(1);});process.stdin.on("end", () => {  let request;  try {    request = JSON.parse(stdin || "{}");  } catch (err) {    process.stderr.write(`Failed to parse request: ${err.message}\n`);    process.exit(1);  }   const passBin = process.env.PASS_BIN || "pass";  const values = {};  const errors = {};   for (const id of request.ids ?? []) {    const result = spawnSync(passBin, ["show", id], { encoding: "utf8" });    if (result.status === 0) {      values[id] = result.stdout.split(/\r?\n/, 1)[0] ?? "";    } else {      errors[id] = { message: (result.stderr || `pass exited ${result.status}`).trim() };    }  }   process.stdout.write(JSON.stringify({ protocolVersion: 1, values, errors }));});

{  secrets: {    providers: {      pass_store: {        source: "exec",        command: "/usr/local/bin/openclaw-pass-resolver",        passEnv: ["PATH", "HOME", "GNUPGHOME", "GPG_TTY", "PASSWORD_STORE_DIR", "PASS_BIN"],        jsonOnly: true,      },    },  },  models: {    providers: {      openai: {        baseUrl: "https://api.openai.com/v1",        models: [{ id: "gpt-5", name: "gpt-5" }],        apiKey: {          source: "exec",          provider: "pass_store",          id: "openclaw/providers/openai/apiKey",        },      },    },  },}

openclaw secrets audit --checkopenclaw secrets audit --allow-exec

{  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.config.mcpServers를 통해 구성된 MCP 서버 env var는 SecretInput을 지원합니다. 이를 통해 API 키와 토큰을 평문 구성에 넣지 않을 수 있습니다.

{  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",                },              },            },          },        },      },    },  },}

평문 문자열 값도 계속 작동합니다. ${MCP_SERVER_API_KEY} 같은 Env 템플릿 참조와 SecretRef 객체는 MCP 서버 프로세스가 생성되기 전 Gateway 활성화 중에 해석됩니다. 다른 SecretRef 표면과 마찬가지로, 해석되지 않은 참조는 acpx Plugin이 실질적으로 활성 상태일 때만 활성화를 차단합니다.

샌드박스 SSH 인증 자료

코어 ssh 샌드박스 백엔드도 SSH 인증 자료에 대해 SecretRef를 지원합니다.

{  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 호출 중에 지연 처리하지 않고, 샌드박스 활성화 중에 이 참조들을 해석합니다.
• 해석된 값은 제한적인 권한의 임시 파일에 기록되며 생성된 SSH 구성에서 사용됩니다.
• 유효한 샌드박스 백엔드가 ssh가 아니면 이 참조들은 비활성 상태로 유지되며 시작을 차단하지 않습니다.

지원되는 자격 증명 표면

표준 지원 및 미지원 자격 증명은 다음에 나열되어 있습니다.

• SecretRef 자격 증명 표면

필수 동작 및 우선순위

• 참조가 없는 필드: 변경 없음.
• 참조가 있는 필드: 활성 표면에서 활성화 중 필수.
• 평문과 참조가 모두 있으면 지원되는 우선순위 경로에서는 참조가 우선합니다.
• 삭제 표시 센티널 __OPENCLAW_REDACTED__는 내부 구성 삭제 표시/복원용으로 예약되어 있으며 리터럴 제출 구성 데이터로는 거부됩니다.

경고 및 감사 신호:

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

Google Chat 호환성 동작:

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

활성화 트리거

비밀 활성화는 다음에서 실행됩니다.

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

활성화 계약:

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

성능 저하 및 복구 신호

정상 상태 이후 reload 시점 활성화가 실패하면 OpenClaw는 성능 저하 비밀 상태로 진입합니다.

일회성 시스템 이벤트 및 로그 코드:

• SECRETS_RELOADER_DEGRADED
• SECRETS_RELOADER_RECOVERED

동작:

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

명령 경로 해석

명령 경로는 Gateway 스냅샷 RPC를 통해 지원되는 SecretRef 해석을 선택할 수 있습니다.

두 가지 넓은 동작이 있습니다:

기타 참고 사항:

• 백엔드 비밀 회전 후 스냅샷 새로 고침은 openclaw secrets reload가 처리합니다.
• 이 명령 경로들이 사용하는 Gateway RPC 메서드: secrets.resolve.

감사 및 구성 워크플로

기본 운영자 흐름:

openclaw secrets audit --check

openclaw secrets configure --apply

openclaw secrets audit --check

다시 감사가 깨끗하게 통과하기 전까지 마이그레이션이 완료된 것으로 간주하지 마세요. 감사에서 저장된 평문 값이 여전히 보고되면, 런타임 API가 수정된 값을 반환하더라도 에이전트 접근 위험은 여전히 존재합니다.

configure 중 적용하는 대신 계획을 저장했다면, 다시 감사하기 전에 openclaw secrets apply --from <plan-path>로 저장된 계획을 적용하세요.

openclaw secrets apply --from /tmp/openclaw-secrets-plan.jsonopenclaw secrets apply --from /tmp/openclaw-secrets-plan.json --allow-execopenclaw secrets apply --from /tmp/openclaw-secrets-plan.json --dry-runopenclaw secrets apply --from /tmp/openclaw-secrets-plan.json --dry-run --allow-exec

단방향 안전 정책

안전 모델:

• 쓰기 모드 전에 사전 확인이 성공해야 합니다.
• 커밋 전에 런타임 활성화가 검증됩니다.
• 적용은 원자적 파일 교체와 실패 시 최선 노력 복원을 사용해 파일을 업데이트합니다.

레거시 auth 호환성 참고

정적 자격 증명의 경우, 런타임은 더 이상 평문 레거시 auth 저장소에 의존하지 않습니다.

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

Web UI 참고

일부 SecretInput 유니언은 폼 모드보다 원시 편집기 모드에서 구성하기가 더 쉽습니다.

관련 항목

• Authentication — auth 설정
• CLI: secrets — CLI 명령
• Environment Variables — 환경 우선순위
• SecretRef Credential Surface — 자격 증명 표면
• Secrets Apply Plan Contract — 계획 계약 세부 정보
• Security — 보안 태세