OpenClaw 설정 가이드

새로운 도구를 설치하고 나서 설정 파일의 복잡한 구조 때문에 당황했던 적이 있으실 거예요. 사소한 오타 하나 때문에 서비스가 실행되지 않는데, 어디가 잘못되었는지 몰라 로그만 붙잡고 씨름하다 보면 금방 지치게 되죠.

OpenClaw는 이런 번거로움을 줄이기 위해 유연하면서도 엄격한 설정 시스템을 제공해요. 처음 시작하는 분들을 위해 가장 빠르게 설정을 마치는 방법을 정리해 드릴게요.

필요한 것

• OpenClaw Gateway
• ~/.openclaw/openclaw.json 파일 (필요 시 생성)

빠른 시작

OpenClaw는 설정 파일이 없어도 안전한 기본값으로 작동하지만, 채널을 연결하거나 모델을 튜닝하려면 설정이 필요해요. JSON5 형식을 지원하므로 주석을 자유롭게 달 수 있습니다.

1. 최소 설정 파일 생성: ~/.openclaw/openclaw.json 경로에 아래 내용을 저장하세요.

~/.openclaw/openclaw.json

{
  agents: { defaults: { workspace: "~/.openclaw/workspace" } },
  channels: { whatsapp: { allowFrom: ["+15555550123"] } },
}

2. 설정 수정하기: 아래 네 가지 방법 중 편한 방식을 선택하세요.

• Interactive wizard: openclaw onboard를 입력해 안내에 따라 설정을 마칩니다.
• CLI 명령어: openclaw config set agents.defaults.heartbeat.every "2h" 처럼 한 줄의 명령어로 값을 수정합니다.
• Control UI: http://127.0.0.1:18789에 접속해 Config 탭에서 폼을 입력합니다.
• 직접 수정: 파일을 직접 수정하면 Gateway가 변경 사항을 감지해 자동으로 적용(hot reload)합니다.

문제 해결

OpenClaw는 설정 검증이 매우 엄격해요. 스키마에 맞지 않는 키나 잘못된 타입이 포함되면 Gateway가 아예 시작되지 않습니다.

• Gateway가 부팅되지 않을 때: openclaw doctor, openclaw logs, openclaw health, openclaw status 같은 진단 명령어만 작동하는 상태인지 확인하세요.
• 문제 진단: openclaw doctor를 실행해 구체적으로 어떤 부분이 잘못되었는지 확인합니다.
• 자동 복구: openclaw doctor --fix 명령어를 사용하면 발견된 오류를 즉시 수정할 수 있습니다.

설정 과정에서 도움이 필요하다면 언제든 AI Setup Assistant에게 물어보세요.

다음 단계

• Configuration Reference 전체 보기
• 다양한 설정 예시 확인하기

```mdx
---
title: "Common tasks"
description: "OpenClaw를 사용하면서 자주 마주하는 주요 설정과 작업들을 빠르게 해결하는 방법을 알아봅니다."
---

봇을 여러 채널에 연결하고 관리하는 과정에서 설정 파일이 복잡해지거나, 특정 사용자만 접근하게 만들고 싶을 때가 있죠. 세션 초기화나 모델 교체 같은 반복적인 작업들을 매번 새로 고민하는 건 꽤나 피곤한 일이에요. 이런 일반적인 기술적 고민들을 해결할 수 있는 핵심 설정들을 정리했습니다.

## 필요한 것

- `openclaw.json` 또는 `openclaw.json5` 설정 파일
- 연결하려는 채널의 API 토큰 또는 계정 (WhatsApp, Telegram, Discord 등)
- 모델 API 키 (Anthropic, OpenAI 등)
- (선택 사항) Sandboxing 기능을 위한 Docker 환경

## 빠른 시작

가장 먼저 해야 할 일은 채널을 연결하고 모델을 지정하는 거예요. 5분 안에 끝낼 수 있는 최소 설정 경로입니다.

1. **채널 설정**: `channels.telegram` 등에 토큰을 넣고 `enabled: true`로 바꿉니다.
2. **모델 지정**: `agents.defaults.model.primary`에 사용할 모델을 적습니다.
3. **액세스 제어**: `dmPolicy`를 설정해 누가 메시지를 보낼 수 있는지 정합니다.

```json
{
  agents: {
    defaults: {
      model: { primary: "anthropic/claude-sonnet-4-5" }
    }
  },
  channels: {
    telegram: {
      enabled: true,
      botToken: "YOUR_TOKEN",
      dmPolicy: "pairing"
    }
  }
}

---

