SecretRef credential surface

기준일: 2026-07-26
공식 기준: SecretRef credential surface

SecretRef credential surface 문서는 OpenClaw 공식 문서(reference/secretref-credential-surface)를 한국어로 정리한 가이드입니다. Canonical supported vs unsupported SecretRef credential surface 명령·설정 키·코드 예시는 공식 문서를 그대로 보존하며, 해석과 절차 안내는 한국어로 제공합니다. 최종 동작은 설치된 CLI 버전과 공식 원문을 확인하세요.

핵심 요약

Canonical supported vs unsupported SecretRef credential surface

한국어 가이드 범위: reference/secretref-credential-surface 경로의 설정·명령·제약·예시를 학습용으로 재구성합니다.

문서 구성

공식 문서의 주요 섹션은 다음과 같습니다.

• Supported credentials
• auth-profiles.json targets (secrets configure + secrets apply + secrets audit)
• Unsupported credentials
• 관련 문서

상세 내용

본문

This page defines the canonical SecretRef credential surface: which credential fields accept a SecretRef (env/file/exec-backed reference) instead of a raw secret value.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

주요 항목:

• In scope: strictly user-supplied credentials that OpenClaw does not mint or rotate.
• Out of scope: runtime-minted or rotating credentials, OAuth refresh material, and session-like artifacts.

Supported credentials

이 섹션의 세부 항목은 공식 문서 Supported credentials를 참고하세요.

openclaw.json targets (secrets configure + secrets apply + secrets audit)

주요 항목:

• models.providers.*.apiKey
• models.providers.*.headers.*
• models.providers.*.request.auth.token
• models.providers.*.request.auth.value
• models.providers.*.request.headers.*
• models.providers.*.request.proxy.tls.ca
• models.providers.*.request.proxy.tls.cert
• models.providers.*.request.proxy.tls.key
• models.providers.*.request.proxy.tls.passphrase
• models.providers.*.request.tls.ca
• models.providers.*.request.tls.cert
• models.providers.*.request.tls.key
• models.providers.*.request.tls.passphrase
• skills.entries.*.apiKey
• memory.search.remote.apiKey
• agents.entries.*.tts.providers.*.apiKey
• agents.entries.*.memory.search.remote.apiKey
• talk.providers.*.apiKey
• talk.realtime.providers.*.apiKey
• tts.providers.*.apiKey
• plugins.entries.acpx.config.mcpServers.*.env.*
• plugins.entries.brave.config.webSearch.apiKey
• plugins.entries.codex.config.appServer.authToken
• plugins.entries.codex.config.appServer.headers.*
• plugins.entries.exa.config.webSearch.apiKey

auth-profiles.json targets (secrets configure + secrets apply + secrets audit)

주요 항목:

• profiles.*.keyRef (type: "api_key"; unsupported when auth.profiles.<id>.mode = "oauth")
• profiles.*.tokenRef (type: "token"; unsupported when auth.profiles.<id>.mode = "oauth")
• Auth-profile plan targets require agentId; plan entries target profiles.*.key / profiles.*.token and write sibling refs (keyRef / tokenRef). Auth-profile refs are included in runtime resolution and audit coverage.
• In openclaw.json, SecretRefs must use structured objects such as {"source":"env","provider":"default","id":"DISCORD_BOT_TOKEN"}. Legacy secretref-env:<ENV_VAR> marker strings are rejected on SecretRef credential paths; run openclaw doctor --fix to migrate valid markers.
• OAuth policy guard: auth.profiles.<id>.mode = "oauth" cannot be combined with SecretRef inputs for that profile. Startup/reload and auth-profile resolution fail fast when this policy is violated.
• For SecretRef-managed model providers, generated agents/*/agent/models.json entries persist non-secret markers (not resolved secret values) for apiKey/header surfaces. Marker persistence is source-authoritative: OpenClaw writes markers from the active source config snapshot (pre-resolution), not from resolved runtime secret values.
• Cold Gateway startup can isolate retryable resolution failures for mapped, non-Gateway owners. Current mapped classes include model providers and skills, media/TTS/cron providers, eligible auth profiles, per-agent memory, sandbox SSH, channel accounts, and manifest-declared plugin routes. Startup keeps each failed owner's explicit refs in the runtime snapshot, reports the owner through status and doctor, and rejects requests for that owner without trying lower-precedence credentials. Reload and config-write preflight use the same owner-aware policy: healthy owners refresh; an eligible failed owner stays stale only when its ref identities, provider definitions, and complete non-secret owner contract are unchanged; a new or changed failure becomes cold. Gateway ingress auth, structurally invalid refs or values, fail-closed owners, and currently unmapped owners remain strict.
• For web search: in explicit provider mode (tools.web.search.provider set), only the selected provider key is active. In auto mode (tools.web.search.provider unset), only the first provider key that resolves by precedence is active, and non-selected provider refs are treated as inactive until selected. Provider credentials use plugins.entries.<plugin>.config.webSearch.*.
• Slack identity: "user" uses channels.slack.userToken with channels.slack.appToken for Socket Mode or channels.slack.signingSecret for HTTP mode. The same pairing applies under channels.slack.accounts.*; no bot token is required for this identity.

Unsupported credentials

These credentials are minted, rotated, session-bearing, or OAuth-durable classes that do not fit read-only external SecretRef resolution:

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

주요 항목:

• hooks.token
• hooks.gmail.pushToken
• hooks.mappings[].sessionKey
• auth-profiles.oauth.*
• channels.discord.threadBindings.webhookToken
• channels.discord.accounts.*.threadBindings.webhookToken
• channels.whatsapp.creds.json
• channels.whatsapp.accounts.*.creds.json

관련 문서

주요 항목:

• Secrets management
• Auth credential semantics

실습 체크리스트

1. 공식 문서와 로컬 버전을 대조합니다: https://docs.openclaw.ai/reference/secretref-credential-surface
2. 관련 CLI는 openclaw --help 및 하위 명령 --help로 옵션을 확인합니다.
3. 설정 변경 시 openclaw config / openclaw doctor로 유효성을 검사합니다.
4. Gateway·채널·플러그인 변경 후에는 필요 시 Gateway를 재시작합니다.

관련 링크

• 공식 원문: reference/secretref-credential-surface
• OpenClaw 문서 홈

이 가이드는 공식 문서를 한국어 학습용으로 재구성한 것입니다. 옵션 기본값·플래그 이름은 설치 버전에 따라 달라질 수 있습니다.