설정 레퍼런스

~/.openclaw/openclaw.json에서 사용 가능한 모든 필드입니다. 작업 중심 개요는 설정을 참조하세요.

설정 형식은 JSON5 (주석 + 후행 쉼표 허용)입니다. 모든 필드는 선택 사항이며 — 생략 시 OpenClaw는 안전한 기본값을 사용합니다.

채널

각 채널은 설정 섹션이 존재하면 자동으로 시작됩니다 (enabled: false가 아닌 한).

DM 및 그룹 접근

모든 채널은 DM 정책과 그룹 정책을 지원합니다:

DM 정책동작
pairing (기본값)알 수 없는 발신자가 일회성 페어링 코드를 받음; 소유자가 승인해야 함
allowlistallowFrom(또는 페어링 허용 저장소)에 있는 발신자만
open모든 수신 DM 허용 (allowFrom: ["*"] 필요)
disabled모든 수신 DM 무시
그룹 정책동작
allowlist (기본값)설정된 허용 목록과 일치하는 그룹만
open그룹 허용 목록 우회 (멘션 게이팅은 여전히 적용)
disabled모든 그룹/룸 메시지 차단

참고: channels.defaults.groupPolicy는 제공자의 groupPolicy가 설정되지 않은 경우 기본값을 설정합니다. 페어링 코드는 1시간 후 만료됩니다. 대기 중인 DM 페어링 요청은 채널당 3개로 제한됩니다. 제공자 블록이 완전히 없는 경우(channels.<provider> 부재), 런타임 그룹 정책은 시작 경고와 함께 allowlist (실패 폐쇄)로 폴백합니다.

채널 모델 오버라이드

channels.modelByChannel을 사용하여 특정 채널 ID를 모델에 고정합니다. 값은 provider/model 또는 설정된 모델 별칭을 수용합니다. 세션에 이미 모델 오버라이드가 없는 경우(예: /model로 설정된 경우) 채널 매핑이 적용됩니다.

{
  channels: {
    modelByChannel: {
      discord: {
        "123456789012345678": "anthropic/claude-opus-4-6",
      },
      slack: {
        C1234567890: "openai/gpt-4.1",
      },
      telegram: {
        "-1001234567890": "openai/gpt-4.1-mini",
        "-1001234567890:topic:99": "anthropic/claude-sonnet-4-6",
      },
    },
  },
}

채널 기본값 및 하트비트

channels.defaults를 사용하여 제공자 간 공유 그룹 정책 및 하트비트 동작을 설정합니다:

{
  channels: {
    defaults: {
      groupPolicy: "allowlist", // open | allowlist | disabled
      heartbeat: {
        showOk: false,
        showAlerts: true,
        useIndicator: true,
      },
    },
  },
}
  • channels.defaults.groupPolicy: 제공자 수준 groupPolicy가 설정되지 않은 경우 폴백 그룹 정책.
  • channels.defaults.heartbeat.showOk: 하트비트 출력에 정상 채널 상태 포함.
  • channels.defaults.heartbeat.showAlerts: 하트비트 출력에 저하/오류 상태 포함.
  • channels.defaults.heartbeat.useIndicator: 컴팩트 인디케이터 스타일 하트비트 출력 렌더링.

WhatsApp

WhatsApp은 게이트웨이의 웹 채널(Baileys Web)을 통해 실행됩니다. 연결된 세션이 존재하면 자동으로 시작됩니다.

{
  channels: {
    whatsapp: {
      dmPolicy: "pairing", // pairing | allowlist | open | disabled
      allowFrom: ["+15555550123", "+447700900123"],
      textChunkLimit: 4000,
      chunkMode: "length", // length | newline
      mediaMaxMb: 50,
      sendReadReceipts: true, // 파란 체크 (자기 채팅 모드에서는 false)
      groups: {
        "*": { requireMention: true },
      },
      groupPolicy: "allowlist",
      groupAllowFrom: ["+15551234567"],
    },
  },
  web: {
    enabled: true,
    heartbeatSeconds: 60,
    reconnect: {
      initialMs: 2000,
      maxMs: 120000,
      factor: 1.4,
      jitter: 0.2,
      maxAttempts: 0,
    },
  },
}
다중 계정 WhatsApp 
{
  channels: {
    whatsapp: {
      accounts: {
        default: {},
        personal: {},
        biz: {
          // authDir: "~/.openclaw/credentials/whatsapp/biz",
        },
      },
    },
  },
}
  • 아웃바운드 명령어는 default 계정이 있으면 기본값으로 사용합니다. 없으면 정렬된 첫 번째 설정 계정 ID.
  • 선택적 channels.whatsapp.defaultAccount는 설정된 계정 ID와 일치하는 경우 해당 폴백 기본 계정 선택을 오버라이드합니다.
  • 레거시 단일 계정 Baileys 인증 디렉토리는 openclaw doctor에 의해 whatsapp/default로 마이그레이션됩니다.
  • 계정별 오버라이드: channels.whatsapp.accounts.<id>.sendReadReceipts, channels.whatsapp.accounts.<id>.dmPolicy, channels.whatsapp.accounts.<id>.allowFrom.

