구성 예시

아래 예시는 현재 구성 스키마에 맞춰져 있습니다. 전체 참조와 필드별 참고 사항은 구성을 참조하십시오.

빠른 시작

최소 구성

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

~/.openclaw/openclaw.json에 저장하면 해당 번호로 봇에 DM을 보낼 수 있습니다.

권장 시작 구성

{
  agents: {
    defaults: {
      workspace: "~/.openclaw/workspace",
      model: { primary: "anthropic/claude-sonnet-4-6" },
    },
    list: [
      {
        id: "main",
        identity: {
          name: "Clawd",
          theme: "helpful assistant",
          emoji: "🦞",
        },
      },
    ],
  },
  channels: {
    whatsapp: {
      allowFrom: ["+15555550123"],
      groups: { "*": { requireMention: true } },
    },
  },
  messages: {
    visibleReplies: "automatic",
    groupChat: {
      visibleReplies: "message_tool", // 선택 사용; 표시되는 출력에는 message(action=send)가 필요합니다
      unmentionedInbound: "room_event",
    },
  },
}

확장 예시(주요 옵션)

JSON5에서는 주석과 후행 쉼표를 사용할 수 있습니다. 일반 JSON도 사용할 수 있습니다.

{
  // 환경 + 셸
  env: {
    OPENROUTER_API_KEY: "sk-or-...",
    vars: {
      GROQ_API_KEY: "gsk-...",
    },
    shellEnv: {
      enabled: true,
      timeoutMs: 15000,
    },
  },

  // 인증 프로필 메타데이터(보안 비밀은 auth-profiles.json에 있음)
  auth: {
    profiles: {
      "anthropic:default": { provider: "anthropic", mode: "api_key" },
      "anthropic:work": { provider: "anthropic", mode: "api_key" },
      "openai:default": { provider: "openai", mode: "api_key" },
      "openai:personal": { provider: "openai", mode: "oauth" },
    },
    order: {
      anthropic: ["anthropic:default", "anthropic:work"],
      openai: ["openai:personal", "openai:default"],
    },
  },

  // ID는 에이전트별로 설정합니다. 아래 agents.list[].identity에서 설정하십시오.

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

  // 메시지 서식
  messages: {
    messagePrefix: "[openclaw]",
    visibleReplies: "automatic",
    responsePrefix: ">",
    ackReaction: "👀",
    ackReactionScope: "group-mentions",
    groupChat: {
      historyLimit: 50,
      visibleReplies: "message_tool", // 도구를 안정적으로 사용하는 모델이 있는 공유 방에서 사용하도록 선택합니다
      unmentionedInbound: "room_event",
    },
    queue: {
      mode: "followup",
      debounceMs: 500,
      cap: 20,
      drop: "summarize",
      byChannel: {
        whatsapp: "followup",
        telegram: "followup",
        discord: "collect",
        slack: "collect",
        signal: "followup",
        imessage: "followup",
        webchat: "followup",
      },
    },
  },

  // 도구
  tools: {
    media: {
      audio: {
        enabled: true,
        maxBytes: 20971520,
        models: [
          { provider: "openai", model: "gpt-4o-transcribe" },
          // 선택적 CLI 대체 수단(Whisper 바이너리):
          // { type: "cli", command: "whisper", args: ["--model", "base", "{{MediaPath}}"] }
        ],
        timeoutSeconds: 120,
      },
      video: {
        enabled: true,
        maxBytes: 52428800,
        models: [{ provider: "google", model: "gemini-3-flash-preview" }],
      },
    },
  },

  // 세션 동작
  session: {
    scope: "per-sender",
    dmScope: "per-channel-peer", // 여러 사용자가 이용하는 받은 편지함에 권장합니다
    reset: {
      mode: "daily",
      atHour: 4,
      idleMinutes: 60,
    },
    resetByChannel: {
      discord: { mode: "idle", idleMinutes: 10080 },
    },
    resetTriggers: ["/new", "/reset"],
    store: "~/.openclaw/agents/main/sessions/sessions.json",
    maintenance: {
      mode: "warn",
      pruneAfter: "30d",
      maxEntries: 500,
      resetArchiveRetention: "30d", // 기간 또는 false
      maxDiskBytes: "500mb", // 선택 사항
      highWaterBytes: "400mb", // 선택 사항(기본값은 maxDiskBytes의 80%)
    },
    typingIntervalSeconds: 5,
    sendPolicy: {
      default: "allow",
      rules: [{ action: "deny", match: { channel: "discord", chatType: "group" } }],
    },
  },

  // 채널
  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: ["123456789012345678"] },
      guilds: {
        "123456789012345678": {
          slug: "friends-of-openclaw",
          requireMention: false,
          channels: {
            general: { enabled: true },
            help: { enabled: true, requireMention: true },
          },
        },
      },
    },

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

  // 에이전트 런타임
  agents: {
    defaults: {
      workspace: "~/.openclaw/workspace",
      userTimezone: "America/Chicago",
      model: {
        primary: "anthropic/claude-sonnet-4-6",
        fallbacks: ["anthropic/claude-opus-4-6", "openai/gpt-5.4"],
      },
      imageModel: {
        primary: "openrouter/anthropic/claude-sonnet-4-6",
      },
      models: {
        "anthropic/claude-opus-4-6": { alias: "opus" },
        "anthropic/claude-sonnet-4-6": { alias: "sonnet" },
        "openai/gpt-5.4": { alias: "gpt" },
      },
      skills: ["github", "weather"], // list[].skills를 생략한 에이전트가 상속합니다
      thinkingDefault: "low",
      verboseDefault: "off",
      toolProgressDetail: "explain",
      reasoningDefault: "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-6",
        target: "last",
        directPolicy: "allow", // allow(기본값) | block
        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",
        scope: "session", // 기존 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,
        },
      },
    },
    list: [
      {
        id: "main",
        default: true,
        identity: {
          name: "Samantha",
          theme: "도움이 되는 나무늘보",
          emoji: "🦥",
        },
        // defaults.skills -> github, weather를 상속합니다
        groupChat: {
          mentionPatterns: ["@openclaw", "openclaw"],
        },
        thinkingDefault: "high", // 에이전트별 사고 설정 재정의
        reasoningDefault: "on", // 에이전트별 추론 표시 여부
        fastModeDefault: false, // 에이전트별 빠른 모드
      },
      {
        id: "quick",
        skills: [], // 이 에이전트에는 Skills가 없습니다
        fastModeDefault: true, // 이 에이전트는 항상 빠르게 실행됩니다
        thinkingDefault: "off",
      },
    ],
  },

  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: ["123456789012345678"],
        slack: ["U123"],
        signal: ["+15555550123"],
        imessage: ["user@example.com"],
        webchat: ["session:demo"],
      },
    },
  },

  // 사용자 지정 모델 제공업체
  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 작업
  cron: {
    enabled: true,
    store: "~/.openclaw/cron/jobs.json",
    maxConcurrentRuns: 8, // 기본값; Cron 디스패치 + 격리된 Cron 에이전트 턴 실행
    sessionRetention: "24h",
  },

  // Webhook
  hooks: {
    enabled: true,
    path: "/hooks",
    token: "shared-secret",
    presets: ["gmail"],
    transformsDir: "~/.openclaw/hooks/transforms",
    mappings: [
      {
        id: "gmail-hook",
        match: { path: "gmail" },
        action: "agent",
        wakeMode: "now",
        name: "Gmail",
        sessionKey: "hook:gmail:{{messages[0].id}}",
        messageTemplate: "보낸 사람: {{messages[0].from}}\n제목: {{messages[0].subject}}",
        textTemplate: "{{messages[0].snippet}}",
        deliver: true,
        channel: "last",
        to: "+15555550123",
        thinking: "low",
        timeoutSeconds: 300,
        transform: {
          module: "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 + 네트워킹
  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-host.ts.net:18789", token: "remote-token" },
    reload: { mode: "hybrid", debounceMs: 300 },
  },

  skills: {
    allowBundled: ["gemini", "peekaboo"],
    load: {
      extraDirs: ["~/Projects/agent-scripts/skills"],
      allowSymlinkTargets: ["~/Projects/agent-scripts/skills"],
    },
    install: {
      preferBrew: true,
      nodeManager: "npm", // npm | pnpm | yarn | bun
      allowUploadedArchives: false,
    },
    entries: {
      "image-lab": {
        enabled: true,
        apiKey: "GEMINI_KEY_HERE",
        env: { GEMINI_API_KEY: "GEMINI_KEY_HERE" },
      },
      peekaboo: { enabled: true },
    },
  },
}

심볼릭 링크된 형제 Skills 저장소

기본 제공 Skills 루트에 형제 저장소를 가리키는 심볼릭 링크가 포함된 경우 사용하십시오. 예: ~/.agents/skills/manager -> ~/Projects/manager/skills.

{
  skills: {
    load: {
      extraDirs: ["~/Projects/manager/skills"],
      allowSymlinkTargets: ["~/Projects/manager/skills"],
    },
  },
}

extraDirs는 형제 저장소를 명시적인 Skills 루트로 스캔합니다.
allowSymlinkTargets를 사용하면 임의의 심볼릭 링크 이탈을 허용하지 않으면서 심볼릭 링크된 Skills 폴더가 신뢰할 수 있는 실제 대상 루트로 확인될 수 있습니다.
Skill Workshop이 동일하게 신뢰할 수 있는 심볼릭 링크 대상을 통해 쓰기를 적용하도록 하려면 skills.workshop.allowSymlinkTargetWrites: true을 설정하십시오.

일반적인 패턴

하나의 재정의가 있는 공유 Skills 기준선

{
  agents: {
    defaults: {
      workspace: "~/.openclaw/workspace",
      skills: ["github", "weather"],
    },
    list: [
      { id: "main", default: true },
      { id: "docs", workspace: "~/.openclaw/workspace-docs", skills: ["docs-search"] },
    ],
  },
}

agents.defaults.skills은 공유 기준선입니다.
agents.list[].skills은 한 에이전트에 대해 해당 기준선을 대체합니다.
에이전트에 Skills가 표시되지 않아야 하는 경우 skills: []을 사용하십시오.

다중 플랫폼 설정

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

신뢰할 수 있는 Node 네트워크 자동 승인

네트워크 경로를 제어하지 않는 한 기기 페어링은 수동으로 유지하십시오. 전용 실험실 또는 tailnet 서브넷의 경우 정확한 CIDR 또는 IP를 사용하여 최초 Node 기기 자동 승인을 사용하도록 선택할 수 있습니다.

{
  gateway: {
    nodes: {
      pairing: {
        autoApproveCidrs: ["192.168.1.0/24", "fd00:1234:5678::/64"],
      },
    },
  },
}

설정하지 않으면 이 기능은 계속 비활성화됩니다. 요청된 범위가 없는 새로운 role: node 페어링에만 적용됩니다. 운영자/브라우저 클라이언트와 역할, 범위, 메타데이터 또는 공개 키 업그레이드는 여전히 수동 승인이 필요합니다.

안전한 DM 모드(공유 받은 편지함/다중 사용자 DM)

두 명 이상이 봇에 DM을 보낼 수 있는 경우(allowFrom에 여러 항목이 있거나, 여러 사람에 대한 페어링 승인이 있거나, dmPolicy: "open"인 경우) 안전한 DM 모드를 활성화하여 서로 다른 발신자의 DM이 기본적으로 하나의 컨텍스트를 공유하지 않도록 하십시오.

{
  // 다중 사용자 또는 민감한 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: ["123456789012345678", "987654321098765432"] },
    },
  },
}