주요 작업 가이드

1. 채널 설정 (WhatsApp, Telegram, Discord 등)

각 채널은 channels.<provider> 아래에 고유한 설정 섹션을 가집니다. 구체적인 단계는 각 채널 페이지를 참고하세요.

• WhatsApp — channels.whatsapp
• Telegram — channels.telegram
• Discord — channels.discord
• Slack — channels.slack
• Signal — channels.signal
• iMessage — channels.imessage
• Google Chat — channels.googlechat
• Mattermost — channels.mattermost
• MS Teams — channels.msteams

모든 채널은 동일한 DM 정책 패턴을 공유해요.

{
  channels: {
    telegram: {
      enabled: true,
      botToken: "123:abc",
      dmPolicy: "pairing",   // pairing | allowlist | open | disabled
      allowFrom: ["tg:123"], // allowlist/open 설정 시에만 사용
    },
  },
}

2. 모델 선택 및 구성

기본 모델과 선택 사항인 fallback 모델을 설정할 수 있습니다.

{
  agents: {
    defaults: {
      model: {
        primary: "anthropic/claude-sonnet-4-5",
        fallbacks: ["openai/gpt-5.2"],
      },
      models: {
        "anthropic/claude-sonnet-4-5": { alias: "Sonnet" },
        "openai/gpt-5.2": { alias: "GPT" },
      },
    },
  },
}

• agents.defaults.models는 모델 카탈로그를 정의하며 /model 명령어로 바꿀 수 있는 allowlist 역할을 합니다.
• 모델 참조는 provider/model 형식을 사용해요 (예: anthropic/claude-opus-4-6).
• 채팅 중 모델 전환은 Models CLI를, 인증 순환이나 fallback 동작은 Model Failover를 확인하세요.
• 커스텀 또는 자체 호스팅 provider는 Custom providers 레퍼런스를 참고하면 됩니다.

3. 봇에게 메시지를 보낼 수 있는 사용자 제어

DM 접근 권한은 채널별로 dmPolicy를 통해 제어해요.

• "pairing" (기본값): 모르는 발신자에게는 승인을 위한 일회용 페어링 코드를 보냅니다.
• "allowlist": allowFrom에 정의된 발신자(또는 페어링된 allow store)만 허용합니다.
• "open": 모든 인바운드 DM을 허용합니다 (allowFrom: ["*"] 설정 필요).
• "disabled": 모든 DM을 무시합니다.

그룹 채팅의 경우 groupPolicy와 groupAllowFrom 또는 채널별 allowlist를 사용하세요. 자세한 내용은 full reference에서 확인할 수 있습니다.

4. 그룹 채팅 멘션 게이팅 설정

그룹 메시지는 기본적으로 멘션이 필요하도록 설정되어 있습니다. 에이전트별로 패턴을 구성해 보세요.

{
  agents: {
    list: [
      {
        id: "main",
        groupChat: {
          mentionPatterns: ["@openclaw", "openclaw"],
        },
      },
    ],
  },
  channels: {
    whatsapp: {
      groups: { "*": { requireMention: true } },
    },
  },
}

• Metadata mentions: 네이티브 @-멘션 (WhatsApp tap-to-mention, Telegram @bot 등)
• Text patterns: mentionPatterns에 정의된 정규식 패턴
• 채널별 오버라이드나 self-chat 모드는 full reference를 참고하세요.

5. 세션 및 초기화 구성

세션은 대화의 연속성과 격리를 관리합니다.

{
  session: {
    dmScope: "per-channel-peer",  // 다중 사용자 환경에서 권장
    reset: {
      mode: "daily",
      atHour: 4,
      idleMinutes: 120,
    },
  },
}

• dmScope: main (공유) | per-peer | per-channel-peer | per-account-channel-peer
• 스코핑, ID 링크, 전송 정책에 대해서는 Session Management를 확인하세요.
• 모든 필드 정보는 full reference에 있습니다.

6. Sandboxing 활성화

에이전트 세션을 격리된 Docker 컨테이너에서 실행할 수 있습니다.

{
  agents: {
    defaults: {
      sandbox: {
        mode: "non-main",  // off | non-main | all
        scope: "agent",    // session | agent | shared
      },
    },
  },
}

먼저 이미지를 빌드해야 합니다: scripts/sandbox-setup.sh

전체 가이드는 Sandboxing을, 모든 옵션은 full reference를 참고하세요.

7. Heartbeat 설정 (주기적 체크인)

{
  agents: {
    defaults: {
      heartbeat: {
        every: "30m",
        target: "last",
      },
    },
  },
}