Telegram

{
  channels: {
    telegram: {
      enabled: true,
      botToken: "your-bot-token",
      dmPolicy: "pairing",
      allowFrom: ["tg:123456789"],
      groups: {
        "*": { requireMention: true },
        "-1001234567890": {
          allowFrom: ["@admin"],
          systemPrompt: "Keep answers brief.",
          topics: {
            "99": {
              requireMention: false,
              skills: ["search"],
              systemPrompt: "Stay on topic.",
            },
          },
        },
      },
      customCommands: [
        { command: "backup", description: "Git backup" },
        { command: "generate", description: "Create an image" },
      ],
      historyLimit: 50,
      replyToMode: "first", // off | first | all
      linkPreview: true,
      streaming: "partial", // off | partial | block | progress (기본값: off)
      actions: { reactions: true, sendMessage: true },
      reactionNotifications: "own", // off | own | all
      mediaMaxMb: 100,
      retry: {
        attempts: 3,
        minDelayMs: 400,
        maxDelayMs: 30000,
        jitter: 0.1,
      },
      network: {
        autoSelectFamily: true,
        dnsResultOrder: "ipv4first",
      },
      proxy: "socks5://localhost:9050",
      webhookUrl: "https://example.com/telegram-webhook",
      webhookSecret: "secret",
      webhookPath: "/telegram-webhook",
    },
  },
}
  • 봇 토큰: channels.telegram.botToken 또는 channels.telegram.tokenFile(일반 파일만; 심볼릭 링크 거부), 기본 계정에 대해 TELEGRAM_BOT_TOKEN을 폴백으로 사용.
  • 선택적 channels.telegram.defaultAccount는 설정된 계정 ID와 일치하는 경우 기본 계정 선택을 오버라이드합니다.
  • 다중 계정 설정(2개 이상의 계정 ID)에서는 명시적 기본값(channels.telegram.defaultAccount 또는 channels.telegram.accounts.default)을 설정하여 폴백 라우팅을 방지합니다. openclaw doctor는 이것이 누락되거나 유효하지 않으면 경고합니다.
  • configWrites: false는 Telegram에서 시작된 설정 쓰기를 차단합니다 (슈퍼그룹 ID 마이그레이션, /config set|unset).
  • 최상위 bindings[] 항목에서 type: "acp"는 포럼 토픽에 대한 영구 ACP 바인딩을 설정합니다 (match.peer.id에 정규 chatId:topic:topicId 사용). 필드 시맨틱스는 ACP 에이전트에서 공유됩니다.
  • Telegram 스트림 미리보기는 sendMessage + editMessageText를 사용합니다 (직접 및 그룹 채팅에서 동작).
  • 재시도 정책: 재시도 정책 참조.

Discord

