Gateway 설정 예제 가이드

설정 파일 하나 때문에 몇 시간을 허비한 적 있으신가요? 문법이 맞는지, 필드 이름이 정확한지 고민하다 보면 개발 흐름이 끊기기 마련이죠. 복잡한 설명 대신 바로 참고할 수 있는 예제가 있다면 개발이 훨씬 수월해질 거예요.

필요한 것

이 가이드를 따라하기 전에 다음 사항을 확인해 주세요.

• Gateway 설치 완료
• Configuration 상세 참조 문서 확인

빠른 시작

현재 설정 스키마에 맞춘 예제를 통해 5분 안에 설정을 마칠 수 있어요.

1. 사용 중인 Gateway 버전이 최신 스키마를 지원하는지 확인하세요.
2. Configuration 페이지로 이동하여 각 필드에 대한 상세 노트를 확인하세요.
3. 프로젝트 요구 사항에 맞는 설정 값을 복사하여 적용하세요.

문제 해결

설정 과정에서 문제가 발생한다면 다음을 확인해 보세요.

• 설정 필드 오류: 모든 예제는 현재 config 스키마에 맞춰져 있습니다. 필드별 상세 설명과 제약 사항은 Configuration 문서의 ‘per-field notes’를 참고해 주세요.

---

더 궁금한 점이 있다면 AI Setup Assistant에게 물어보세요!

다음 단계

• Configuration Reference

```mdx
---
title: "Quick start"
description: "OpenClaw를 빠르게 설정하고 첫 번째 메시지를 보내는 방법을 알아봅니다."
---

새로운 도구를 설정할 때 복잡한 가이드 문서 때문에 시작도 하기 전에 지치는 경우가 많아요. 이것저것 설치하고 복잡한 환경 변수를 맞추다 보면 정작 만들고 싶은 기능은 손도 못 대기 일쑤죠.

OpenClaw는 이런 번거로움을 줄이고 바로 동작하는 환경을 만드는 데 집중해요. 아주 간단한 설정만으로 나만의 봇을 준비할 수 있습니다.

## 필요한 것

시작하기 전에 다음 사항들을 확인해 주세요.

- `~/.openclaw/workspace` 경로의 작업 공간
- 메시지를 수신할 WhatsApp 전화번호

## 빠른 시작

가장 빠르게 OpenClaw를 실행하는 방법입니다.

### 1. 최소 설정 (Absolute minimum)

가장 기본적인 설정입니다. 아래 내용을 복사해서 사용하세요.

```json
{
  agent: { workspace: "~/.openclaw/workspace" },
  channels: { whatsapp: { allowFrom: ["+15555550123"] } },
}

이 내용을 ~/.openclaw/openclaw.json 파일로 저장하세요. 이제 지정한 전화번호로 봇에게 DM을 보낼 수 있습니다.

2. 추천 시작 설정 (Recommended starter)

봇에게 이름과 개성을 부여하고 싶다면 이 설정을 추천해요. 특정 모델을 지정하거나 그룹 채팅에서의 동작도 제어할 수 있습니다.

{
  identity: {
    name: "Clawd",
    theme: "helpful assistant",
    emoji: "🦞",
  },
  agent: {
    workspace: "~/.openclaw/workspace",
    model: { primary: "anthropic/claude-sonnet-4-5" },
  },
  channels: {
    whatsapp: {
      allowFrom: ["+15555550123"],
      groups: { "*": { requireMention: true } },
    },
  },
}

문제 해결

설정 과정에서 문제가 생기면 다음 내용을 확인해 보세요.

• 파일 경로 확인: 설정 파일이 반드시 ~/.openclaw/openclaw.json 경로에 저장되어야 합니다.
• 전화번호 형식: allowFrom에 입력한 전화번호가 국가 코드를 포함한 올바른 형식인지 확인하세요.

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

다음 단계

• Identity 설정 자세히 보기
• WhatsApp 채널 구성하기

에이전트를 내 입맛에 딱 맞게 설정하고 싶은데, 막상 설정 파일을 열면 어디서부터 손을 대야 할지 막막할 때가 있죠. 기본 설정만으로는 부족하고, 그렇다고 모든 문서를 하나하나 뒤져가며 옵션을 찾기에는 시간이 너무 부족합니다.