• every: 기간 문자열 (30m, 2h). 비활성화하려면 0m으로 설정하세요.
• target: last | whatsapp | telegram | discord | none
• 자세한 내용은 Heartbeat 가이드를 확인하세요.

8. Cron 작업 구성

{
  cron: {
    enabled: true,
    maxConcurrentRuns: 2,
    sessionRetention: "24h",
  },
}

기능 개요와 CLI 예시는 Cron jobs에서 볼 수 있습니다.

9. Webhooks (hooks) 설정

Gateway에서 HTTP webhook 엔드포인트를 활성화합니다.

{
  hooks: {
    enabled: true,
    token: "shared-secret",
    path: "/hooks",
    mappings: [
      {
        match: { path: "gmail" },
        action: "agent",
        agentId: "main",
        deliver: true,
      },
    ],
  },
}

모든 매핑 옵션과 Gmail 연동은 full reference를 참고하세요.

10. 멀티 에이전트 라우팅 구성

별도의 작업 공간과 세션을 가진 여러 개의 독립된 에이전트를 실행합니다.

{
  agents: {
    list: [
      { id: "home", default: true, workspace: "~/.openclaw/workspace-home" },
      { id: "work", workspace: "~/.openclaw/workspace-work" },
    ],
  },
  bindings: [
    { agentId: "home", match: { channel: "whatsapp", accountId: "personal" } },
    { agentId: "work", match: { channel: "whatsapp", accountId: "biz" } },
  ],
}

바인딩 규칙과 에이전트별 액세스 프로필은 Multi-Agent 및 full reference를 확인하세요.

11. 설정 파일 분할 ($include)

$include를 사용해 거대한 설정 파일을 효율적으로 관리할 수 있습니다.

~/.openclaw/openclaw.json

{
  gateway: { port: 18789 },
  agents: { $include: "./agents.json5" },
  broadcast: {
    $include: ["./clients/a.json5", "./clients/b.json5"],
  },
}

• 단일 파일: 포함하는 객체를 대체합니다.
• 파일 배열: 순서대로 deep-merge 됩니다 (나중에 나오는 파일이 우선함).
• Sibling keys: include 이후에 병합되어 include 된 값을 덮어씁니다.
• Nested includes: 최대 10단계 깊이까지 지원합니다.
• Relative paths: 해당 파일을 포함하고 있는 파일을 기준으로 경로를 찾습니다.
• 에러 핸들링: 파일 누락, 파싱 에러, 순환 참조 발생 시 명확한 에러를 표시합니다.

---

문제 해결

• 모델이 바뀌지 않나요? Models CLI를 통해 채팅 내에서 올바르게 명령어를 입력했는지 확인해 보세요.
• Sandbox 실행 에러: 컨테이너를 실행하기 전 scripts/sandbox-setup.sh로 이미지를 먼저 빌드했는지 확인이 필요합니다.
• 설정 파일 로드 실패: $include 경로가 상대 경로인지, 그리고 순환 참조(A가 B를 포함하고 B가 다시 A를 포함)가 있지는 않은지 체크해 보세요.

설정 과정에서 도움이 더 필요하다면 AI Setup Assistant에게 물어보세요!

다음 단계

• Gateway Configuration Reference
• Session Management Concepts
• Model Failover Strategy

설정 파일 하나 바꿀 때마다 서버를 껐다 켜는 건 정말 귀찮은 일이에요. 특히 API 연동이나 모델 설정을 미세하게 조정하고 있을 때는 흐름이 끊기기 쉽죠. 매번 터미널로 돌아가서 프로세스를 재시작하는 대신, 저장 버튼만 누르면 바로 반영되는 환경이 필요해요.

## 필요한 것

- `~/.openclaw/openclaw.json` 설정 파일

## 빠른 시작

Gateway는 `~/.openclaw/openclaw.json` 파일을 실시간으로 감시해요. 대부분의 설정은 파일을 저장하는 즉시 적용되므로 서버를 수동으로 재시작할 필요가 없어요.

가장 추천하는 방식은 기본값인 `hybrid` 모드를 사용하는 거예요. 안전한 변경사항은 즉시 반영하고, 중요한 변경은 알아서 재시작을 처리해주거든요.

