OpenClaw 설정 가이드

이 가이드를 통해 OpenClaw에서 Relay의 API 키를 설정하고, OpenClaw 에이전트가 사용할 수 있도록 등록하는 방법을 단계별로 안내합니다.

한눈에 보기

  1. Relay API 키 발급
  2. Relay 기본 정보 설정
  3. 모델 등록 및 에이전트 허용
  4. 기본 모델 설정 (선택)
  5. 게이트웨이 재시작

아래 단계를 순서대로 진행하면 됩니다.

사전 준비 사항

  • OpenClaw 설치 완료
  • Relay 대시보드에서 발급받은 전용 API 키 (rlk-로 시작)
  • 터미널

API 키 준비

Relay 대시보드의 액세스 키 페이지에서 API 키를 생성할 수 있습니다. 생성된 키는 rlk-로 시작합니다.

  • 키가 노출되면 즉시 폐기하고 새 키를 발급하세요.
  • 키는 개인 정보이므로 공유하거나 저장소에 커밋하지 마세요.

1단계: Relay 기본 정보 설정

먼저 openclaw config patch 명령을 사용하여 Relay의 기본 정보를 OpenClaw 설정에 추가합니다. YOUR_RELAY_API_KEY부분은 반드시 본인의 Relay API 키로 교체해야 합니다.

Bash
# Relay Base URL 설정
openclaw config patch models.providers.Relay.baseUrl "https://www.relayservice.im/api/v1"

# Relay API 키 설정 (YOUR_RELAY_API_KEY를 본인의 키로 교체!)
openclaw config patch models.providers.Relay.apiKey "YOUR_RELAY_API_KEY"

# 인증 방식 설정 (API 키 방식)
openclaw config patch models.providers.Relay.auth "api-key"

# API 호환성 설정 (Relay는 OpenAI 호환 API를 제공하므로 대부분 이 값을 사용합니다.)
openclaw config patch models.providers.Relay.api "openai-completions"

2단계: Relay 모델 등록

다음은 Relay가 현재 제공하는 모델 목록입니다. 이 명령을 통해 OpenClaw에서 원하는 모델을 변경할 수 있습니다. 필요에 따라 1가지 모델만 등록하여도 무방합니다.

Bash
openclaw config patch models.providers.Relay.models '[
  {
    "id": "claude-haiku-4-5-20251001",
    "name": "claude-haiku-4-5-20251001",
    "api": "openai-completions",
    "reasoning": false,
    "input": ["text", "image"],
    "cost": {"input": 0, "output": 0, "cacheRead": 0, "cacheWrite": 0},
    "contextWindow": 200000,
    "maxTokens": 8192
  },
  {
    "id": "claude-sonnet-4-5-20250929",
    "name": "claude-sonnet-4-5-20250929",
    "api": "openai-completions",
    "reasoning": true,
    "input": ["text", "image"],
    "cost": {"input": 0, "output": 0, "cacheRead": 0, "cacheWrite": 0},
    "contextWindow": 200000,
    "maxTokens": 16384
  },
  {
    "id": "claude-opus-4-5-20251101",
    "name": "claude-opus-4-5-20251101",
    "api": "openai-completions",
    "reasoning": true,
    "input": ["text", "image"],
    "cost": {"input": 0, "output": 0, "cacheRead": 0, "cacheWrite": 0},
    "contextWindow": 200000,
    "maxTokens": 16384
  },
  {
    "id": "gemini-2.5-flash",
    "name": "gemini-2.5-flash",
    "api": "openai-completions",
    "reasoning": false,
    "input": ["text", "image"],
    "cost": {"input": 0, "output": 0, "cacheRead": 0, "cacheWrite": 0},
    "contextWindow": 200000,
    "maxTokens": 8192
  },
  {
    "id": "gemini-2.5-flash-lite",
    "name": "gemini-2.5-flash-lite",
    "api": "openai-completions",
    "reasoning": false,
    "input": ["text", "image"],
    "cost": {"input": 0, "output": 0, "cacheRead": 0, "cacheWrite": 0},
    "contextWindow": 200000,
    "maxTokens": 8192
  },
  {
    "id": "gemini-2.5-pro",
    "name": "gemini-2.5-pro",
    "api": "openai-completions",
    "reasoning": true,
    "input": ["text", "image"],
    "cost": {"input": 0, "output": 0, "cacheRead": 0, "cacheWrite": 0},
    "contextWindow": 200000,
    "maxTokens": 8192
  },
  {
    "id": "gpt-5.2",
    "name": "gpt-5.2",
    "api": "openai-completions",
    "reasoning": true,
    "input": ["text", "image"],
    "cost": {"input": 0, "output": 0, "cacheRead": 0, "cacheWrite": 0},
    "contextWindow": 128000,
    "maxTokens": 16384
  },
  {
    "id": "gpt-5.2-pro",
    "name": "gpt-5.2-pro",
    "api": "openai-completions",
    "reasoning": true,
    "input": ["text", "image"],
    "cost": {"input": 0, "output": 0, "cacheRead": 0, "cacheWrite": 0},
    "contextWindow": 128000,
    "maxTokens": 16384
  },
  {
    "id": "gpt-5-mini",
    "name": "gpt-5-mini",
    "api": "openai-completions",
    "reasoning": false,
    "input": ["text", "image"],
    "cost": {"input": 0, "output": 0, "cacheRead": 0, "cacheWrite": 0},
    "contextWindow": 128000,
    "maxTokens": 16384
  },
  {
    "id": "gpt-4o-mini",
    "name": "gpt-4o-mini",
    "api": "openai-completions",
    "reasoning": false,
    "input": ["text", "image"],
    "cost": {"input": 0, "output": 0, "cacheRead": 0, "cacheWrite": 0},
    "contextWindow": 128000,
    "maxTokens": 16384
  }
]'