Discord/Google Chat/IRC/Mattermost/Microsoft Teams/Slack의 발신자 권한 부여는 기본적으로 ID를 우선합니다. 해당 위험을 명시적으로 수용하는 경우에만 각 채널의 dangerouslyAllowNameMatching: true을 사용하여 변경 가능한 이름/이메일/닉네임 직접 일치를 활성화하십시오.

Anthropic API 키 + MiniMax 대체 모델

{
  auth: {
    profiles: {
      "anthropic:api": {
        provider: "anthropic",
        mode: "api_key",
      },
    },
    order: {
      anthropic: ["anthropic:api"],
    },
  },
  models: {
    providers: {
      minimax: {
        baseUrl: "https://api.minimax.io/anthropic",
        api: "anthropic-messages",
        apiKey: "${MINIMAX_API_KEY}",
      },
    },
  },
  agents: {
    defaults: {
      workspace: "~/.openclaw/workspace",
      model: {
        primary: "anthropic/claude-opus-4-6",
        fallbacks: ["minimax/MiniMax-M2.7"],
      },
    },
  },
}

업무용 봇(접근 제한)

{
  agents: {
    defaults: {
      workspace: "~/work-openclaw",
      elevatedDefault: "off",
    },
    list: [
      {
        id: "main",
        identity: {
          name: "WorkBot",
          theme: "professional assistant",
        },
      },
    ],
  },
  channels: {
    slack: {
      enabled: true,
      botToken: "xoxb-...",
      channels: {
        "#engineering": { enabled: true, requireMention: true },
        "#general": { enabled: true, requireMention: true },
      },
    },
  },
}

