OpenClaw SecretRef 설정: 보안 자격 증명 관리 가이드

여러 플랫폼의 API 키와 자격 증명을 관리하다 보면 어떤 항목을 안전하게 분리해야 할지 고민될 때가 많죠. 설정 파일 곳곳에 흩어진 비밀 정보를 체계적으로 관리하고 싶은 개발자분들을 위해, OpenClaw의 SecretRef가 지원하는 자격 증명 범위를 정리해 드릴게요.

이 가이드는 SecretRef의 표준 자격 증명 범위를 정의합니다.

범위 안내:

포함 대상: OpenClaw가 직접 생성하거나 갱신하지 않는, 사용자가 직접 제공하는 자격 증명입니다.
제외 대상: 런타임에서 생성되거나 순환(rotate)되는 자격 증명, OAuth 리프레시 토큰, 세션 관련 아티팩트입니다.

지원되는 자격 증명 (Supported credentials)

`openclaw.json` 대상 (`secrets configure` + `secrets apply` + `secrets audit`)

models.providers.*.apiKey
models.providers.*.headers.*
skills.entries.*.apiKey
agents.defaults.memorySearch.remote.apiKey
agents.list[].memorySearch.remote.apiKey
talk.apiKey
talk.providers.*.apiKey
messages.tts.providers.*.apiKey
tools.web.fetch.firecrawl.apiKey
plugins.entries.brave.config.webSearch.apiKey
plugins.entries.google.config.webSearch.apiKey
plugins.entries.xai.config.webSearch.apiKey
plugins.entries.moonshot.config.webSearch.apiKey
plugins.entries.perplexity.config.webSearch.apiKey
plugins.entries.firecrawl.config.webSearch.apiKey
plugins.entries.tavily.config.webSearch.apiKey
tools.web.search.apiKey
tools.web.x_search.apiKey
gateway.auth.password
gateway.auth.token
gateway.remote.token
gateway.remote.password
cron.webhookToken
channels.telegram.botToken
channels.telegram.webhookSecret
channels.telegram.accounts.*.botToken
channels.telegram.accounts.*.webhookSecret
channels.slack.botToken
channels.slack.appToken
channels.slack.userToken
channels.slack.signingSecret
channels.slack.accounts.*.botToken
channels.slack.accounts.*.appToken
channels.slack.accounts.*.userToken
channels.slack.accounts.*.signingSecret
channels.discord.token
channels.discord.pluralkit.token
channels.discord.voice.tts.providers.*.apiKey
channels.discord.accounts.*.token
channels.discord.accounts.*.pluralkit.token
channels.discord.accounts.*.voice.tts.providers.*.apiKey
channels.irc.password
channels.irc.nickserv.password
channels.irc.accounts.*.password
channels.irc.accounts.*.nickserv.password
channels.bluebubbles.password
channels.bluebubbles.accounts.*.password
channels.feishu.appSecret
channels.feishu.encryptKey
channels.feishu.verificationToken
channels.feishu.accounts.*.appSecret
channels.feishu.accounts.*.encryptKey
channels.feishu.accounts.*.verificationToken
channels.msteams.appPassword
channels.mattermost.botToken
channels.mattermost.accounts.*.botToken
channels.matrix.accessToken
channels.matrix.password
channels.matrix.accounts.*.accessToken
channels.matrix.accounts.*.password
channels.nextcloud-talk.botSecret
channels.nextcloud-talk.apiPassword
channels.nextcloud-talk.accounts.*.botSecret
channels.nextcloud-talk.accounts.*.apiPassword
channels.zalo.botToken
channels.zalo.webhookSecret
channels.zalo.accounts.*.botToken
channels.zalo.accounts.*.webhookSecret
channels.googlechat.serviceAccount via sibling serviceAccountRef (compatibility exception)
channels.googlechat.accounts.*.serviceAccount via sibling serviceAccountRef (compatibility exception)

`auth-profiles.json` 대상 (`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 플랜 대상은 agentId가 필요해요.
플랜 항목은 profiles.*.key / profiles.*.token을 대상으로 하며, 형제 참조(keyRef / tokenRef)를 작성해요.
Auth-profile 참조는 런타임 확인(resolution) 및 감사(audit) 범위에 포함돼요.
OAuth 정책 가드: auth.profiles.<id>.mode = "oauth" 설정은 해당 프로필의 SecretRef 입력과 함께 사용할 수 없어요. 이 정책을 위반하면 시작/재로드 및 Auth-profile 확인 단계에서 즉시 실패해요.
SecretRef로 관리되는 모델 프로바이더의 경우, 생성된 agents/*/agent/models.json 항목은 apiKey/header 영역에 실제 비밀 값이 아닌 비밀이 아님을 나타내는 마커(non-secret markers)를 유지해요.
마커 유지 방식은 소스 권한을 따라가요. OpenClaw는 확인된 런타임 비밀 값이 아니라, 활성화된 소스 설정 스냅샷(확인 전 단계)에서 마커를 작성해요.
웹 검색(web search)의 경우:
- 명시적 프로바이더 모드(tools.web.search.provider 설정됨)에서는 선택된 프로바이더 키만 활성화돼요.
- 자동 모드(tools.web.search.provider 설정 안 됨)에서는 우선순위에 따라 확인되는 첫 번째 프로바이더 키만 활성화돼요.
- 자동 모드에서 선택되지 않은 프로바이더 참조는 선택되기 전까지 비활성 상태로 취급돼요.
- 기존의 tools.web.search.* 프로바이더 경로는 호환성 유지 기간 동안 여전히 확인되지만, 표준 SecretRef 영역은 plugins.entries.<plugin>.config.webSearch.*예요.

지원되지 않는 자격 증명 (Unsupported credentials)

범위 외 자격 증명은 다음과 같아요.

commands.ownerDisplaySecret
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

제외 이유:

이 자격 증명들은 시스템에서 생성되거나, 순환되거나, 세션을 포함하거나, OAuth 지속성을 가지는 클래스들이에요. 따라서 읽기 전용인 외부 SecretRef 확인 방식에는 적합하지 않아요.

도움이 필요하신가요? AI Setup Assistant에게 물어보세요.

다음 단계

OpenClaw Expert

아직 막혀 있나요?

이 문서에서 답을 못 찾았다면 OpenClaw Expert에게 바로 물어보세요.