여러 채널을 동시에 운영하거나 복잡한 라우팅 로직이 필요한 개발자라면, 모든 주요 옵션이 망라된 하나의 완성된 지도가 필요할 거예요. 여기 Openclaw의 강력한 기능들을 한 번에 파악할 수 있는 확장 설정 예시를 준비했습니다.

## 필요한 것

이 예시를 활용하기 위해 필요한 준비물입니다.

*   **API Keys**: OpenRouter, Anthropic, OpenAI, Google(Gemini) 등 사용하려는 프로바이더의 키
*   **Channel Tokens**: Telegram 봇 토큰, Discord 봇 토큰, Slack 앱/봇 토큰 등
*   **JSON5 환경**: 주석과 트레일링 콤마를 사용하기 위해 필요합니다.

## 빠른 시작

아래의 JSON5 설정은 Openclaw에서 사용할 수 있는 거의 모든 주요 옵션을 포함하고 있습니다. 이 코드를 복사해서 `config.json5` 파일에 붙여넣고, 여러분의 API 키와 토큰 정보만 수정하면 바로 시작할 수 있어요.

```json
{
  // Environment + shell
  env: {
    OPENROUTER_API_KEY: "sk-or-...",
    vars: {
      GROQ_API_KEY: "gsk-...",
    },
    shellEnv: {
      enabled: true,
      timeoutMs: 15000,
    },
  },

  // Auth profile metadata (secrets live in auth-profiles.json)
  auth: {
    profiles: {
      "anthropic:me@example.com": {
        provider: "anthropic",
        mode: "oauth",
        email: "me@example.com",
      },
      "anthropic:work": { provider: "anthropic", mode: "api_key" },
      "openai:default": { provider: "openai", mode: "api_key" },
      "openai-codex:default": { provider: "openai-codex", mode: "oauth" },
    },
    order: {
      anthropic: ["anthropic:me@example.com", "anthropic:work"],
      openai: ["openai:default"],
      "openai-codex": ["openai-codex:default"],
    },
  },

  // Identity
  identity: {
    name: "Samantha",
    theme: "helpful sloth",
    emoji: "🦥",
  },

  // Logging
  logging: {
    level: "info",
    file: "/tmp/openclaw/openclaw.log",
    consoleLevel: "info",
    consoleStyle: "pretty",
    redactSensitive: "tools",
  },

  // Message formatting
  messages: {
    messagePrefix: "[openclaw]",
    responsePrefix: ">",
    ackReaction: "👀",
    ackReactionScope: "group-mentions",
  },

  // Routing + queue
  routing: {
    groupChat: {
      mentionPatterns: ["@openclaw", "openclaw"],
      historyLimit: 50,
    },
    queue: {
      mode: "collect",
      debounceMs: 1000,
      cap: 20,
      drop: "summarize",
      byChannel: {
        whatsapp: "collect",
        telegram: "collect",
        discord: "collect",
        slack: "collect",
        signal: "collect",
        imessage: "collect",
        webchat: "collect",
      },
    },
  },

  // Tooling
  tools: {
    media: {
      audio: {
        enabled: true,
        maxBytes: 20971520,
        models: [
          { provider: "openai", model: "gpt-4o-mini-transcribe" },
          // Optional CLI fallback (Whisper binary):
          // { type: "cli", command: "whisper", args: ["--model", "base", "{{MediaPath}}"] }
        ],
        timeoutSeconds: 120,
      },
      video: {
        enabled: true,
        maxBytes: 52428800,
        models: [{ provider: "google", model: "gemini-3-flash-preview" }],
      },
    },
  },

  // Session behavior
  session: {
    scope: "per-sender",
    reset: {
      mode: "daily",
      atHour: 4,
      idleMinutes: 60,
    },
    resetByChannel: {
      discord: { mode: "idle", idleMinutes: 10080 },
    },
    resetTriggers: ["/new", "/reset"],
    store: "~/.openclaw/agents/default/sessions/sessions.json",
    maintenance: {
      mode: "warn",
      pruneAfter: "30d",
      maxEntries: 500,
      rotateBytes: "10mb",
    },
    typingIntervalSeconds: 5,
    sendPolicy: {
      default: "allow",
      rules: [{ action: "deny", match: { channel: "discord", chatType: "group" } }],
    },
  },

  // Channels
  channels: {
    whatsapp: {
      dmPolicy: "pairing",
      allowFrom: ["+15555550123"],
      groupPolicy: "allowlist",
      groupAllowFrom: ["+15555550123"],
      groups: { "*": { requireMention: true } },
    },

    telegram: {
      enabled: true,
      botToken: "YOUR_TELEGRAM_BOT_TOKEN",
      allowFrom: ["123456789"],
      groupPolicy: "allowlist",
      groupAllowFrom: ["123456789"],
      groups: { "*": { requireMention: true } },
    },

    discord: {
      enabled: true,
      token: "YOUR_DISCORD_BOT_TOKEN",
      dm: { enabled: true, allowFrom: ["steipete"] },
      guilds: {
        "123456789012345678": {
          slug: "friends-of-openclaw",
          requireMention: false,
          channels: {
            general: { allow: true },
            help: { allow: true, requireMention: true },
          },
        },
      },
    },

    slack: {
      enabled: true,
      botToken: "xoxb-REPLACE_ME",
      appToken: "xapp-REPLACE_ME",
      channels: {
        "#general": { allow: true, requireMention: true },
      },
      dm: { enabled: true, allowFrom: ["U123"] },
      slashCommand: {
        enabled: true,
        name: "openclaw",
        sessionPrefix: "slack:slash",
        ephemeral: true,
      },
    },
  },

  // Agent runtime
  agents: {
    defaults: {
      workspace: "~/.openclaw/workspace",
      userTimezone: "America/Chicago",
      model: {
        primary: "anthropic/claude-sonnet-4-5",
        fallbacks: ["anthropic/claude-opus-4-6", "openai/gpt-5.2"],
      },
      imageModel: {
        primary: "openrouter/anthropic/claude-sonnet-4-5",
      },
      models: {
        "anthropic/claude-opus-4-6": { alias: "opus" },
        "anthropic/claude-sonnet-4-5": { alias: "sonnet" },
        "openai/gpt-5.2": { alias: "gpt" },
      },
      thinkingDefault: "low",
      verboseDefault: "off",
      elevatedDefault: "on",
      blockStreamingDefault: "off",
      blockStreamingBreak: "text_end",
      blockStreamingChunk: {
        minChars: 800,
        maxChars: 1200,
        breakPreference: "paragraph",
      },
      blockStreamingCoalesce: {
        idleMs: 1000,
      },
      humanDelay: {
        mode: "natural",
      },
      timeoutSeconds: 600,
      mediaMaxMb: 5,
      typingIntervalSeconds: 5,
      maxConcurrent: 3,
      heartbeat: {
        every: "30m",
        model: "anthropic/claude-sonnet-4-5",
        target: "last",
        to: "+15555550123",
        prompt: "HEARTBEAT",
        ackMaxChars: 300,
      },
      memorySearch: {
        provider: "gemini",
        model: "gemini-embedding-001",
        remote: {
          apiKey: "${GEMINI_API_KEY}",
        },
        extraPaths: ["../team-docs", "/srv/shared-notes"],
      },
      sandbox: {
        mode: "non-main",
        perSession: true,
        workspaceRoot: "~/.openclaw/sandboxes",
        docker: {
          image: "openclaw-sandbox:bookworm-slim",
          workdir: "/workspace",
          readOnlyRoot: true,
          tmpfs: ["/tmp", "/var/tmp", "/run"],
          network: "none",
          user: "1000:1000",
        },
        browser: {
          enabled: false,
        },
      },
    },
  },

  tools: {
    allow: ["exec", "process", "read", "write", "edit", "apply_patch"],
    deny: ["browser", "canvas"],
    exec: {
      backgroundMs: 10000,
      timeoutSec: 1800,
      cleanupMs: 1800000,
    },
    elevated: {
      enabled: true,
      allowFrom: {
        whatsapp: ["+15555550123"],
        telegram: ["123456789"],
        discord: ["steipete"],
        slack: ["U123"],
        signal: ["+15555550123"],
        imessage: ["user@example.com"],
        webchat: ["session:demo"],
      },
    },
  },

  // Custom model providers
  models: {
    mode: "merge",
    providers: {
      "custom-proxy": {
        baseUrl: "http://localhost:4000/v1",
        apiKey: "LITELLM_KEY",
        api: "openai-responses",
        authHeader: true,
        headers: { "X-Proxy-Region": "us-west" },
        models: [
          {
            id: "llama-3.1-8b",
            name: "Llama 3.1 8B",
            api: "openai-responses",
            reasoning: false,
            input: ["text"],
            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
            contextWindow: 128000,
            maxTokens: 32000,
          },
        ],
      },
    },
  },

  // Cron jobs
  cron: {
    enabled: true,
    store: "~/.openclaw/cron/cron.json",
    maxConcurrentRuns: 2,
    sessionRetention: "24h",
  },

  // Webhooks
  hooks: {
    enabled: true,
    path: "/hooks",
    token: "shared-secret",
    presets: ["gmail"],
    transformsDir: "~/.openclaw/hooks",
    mappings: [
      {
        id: "gmail-hook",
        match: { path: "gmail" },
        action: "agent",
        wakeMode: "now",
        name: "Gmail",
        sessionKey: "hook:gmail:{{messages[0].id}}",
        messageTemplate: "From: {{messages[0].from}}\nSubject: {{messages[0].subject}}",
        textTemplate: "{{messages[0].snippet}}",
        deliver: true,
        channel: "last",
        to: "+15555550123",
        thinking: "low",
        timeoutSeconds: 300,
        transform: {
          module: "./transforms/gmail.js",
          export: "transformGmail",
        },
      },
    ],
    gmail: {
      account: "openclaw@gmail.com",
      label: "INBOX",
      topic: "projects/<project-id>/topics/gog-gmail-watch",
      subscription: "gog-gmail-watch-push",
      pushToken: "shared-push-token",
      hookUrl: "http://127.0.0.1:18789/hooks/gmail",
      includeBody: true,
      maxBytes: 20000,
      renewEveryMinutes: 720,
      serve: { bind: "127.0.0.1", port: 8788, path: "/" },
      tailscale: { mode: "funnel", path: "/gmail-pubsub" },
    },
  },

  // Gateway + networking
  gateway: {
    mode: "local",
    port: 18789,
    bind: "loopback",
    controlUi: { enabled: true, basePath: "/openclaw" },
    auth: {
      mode: "token",
      token: "gateway-token",
      allowTailscale: true,
    },
    tailscale: { mode: "serve", resetOnExit: false },
    remote: { url: "ws://gateway.tailnet:18789", token: "remote-token" },
    reload: { mode: "hybrid", debounceMs: 300 },
  },

  skills: {
    allowBundled: ["gemini", "peekaboo"],
    load: {
      extraDirs: ["~/Projects/agent-scripts/skills"],
    },
    install: {
      preferBrew: true,
      nodeManager: "npm",
    },
    entries: {
      "nano-banana-pro": {
        enabled: true,
        apiKey: "GEMINI_KEY_HERE",
        env: { GEMINI_API_KEY: "GEMINI_KEY_HERE" },
      },
      peekaboo: { enabled: true },
    },
  },
}

문제 해결

설정 과정에서 문제가 생겼나요? 다음 내용을 확인해 보세요.

• JSON 형식 오류: JSON5를 사용하면 주석과 마지막 항목 뒤의 콤마(trailing commas)를 사용할 수 있어 편리합니다. 하지만 일반 JSON 환경에서 이 설정을 그대로 사용하면 오류가 발생할 수 있으니 주의하세요.
• 환경 변수 및 쉘: shellEnv 설정 시 timeoutMs가 너무 짧으면 쉘 환경을 불러오기 전에 타임아웃이 발생할 수 있습니다. 예시에서는 15000ms(15초)로 설정되어 있습니다.

설정에 대해 더 궁금한 점이 있다면 AI Setup Assistant에게 물어보세요!

다음 단계

• Authentication Profiles 상세 설정 가이드
• Channel별 연결 방법 (Discord, Slack, Telegram)
• Custom Model Provider 등록하기

여러 플랫폼에 봇을 배포하거나 API 키가 만료될까 봐 걱정해 본 적 있으시죠? 매번 설정을 처음부터 새로 짜는 건 정말 번거로운 일이에요.

보안이 중요한 업무용 봇을 만들거나, 비용 절감을 위해 로컬 모델만 사용하고 싶은 상황도 있을 거예요. 이런 다양한 고민을 해결해 줄 OpenClaw의 주요 설정 패턴들을 정리해 보았습니다.

필요한 것

• ~/.openclaw/workspace 경로 (에이전트 작업 공간)
• 연결하려는 플랫폼의 토큰 (Telegram, Discord, Slack, WhatsApp 등)
• Anthropic 또는 MiniMax API 키 (필요 시)
• 로컬 모델 사용 시 LM Studio 등 로컬 서버 주소

빠른 시작

가장 먼저 여러 플랫폼을 한 번에 연결하는 방법부터 시작해 볼게요. 5분이면 충분합니다. 아래 설정을 사용하면 WhatsApp, Telegram, Discord를 동시에 연동할 수 있습니다.

{
  agent: { workspace: "~/.openclaw/workspace" },
  channels: {
    whatsapp: { allowFrom: ["+15555550123"] },
    telegram: {
      enabled: true,
      botToken: "YOUR_TOKEN",
      allowFrom: ["123456789"],
    },
    discord: {
      enabled: true,
      token: "YOUR_TOKEN",
      dm: { allowFrom: ["yourname"] },
    },
  },
}

보안 DM 모드 (공유 편지함 / 다중 사용자 DM)

한 명 이상의 사용자가 봇에게 DM을 보낼 수 있는 경우(예: allowFrom에 여러 항목이 있거나 dmPolicy: "open" 설정 시), secure DM mode를 활성화하는 것이 좋습니다. 이 설정을 통해 서로 다른 발신자가 보낸 DM이 하나의 컨텍스트를 공유하지 않도록 방지할 수 있습니다.

{
  // 다중 사용자 또는 민감한 정보를 다루는 DM 에이전트 권장 설정
  session: { dmScope: "per-channel-peer" },

  channels: {
    // 예: WhatsApp 다중 사용자 인박스
    whatsapp: {
      dmPolicy: "allowlist",
      allowFrom: ["+15555550123", "+15555550124"],
    },

    // 예: Discord 다중 사용자 인박스
    discord: {
      enabled: true,
      token: "YOUR_DISCORD_BOT_TOKEN",
      dm: { enabled: true, allowFrom: ["alice", "bob"] },
    },
  },
}

OAuth 및 API key failover 설정

Anthropic 구독 계정을 우선 사용하되, 문제가 생길 경우 API key로 자동 전환되도록 설정하는 패턴입니다.

{
  auth: {
    profiles: {
      "anthropic:subscription": {
        provider: "anthropic",
        mode: "oauth",
        email: "me@example.com",
      },
      "anthropic:api": {
        provider: "anthropic",
        mode: "api_key",
      },
    },
    order: {
      anthropic: ["anthropic:subscription", "anthropic:api"],
    },
  },
  agent: {
    workspace: "~/.openclaw/workspace",
    model: {
      primary: "anthropic/claude-sonnet-4-5",
      fallbacks: ["anthropic/claude-opus-4-6"],
    },
  },
}

Anthropic 구독 + API key 및 MiniMax fallback

Anthropic 모델을 메인으로 사용하고, 비상시 MiniMax 모델로 대체하도록 구성할 수 있습니다.

{
  auth: {
    profiles: {
      "anthropic:subscription": {
        provider: "anthropic",
        mode: "oauth",
        email: "user@example.com",
      },
      "anthropic:api": {
        provider: "anthropic",
        mode: "api_key",
      },
    },
    order: {
      anthropic: ["anthropic:subscription", "anthropic:api"],
    },
  },
  models: {
    providers: {
      minimax: {
        baseUrl: "https://api.minimax.io/anthropic",
        api: "anthropic-messages",
        apiKey: "${MINIMAX_API_KEY}",
      },
    },
  },
  agent: {
    workspace: "~/.openclaw/workspace",
    model: {
      primary: "anthropic/claude-opus-4-6",
      fallbacks: ["minimax/MiniMax-M2.1"],
    },
  },
}

업무용 봇 (접근 제한 설정)

특정 Slack 채널에서만 작동하고 관리자 권한을 제한한 설정입니다.

{
  identity: {
    name: "WorkBot",
    theme: "professional assistant",
  },
  agent: {
    workspace: "~/work-openclaw",
    elevated: { enabled: false },
  },
  channels: {
    slack: {
      enabled: true,
      botToken: "xoxb-...",
      channels: {
        "#engineering": { allow: true, requireMention: true },
        "#general": { allow: true, requireMention: true },
      },
    },
  },
}

로컬 모델 전용 설정

LM Studio 등을 사용하여 외부 API 연결 없이 로컬 모델만 사용하는 경우입니다.

{
  agent: {
    workspace: "~/.openclaw/workspace",
    model: { primary: "lmstudio/minimax-m2.1-gs32" },
  },
  models: {
    mode: "merge",
    providers: {
      lmstudio: {
        baseUrl: "http://127.0.0.1:1234/v1",
        apiKey: "lmstudio",
        api: "openai-responses",
        models: [
          {
            id: "minimax-m2.1-gs32",
            name: "MiniMax M2.1 GS32",
            reasoning: false,
            input: ["text"],
            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
            contextWindow: 196608,
            maxTokens: 8192,
          },
        ],
      },
    },
  },
}

문제 해결

다른 사용자의 대화 내용이 섞이나요?

여러 사용자가 봇과 대화할 때 컨텍스트가 섞인다면 session: { dmScope: "per-channel-peer" } 옵션을 확인해 보세요. 이 옵션이 없으면 여러 사용자의 DM이 하나의 대화 흐름으로 묶일 수 있습니다.

특정 채널에서 봇이 응답하지 않나요?

Slack 등의 채널 설정에서 requireMention: true가 설정되어 있는지 확인하세요. 이 경우 봇을 직접 멘션해야만 응답합니다.

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

다음 단계

• Provider 설정 가이드
• 채널별 상세 설정

새로운 도구를 도입할 때 가장 답답한 순간은 문서대로 설정했는데도 생각처럼 작동하지 않을 때죠. 특히 복잡한 Gateway 설정에서는 작은 옵션 하나나 잘못된 ID 형식 때문에 몇 시간씩 디버깅을 하며 시간을 허비하기 쉽습니다. 이런 시행착오를 줄이고 설정을 한 번에 끝낼 수 있도록 실무에서 유용한 팁들을 정리했습니다.

필요한 것

• Gateway 설정 파일
• 연결할 Providers 정보

빠른 시작

Gateway 설정을 빠르게 마무리하려면 다음 두 가지 핵심 사항을 먼저 확인하는 것이 좋습니다.

1. dmPolicy 설정 규칙: 만약 dmPolicy를 "open"으로 설정했다면, 대응하는 allowFrom 리스트에 반드시 "*"가 포함되어야 합니다. 이 설정이 누락되면 의도한 대로 동작하지 않을 수 있습니다.
2. Provider ID 형식 확인: Provider마다 사용하는 ID 형식이 제각각입니다. 전화번호를 쓰는 곳도 있고, 고유한 사용자 ID나 채널 ID를 요구하는 곳도 있습니다. 반드시 해당 Provider 문서를 참고해서 정확한 포맷을 사용하고 있는지 확인하세요.

나중에 필요에 따라 다음과 같은 섹션들을 추가로 구성할 수 있습니다:

• web, browser, ui, discovery
• canvasHost, talk, signal, imessage

문제 해결

설정 과정에서 문제가 발생했다면 가장 먼저 Provider ID 형식이 올바른지 다시 한번 살펴보세요. 대부분의 연동 오류는 잘못된 ID 형식에서 시작됩니다. 더 자세한 해결 방법이 필요하다면 Troubleshooting 가이드를 확인해 보시기 바랍니다.

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

다음 단계

• Providers 상세 설정 보기
• Troubleshooting 가이드 확인하기