로컬 모델만 사용

{
  agents: {
    defaults: {
      workspace: "~/.openclaw/workspace",
      model: { primary: "lmstudio/my-local-model" },
    },
  },
  models: {
    mode: "merge",
    providers: {
      lmstudio: {
        baseUrl: "http://127.0.0.1:1234/v1",
        apiKey: "lmstudio",
        api: "openai-responses",
        models: [
          {
            id: "my-local-model",
            name: "Local Model",
            reasoning: false,
            input: ["text"],
            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
            contextWindow: 196608,
            maxTokens: 8192,
          },
        ],
      },
    },
  },
}

팁

dmPolicy: "open"을 설정하는 경우 일치하는 allowFrom 목록에 "*"이 포함되어야 합니다.
제공자 ID의 형식은 서로 다릅니다(전화번호, 사용자 ID, 채널 ID). 제공자 문서에서 형식을 확인하십시오.
나중에 추가할 수 있는 선택적 섹션: web, browser, ui, discovery, plugins, talk, signal, imessage.
더 자세한 설정 참고 사항은 제공자 및 문제 해결을 참조하십시오.

Gateway

Remote access

Security

Nodes and media

Web interfaces

빠른 시작

최소 구성

권장 시작 구성

확장 예시(주요 옵션)

심볼릭 링크된 형제 Skills 저장소

