Vault SecretRefs

기준일: 2026-07-26
공식 기준: Vault SecretRefs

Vault SecretRefs 문서는 OpenClaw 공식 문서(plugins/vault)를 한국어로 정리한 가이드입니다. Use the bundled Vault plugin to resolve SecretRefs from HashiCorp Vault 명령·설정 키·코드 예시는 공식 문서를 그대로 보존하며, 해석과 절차 안내는 한국어로 제공합니다. 최종 동작은 설치된 CLI 버전과 공식 원문을 확인하세요.

핵심 요약

Use the bundled Vault plugin to resolve SecretRefs from HashiCorp Vault

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

문서 구성

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

• Vault SecretRefs
• 시작하기 전에
• Store a provider key in Vault
• Make Vault visible to the Gateway
• Generate and apply a SecretRef plan
• Configure more provider keys
• SecretRef id format
• What OpenClaw stores
• Containers and managed deployments
• 관련 문서

상세 내용

Vault SecretRefs

The bundled Vault plugin lets OpenClaw resolve exec SecretRefs from HashiCorp Vault at Gateway startup and reload time. OpenClaw stores Vault references in config, keeps resolved values in the in-memory secrets snapshot, and does not write the resolved API keys back to openclaw.json.

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

시작하기 전에

VAULT_TOKEN, OPENCLAW_VAULT_AUTH_METHOD=token_file with VAULT_TOKEN_FILE, or a configured JWT/Kubernetes login

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

주요 항목:

• OpenClaw with the bundled vault plugin available
• a reachable Vault server
• Vault auth that can produce a client token with read access to the secret
• the environment that starts the Gateway must include VAULT_ADDR and either

openclaw plugins enable vault

Store a provider key in Vault

OpenClaw defaults to KV v2 mounted at secret, matching Vault dev-server examples. For production Vault, set OPENCLAW_VAULT_KV_MOUNT to your actual KV mount path before creating SecretRef ids. With the OpenClaw defaults, this SecretRef id:

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

providers/openrouter/apiKey

secret/data/providers/openrouter -> apiKey

vault kv put secret/providers/openrouter apiKey="$OPENROUTER_API_KEY"

path "secret/data/providers/*" {
  capabilities = ["read"]
}

Make Vault visible to the Gateway

For an uncontainerized local Gateway, export Vault settings in the same shell that starts OpenClaw. The default auth method reads a Vault client token from VAULT_TOKEN:

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

Generate and apply a SecretRef plan

Create a plan that maps OpenRouter's model provider API key to Vault:

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

openclaw vault setup \
  --plan-out ./vault-secrets-plan.json \
  --openrouter-id providers/openrouter/apiKey

openclaw secrets apply --from ./vault-secrets-plan.json --dry-run --allow-exec
openclaw secrets apply --from ./vault-secrets-plan.json --allow-exec
openclaw secrets audit --check --allow-exec
openclaw secrets reload

Configure more provider keys

Bundled providers without shortcuts, or already-configured OpenAI-compatible and custom model providers, use --provider-key:

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

openclaw vault setup --openai-id providers/openai/apiKey
openclaw vault setup --anthropic-id providers/anthropic/apiKey
openclaw vault setup --openrouter-id providers/openrouter/apiKey

openclaw vault setup \
  --plan-out ./vault-secrets-plan.json \
  --openai-id providers/openai/apiKey \
  --anthropic-id providers/anthropic/apiKey \
  --openrouter-id providers/openrouter/apiKey

openclaw vault setup \
  --plan-out ./vault-secrets-plan.json \
  --provider-key local-openai=providers/local-openai/apiKey \
  --provider-key groq=providers/groq/apiKey

openclaw vault setup \
  --target channels.telegram.botToken=channels/telegram/botToken \
  --target models.providers.openai.headers.x-api-key=providers/openai/proxyKey \
  --target auth-profiles:main:profiles.openai.key=providers/openai/apiKey

SecretRef id format

The returned Vault field must be a string.

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

SecretRef id	Default KV v2 Vault read	Returned field
providers/openrouter/apiKey	secret/data/providers/openrouter	apiKey
providers/openai/apiKey	secret/data/providers/openai	apiKey
teams/agent-prod/openrouter	secret/data/teams/agent-prod	openrouter

<vault-secret-path>/<field>

secret/providers/openrouter -> apiKey

What OpenClaw stores

Applying a Vault setup plan stores a plugin-managed provider:

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

{
  "source": "exec",
  "pluginIntegration": {
    "pluginId": "vault",
    "integrationId": "vault"
  }
}

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

Containers and managed deployments

Containerized Gateways still use the same plugin and SecretRef config. The container must receive:

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

주요 항목:

• VAULT_ADDR
• one auth source:
• VAULT_TOKEN
• OPENCLAW_VAULT_AUTH_METHOD=token_file plus VAULT_TOKEN_FILE
• OPENCLAW_VAULT_AUTH_METHOD=jwt plus OPENCLAW_VAULT_AUTH_MOUNT,
• OPENCLAW_VAULT_AUTH_METHOD=kubernetes plus OPENCLAW_VAULT_AUTH_ROLE; optionally
• optional VAULT_NAMESPACE, OPENCLAW_VAULT_KV_MOUNT, and

관련 문서

주요 항목:

• Secrets management
• openclaw secrets
• Plugin inventory

실습 체크리스트

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

자주 쓰는 명령·설정 예시

openclaw plugins enable vault

providers/openrouter/apiKey

secret/data/providers/openrouter -> apiKey

vault kv put secret/providers/openrouter apiKey="$OPENROUTER_API_KEY"

path "secret/data/providers/*" {
  capabilities = ["read"]
}

관련 링크

• 공식 원문: plugins/vault
• OpenClaw 문서 홈

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