{
  channels: {
    discord: {
      enabled: true,
      token: "your-bot-token",
      mediaMaxMb: 8,
      allowBots: false,
      actions: {
        reactions: true,
        stickers: true,
        polls: true,
        permissions: true,
        messages: true,
        threads: true,
        pins: true,
        search: true,
        memberInfo: true,
        roleInfo: true,
        roles: false,
        channelInfo: true,
        voiceStatus: true,
        events: true,
        moderation: false,
      },
      replyToMode: "off", // off | first | all
      dmPolicy: "pairing",
      allowFrom: ["1234567890", "123456789012345678"],
      dm: { enabled: true, groupEnabled: false, groupChannels: ["openclaw-dm"] },
      guilds: {
        "123456789012345678": {
          slug: "friends-of-openclaw",
          requireMention: false,
          ignoreOtherMentions: true,
          reactionNotifications: "own",
          users: ["987654321098765432"],
          channels: {
            general: { allow: true },
            help: {
              allow: true,
              requireMention: true,
              users: ["987654321098765432"],
              skills: ["docs"],
              systemPrompt: "Short answers only.",
            },
          },
        },
      },
      historyLimit: 20,
      textChunkLimit: 2000,
      chunkMode: "length", // length | newline
      streaming: "off", // off | partial | block | progress (progress는 Discord에서 partial로 매핑)
      maxLinesPerMessage: 17,
      ui: {
        components: {
          accentColor: "#5865F2",
        },
      },
      threadBindings: {
        enabled: true,
        idleHours: 24,
        maxAgeHours: 0,
        spawnSubagentSessions: false, // sessions_spawn({ thread: true }) 옵트인
      },
      voice: {
        enabled: true,
        autoJoin: [
          {
            guildId: "123456789012345678",
            channelId: "234567890123456789",
          },
        ],
        daveEncryption: true,
        decryptionFailureTolerance: 24,
        tts: {
          provider: "openai",
          openai: { voice: "alloy" },
        },
      },
      retry: {
        attempts: 3,
        minDelayMs: 500,
        maxDelayMs: 30000,
        jitter: 0.1,
      },
    },
  },
}
  • 토큰: channels.discord.token, 기본 계정에 대해 DISCORD_BOT_TOKEN을 폴백으로 사용.
  • 명시적 Discord token을 제공하는 직접 아웃바운드 호출은 해당 토큰을 사용합니다. 계정 재시도/정책 설정은 활성 런타임 스냅샷에서 선택된 계정에서 가져옵니다.
  • 선택적 channels.discord.defaultAccount는 설정된 계정 ID와 일치하는 경우 기본 계정 선택을 오버라이드합니다.
  • 전달 대상에 user:<id> (DM) 또는 channel:<id> (길드 채널)를 사용합니다. 순수 숫자 ID는 거부됩니다.
  • 길드 슬러그는 소문자이며 공백은 -로 대체됩니다. 채널 키는 슬러그화된 이름(# 없음)을 사용합니다. 길드 ID를 선호하세요.
  • 봇이 작성한 메시지는 기본적으로 무시됩니다. allowBots: true로 활성화합니다. allowBots: "mentions"를 사용하면 봇을 멘션하는 봇 메시지만 수용합니다 (자신의 메시지는 여전히 필터링).
  • channels.discord.guilds.<id>.ignoreOtherMentions (및 채널 오버라이드)는 봇이 아닌 다른 사용자 또는 역할을 멘션하는 메시지를 삭제합니다 (@everyone/@here 제외).
  • maxLinesPerMessage (기본값 17)는 2000자 미만이더라도 긴 메시지를 분할합니다.
  • channels.discord.threadBindings는 Discord 스레드 바인딩 라우팅을 제어합니다:
    • enabled: 스레드 바인딩 세션 기능에 대한 Discord 오버라이드 (/focus, /unfocus, /agents, /session idle, /session max-age, 바인딩 전달/라우팅)
    • idleHours: 비활성 자동 해제를 위한 Discord 오버라이드 (시간, 0으로 비활성화)
    • maxAgeHours: 하드 최대 수명에 대한 Discord 오버라이드 (시간, 0으로 비활성화)
    • spawnSubagentSessions: sessions_spawn({ thread: true }) 자동 스레드 생성/바인딩을 위한 옵트인 스위치
  • 최상위 bindings[] 항목에서 type: "acp"는 채널 및 스레드에 대한 영구 ACP 바인딩을 설정합니다 (match.peer.id에 채널/스레드 ID 사용). 필드 시맨틱스는 ACP 에이전트에서 공유됩니다.
  • channels.discord.ui.components.accentColor는 Discord 컴포넌트 v2 컨테이너의 강조 색상을 설정합니다.
  • channels.discord.voice는 Discord 음성 채널 대화 및 선택적 자동 참가 + TTS 오버라이드를 활성화합니다.
  • channels.discord.voice.daveEncryption과 channels.discord.voice.decryptionFailureTolerance는 @discordjs/voice DAVE 옵션에 전달됩니다 (기본값 true 및 24).
  • OpenClaw는 반복적인 복호화 실패 후 음성 세션에서 나갔다 다시 참가하여 음성 수신 복구를 추가로 시도합니다.
  • channels.discord.streaming은 정규 스트림 모드 키입니다. 레거시 streamMode 및 불리언 streaming 값은 자동 마이그레이션됩니다.
  • channels.discord.autoPresence는 런타임 가용성을 봇 존재로 매핑합니다 (정상 => online, 저하 => idle, 소진 => dnd) 및 선택적 상태 텍스트 오버라이드를 허용합니다.
  • channels.discord.dangerouslyAllowNameMatching은 변경 가능한 이름/태그 매칭을 다시 활성화합니다 (비상 호환성 모드).

리액션 알림 모드: off (없음), own (봇의 메시지, 기본값), all (모든 메시지), allowlist (guilds.<id>.users에서 모든 메시지).

이 문서의 나머지 채널(Google Chat, Slack, Mattermost, Signal, BlueBubbles, iMessage, Microsoft Teams, IRC), 다중 계정, 그룹 채팅 멘션 게이팅, 명령어, 에이전트 기본값, 멀티 에이전트 라우팅, 세션, 메시지, Talk, 도구, 커스텀 제공자, 스킬, 플러그인, 브라우저, UI, 게이트웨이, Hooks, 캔버스 호스트, 탐색, 환경, 시크릿, 인증 저장소, 로깅, CLI, 마법사 섹션에 대한 전체 설정 레퍼런스는 원본 영어 문서의 해당 섹션과 동일한 구조를 유지합니다. 모든 설정 키, JSON5 코드 블록, URL, 변수명은 영어 원문 그대로 유지됩니다.

전체 영어 레퍼런스는 Configuration Reference (English)를 참조하세요.

관련: 설정 · 설정 예시 · Doctor

arrow_back
이전
Configuration
다음
Configuration Examples
arrow_forward