3단계: 에이전트 모델 허용

agents.defaults.models 섹션에 Relay 모델들을 추가하여 OpenClaw 에이전트가 이 모델들을 사용할 수 있도록 허용해야 합니다. 이는 에이전트가 특정 모델을 사용할 수 있는지에 대한 "허용 목록"과 같은 역할을 합니다.

Bash
# Relay/claude-haiku-4-5-20251001 모델 허용
openclaw config patch agents.defaults.models.Relay/claude-haiku-4-5-20251001 '{}'

# Relay/claude-sonnet-4-5-20250929 모델 허용
openclaw config patch agents.defaults.models.Relay/claude-sonnet-4-5-20250929 '{}'

# Relay/claude-opus-4-5-20251101 모델 허용
openclaw config patch agents.defaults.models.Relay/claude-opus-4-5-20251101 '{}'

# Relay/gemini-2.5-flash 모델 허용
openclaw config patch agents.defaults.models.Relay/gemini-2.5-flash '{}'

# Relay/gemini-2.5-flash-lite 모델 허용
openclaw config patch agents.defaults.models.Relay/gemini-2.5-flash-lite '{}'

# Relay/gemini-2.5-pro 모델 허용
openclaw config patch agents.defaults.models.Relay/gemini-2.5-pro '{}'

# Relay/gpt-5.2 모델 허용
openclaw config patch agents.defaults.models.Relay/gpt-5.2 '{}'

# Relay/gpt-5.2-pro 모델 허용
openclaw config patch agents.defaults.models.Relay/gpt-5.2-pro '{}'

# Relay/gpt-5-mini 모델 허용
openclaw config patch agents.defaults.models.Relay/gpt-5-mini '{}'

# Relay/gpt-4o-mini 모델 허용
openclaw config patch agents.defaults.models.Relay/gpt-4o-mini '{}'

4단계: 기본(Primary) 모델 설정

이제 Relay를 통해 사용할 모델들이 모두 등록되었으므로, OpenClaw의 기본 모델을 Relay의 특정 모델로 설정할 수 있습니다. 예를 들어,Relay/claude-opus-4-5-20251101를 기본 모델로 설정하려면 다음 명령을 사용합니다.

Bash
openclaw config patch agents.defaults.model.primary "Relay/claude-opus-4-5-20251101"

5단계: 게이트웨이 재시작

설정이 완료된 후 게이트웨이 재시작이 필요합니다.

Bash
openclaw gateway restart

선택: 변경 사항 자동 재시작

변경 사항이 발생할 때마다 게이트웨이가 자동으로 재시작되도록 설정할 수 있습니다.

Bash
openclaw config patch commands.restart true

참고 사항

  • 모델 ID 형식: Relay/ 접두사가 붙은 모델 ID는 Relay 서비스를 통해 해당 모델을 사용하겠다는 의미입니다.
  • 모델 비용: cost 필드는 비용 추적을 위해 사용되지만, Relay 서비스의 실제 비용 정책과는 다를 수 있으므로 Relay 대시보드를 확인하는 것이 가장 정확합니다.
  • contextWindow 및 maxTokens: 이 값들은 모델의 실제 최대 컨텍스트 길이와 최대 생성 토큰 수에 맞춰 설정하는 것이 좋습니다. Relay 문서나 모델 제공사의 문서를 참고하세요.
  • api 필드: Relay는 일반적으로 OpenAI 호환 API를 제공하므로, 대부분의 모델에 대해 "openai-completions"로 설정합니다.