```json
{
  gateway: {
    reload: { mode: "hybrid", debounceMs: 300 },
  },
}

Reload modes 선택하기

상황에 따라 네 가지 모드 중 하나를 선택할 수 있어요:

• hybrid (기본값): 안전한 변경은 즉시 반영하고, 중요한 변경은 자동으로 재시작을 수행해요.
• hot: 안전한 변경만 즉시 반영해요. 재시작이 필요한 경우에는 로그로 경고를 보내주며, 실제 재시작은 직접 관리해야 해요.
• restart: 설정이 조금이라도 바뀌면 무조건 Gateway를 재시작해요.
• off: 파일 감시 기능을 꺼요. 변경사항은 다음번에 수동으로 재시작할 때만 반영돼요.

즉시 반영 vs 재시작 필요

어떤 필드를 수정하느냐에 따라 동작이 달라져요. hybrid 모드라면 재시작이 필요한 항목도 자동으로 처리되니 걱정 마세요.

카테고리	필드	재시작 필요?
Channels	channels.*, web (WhatsApp) — 모든 내장 및 확장 채널	No
Agent & models	agent, agents, models, routing	No
Automation	hooks, cron, agent.heartbeat	No
Sessions & messages	session, messages	No
Tools & media	tools, browser, skills, audio, talk	No
UI & misc	ui, logging, identity, bindings	No
Gateway server	gateway.* (port, bind, auth, tailscale, TLS, HTTP)	Yes
Infrastructure	discovery, canvasHost, plugins	Yes

참고: gateway.reload와 gateway.remote는 예외 항목이에요. 이 설정들을 변경해도 자동으로 재시작이 트리거되지는 않아요.

문제 해결

설정이 제대로 반영되지 않는다면 다음 내용을 확인해 보세요:

• 변경사항이 무시됨: mode가 off로 설정되어 있는지 확인하세요. 이 모드에서는 수동으로 재시작해야만 설정이 적용돼요.
• 로그에 경고 발생: hot 모드를 사용 중인데 재시작이 필요한 항목(예: gateway.port)을 수정했다면, Gateway는 경고 로그만 남기고 변경사항을 적용하지 않아요. 이럴 땐 직접 재시작을 해줘야 해요.

설정 과정에서 막히는 부분이 있다면 AI Setup Assistant에게 바로 물어보세요!

다음 단계

• Gateway 구성 상세 보기
• Agent 및 모델 설정법

설정 파일을 매번 수동으로 수정하고 저장하는 과정은 꽤나 번거로운 일이에요. 특히 운영 환경에서 설정을 동적으로 변경해야 하거나 자동화 스크립트를 작성해야 할 때, 설정 파일에 직접 접근하는 방식은 실수가 생기기 쉽고 관리도 어렵죠.

이런 문제를 해결하기 위해 OpenClaw는 RPC를 통해 프로그래밍 방식으로 설정을 업데이트하는 기능을 제공해요. API를 통해 안전하고 정확하게 Gateway 설정을 관리하는 방법을 알아볼게요.

필요한 것

• 실행 중인 OpenClaw Gateway
• OpenClaw CLI

빠른 시작

RPC를 사용하면 Gateway를 중단하지 않고도 설정을 변경할 수 있어요. 크게 전체 설정을 교체하는 방식과 필요한 부분만 수정하는 방식 두 가지가 있어요.

1. config.apply (전체 교체)

config.apply는 전체 설정을 검증하고 저장한 뒤, Gateway를 한 번에 재시작해요.

주의

config.apply는 설정 전체를 교체해요. 일부만 수정하고 싶다면 config.patch를 사용하거나, 단일 키만 바꿀 때는 openclaw config set을 사용하세요.

사용 가능한 Parameters:

• raw (string): 전체 설정에 대한 JSON5 페이로드
• baseHash (optional): config.get에서 얻은 설정 해시 (설정이 이미 존재할 때 필수)
• sessionKey (optional): 재시작 후 웨이크업 핑(wake-up ping)을 위한 세션 키
• note (optional): 재시작 센티널(sentinel)을 위한 기록용 노트
• restartDelayMs (optional): 재시작 전 대기 시간 (기본값 2000)

# 먼저 payload.hash를 확보하세요
openclaw gateway call config.get --params '{}'

# 확보한 해시를 넣어 전체 설정을 적용합니다
openclaw gateway call config.apply --params '{
  "raw": "{ agents: { defaults: { workspace: \"~/.openclaw/workspace\" } } }",
  "baseHash": "<hash>",
  "sessionKey": "agent:main:whatsapp:dm:+15555550123"
}'

2. config.patch (부분 업데이트)

기존 설정을 유지하면서 특정 부분만 병합하고 싶을 때는 config.patch를 사용해요. JSON merge patch 규칙을 따릅니다.

• 객체(Object)는 재귀적으로 병합돼요.
• null 값을 넣으면 해당 키를 삭제해요.
• 배열(Array)은 기존 내용을 덮어쓰며 교체돼요.

사용 가능한 Parameters:

• raw (string): 변경하려는 키만 포함된 JSON5
• baseHash (required): config.get에서 얻은 설정 해시
• sessionKey, note, restartDelayMs: config.apply와 동일해요.

openclaw gateway call config.patch --params '{
  "raw": "{ channels: { telegram: { groups: { \"*\": { requireMention: false } } } } }",
  "baseHash": "<hash>"
}'

문제 해결

• baseHash 오류: 설정을 업데이트할 때 baseHash가 일치하지 않으면 충돌을 방지하기 위해 요청이 거절될 수 있어요. 항상 config.get을 통해 최신 해시를 먼저 확인하세요.
• JSON5 형식: raw 파라미터에 전달하는 값은 올바른 JSON5 형식이어야 해요. 따옴표나 괄호가 누락되지 않았는지 확인해 보세요.

설정 과정에서 도움이 필요하다면 AI Setup Assistant에게 질문해 보세요.

다음 단계

• Gateway Configuration Overview
• CLI Reference

API 키나 비밀 설정을 관리하는 건 매번 번거로운 작업이죠. 로컬 개발 환경과 실제 배포 환경에서 매번 설정을 바꾸다 보면 실수하기 딱 좋습니다.

OpenClaw는 이런 불편함을 줄이기 위해 여러 곳에서 환경 변수를 불러오고, 설정 파일 안에서 동적으로 값을 치환할 수 있는 유연한 방법을 제공해요.

필요한 것

시작하기 전에 다음 항목이 준비되었는지 확인해 주세요.

• OpenClaw 설치 완료
• 사용할 서비스의 API 키 (예: OpenRouter, Groq 등)

빠른 시작

OpenClaw는 실행 시 부모 프로세스의 환경 변수를 기본으로 읽어오며, 추가로 다음 경로의 파일을 확인해요.

• 현재 작업 디렉토리의 .env 파일
• 전역 폴더인 ~/.openclaw/.env 파일

중요한 점은 파일에 정의된 값이 이미 존재하는 환경 변수를 덮어쓰지 않는다는 거예요. 만약 설정 파일 안에 직접 환경 변수를 정의하고 싶다면 아래와 같이 json5 형식으로 작성할 수 있어요.

{
  env: {
    OPENROUTER_API_KEY: "sk-or-...",
    vars: { GROQ_API_KEY: "gsk-..." },
  },
}

Shell 환경 변수 가져오기 (선택 사항)

필요한 키가 설정되어 있지 않을 때, OpenClaw가 로그인 쉘을 실행해서 누락된 키만 가져오도록 설정할 수도 있어요.

{
  env: {
    shellEnv: { enabled: true, timeoutMs: 15000 },
  },
}

환경 변수로 직접 설정하려면 OPENCLAW_LOAD_SHELL_ENV=1을 사용하면 돼요.

설정 값에서 환경 변수 치환하기

설정 파일 내의 문자열 값 어디에서든 ${VAR_NAME} 형식을 사용해 환경 변수를 참조할 수 있어요.

{
  gateway: { auth: { token: "${OPENCLAW_GATEWAY_TOKEN}" } },
  models: { providers: { custom: { apiKey: "${CUSTOM_API_KEY}" } } },
}

이 기능을 사용할 때는 몇 가지 규칙이 있어요.

• 대문자 이름만 인식해요: [A-Z_][A-Z0-9_]*
• $${VAR} 처럼 $를 두 번 쓰면 치환되지 않고 그대로 출력돼요.
• $include로 가져오는 파일 내부에서도 작동해요.
• "https://api.example.com/v1" 처럼 전체 주소를 만들 때 "${BASE}/v1"과 같이 부분 치환도 가능해요.

더 자세한 우선순위와 소스 정보는 Environment 문서를 참고해 주세요.

문제 해결

환경 변수 설정 중 문제가 생기면 다음 내용을 확인해 보세요.

• Missing/Empty Variable Error: 설정 파일에서 참조한 환경 변수가 없거나 비어 있으면 로드 시점에 에러가 발생해요. 변수가 시스템이나 .env 파일에 올바르게 정의되었는지 확인이 필요해요.

Full reference

필드별 상세 레퍼런스가 궁금하다면 **Configuration Reference**를 확인해 보세요.

설정 과정에서 도움이 필요하신가요? AI Setup Assistant에게 물어보세요!

---

What’s Next

• Configuration Examples
• Configuration Reference
• Doctor