일반적인 패턴

하나의 재정의가 있는 공유 Skills 기준선

다중 플랫폼 설정

신뢰할 수 있는 Node 네트워크 자동 승인

안전한 DM 모드(공유 받은 편지함/다중 사용자 DM)

Anthropic API 키 + MiniMax 대체 모델

업무용 봇(접근 제한)

로컬 모델만 사용

팁

관련 문서

​빠른 시작

​최소 구성

​권장 시작 구성

​확장 예시(주요 옵션)

​심볼릭 링크된 형제 Skills 저장소

​일반적인 패턴

​하나의 재정의가 있는 공유 Skills 기준선

​다중 플랫폼 설정

​신뢰할 수 있는 Node 네트워크 자동 승인

​안전한 DM 모드(공유 받은 편지함/다중 사용자 DM)

​Anthropic API 키 + MiniMax 대체 모델

​업무용 봇(접근 제한)

​로컬 모델만 사용

​팁

​관련 문서

빠른 시작

최소 구성

권장 시작 구성

확장 예시(주요 옵션)

심볼릭 링크된 형제 Skills 저장소

일반적인 패턴

하나의 재정의가 있는 공유 Skills 기준선

다중 플랫폼 설정

신뢰할 수 있는 Node 네트워크 자동 승인

안전한 DM 모드(공유 받은 편지함/다중 사용자 DM)

Anthropic API 키 + MiniMax 대체 모델

업무용 봇(접근 제한)

로컬 모델만 사용

팁

관련 문서