Hello Claw: OpenClaw 입문

#부록 B: 구성 파일에 대한 자세한 설명

OpenClaw의 구성 시스템은 유연하고 강력합니다. 본 부록에서는 공식 문서를 바탕으로 각 구성 항목을 자세히 분석합니다.

참고자료 : OpenClaw Configuration

구성 파일 위치

OpenClaw는 선택적 JSON5 구성 파일을 읽습니다.

~/.openclaw/openclaw.json          # 主配置文件
~/.openclaw/.env                   # 环境变量文件

구성 파일이 없으면 OpenClaw는 안전한 기본값을 사용합니다.

구성 파일 구조 개요

json5

{
  agents: { ... },           // Agent 配置
  channels: { ... },         // 渠道配置
  gateway: { ... },          // 网关配置
  session: { ... },          // 会话配置
  messages: { ... },         // 消息配置
  tools: { ... },            // 工具配置
  skills: { ... },           // 技能配置
  cron: { ... },             // 定时任务配置
  hooks: { ... },            // Webhook 配置
  bindings: [...],           // 绑定规则
  env: { ... },              // 环境变量
}

1. 에이전트 구성(에이전트)

1.1 기본 구성(agents.defaults)

json5

{
  agents: {
    defaults: {
      // 工作空间路径
      workspace: "~/.openclaw/workspace",
      
      // 模型配置
      model: {
        primary: "anthropic/claude-sonnet-4-5",
        fallbacks: ["openai/gpt-5.2"]
      },
      
      // 模型目录（用于 /model 命令）
      models: {
        "anthropic/claude-sonnet-4-5": {
          alias: "Sonnet"
        },
        "openai/gpt-5.2": {
          alias: "GPT"
        }
      },
      
      // 图片最大尺寸（像素）
      imageMaxDimensionPx: 1200,
      
      // 心跳配置
      heartbeat: {
        every: "30m",        // 30分钟、2小时等
        target: "last",      // last | whatsapp | telegram | discord | none
        directPolicy: "allow" // allow | block
      },
      
      // 沙盒配置
      sandbox: {
        mode: "non-main",    // off | non-main | all
        scope: "agent"       // session | agent | shared
      },
      
      // 工具配置
      tools: {
        enabled: true,
        profile: "full"
      }
    }
  }
}

구성 항목 설명:

구성 항목	유형	기본값	설명
`workspace`	문자열	~/.openclaw/작업 공간	에이전트 작업 디렉터리
`model.primary`	문자열	-	기본 모델, 형식: 공급자/모델
`model.fallbacks`	배열	[]	대체 모델 목록
`imageMaxDimensionPx`	번호	1200	이미지 전사/도구 이미지 확대/축소 크기
`heartbeat.every`	문자열	-	하트비트 간격(예: 30분, 2시간)
`sandbox.mode`	문자열	떨어져	샌드박스 모드

1.2 다중 에이전트 구성(agents.list)

json5

{
  agents: {
    list: [
      {
        id: "home",
        default: true,
        workspace: "~/.openclaw/workspace-home",
        groupChat: {
          mentionPatterns: ["@openclaw", "openclaw"]
        }
      },
      {
        id: "work",
        workspace: "~/.openclaw/workspace-work",
        model: {
          primary: "anthropic/claude-opus-4-6"
        }
      }
    ]
  }
}

2. 채널 구성(채널)

2.1 일반 DM 정책 구성

모든 채널은 동일한 DM 전략 패턴을 공유합니다.

json5

{
  channels: {
    telegram: {
      enabled: true,
      botToken: "123:abc",
      dmPolicy: "pairing",      // pairing | allowlist | open | disabled
      allowFrom: ["tg:123"],    // 仅用于 allowlist/open
    },
    
    whatsapp: {
      enabled: true,
      allowFrom: ["+15555550123"],
      groups: {
        "*": {
          requireMention: true
        }
      }
    },
    
    discord: {
      enabled: true,
      botToken: "${DISCORD_BOT_TOKEN}",
      dmPolicy: "pairing",
      allowFrom: ["discord:123"]
    },
    
    slack: {
      enabled: true,
      botToken: "${SLACK_BOT_TOKEN}",
      dmPolicy: "pairing"
    }
  }
}

DM 정책 옵션:

전략	설명
`pairing`	알 수 없는 발신자가 일회성 페어링 코드를 받았으며 승인이 필요함
`allowlist`	AllowFrom의 보낸 사람만
`open`	모든 인바운드 DM 허용(allowFrom: ["*"] 필요)
`disabled`	모든 DM 무시

2.2 그룹채팅 멘션 게이트 제어

json5

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

3. 게이트웨이 구성(게이트웨이)

json5

{
  gateway: {
    port: 18789,
    bind: "loopback",           // loopback | lan | tailnet | auto | custom
    auth: {
      mode: "token",            // token | password
      token: "${OPENCLAW_GATEWAY_TOKEN}",
      password: "${OPENCLAW_GATEWAY_PASSWORD}",
      allowTailscale: true
    },
    tailscale: {
      mode: "off",              // off | serve | funnel
      resetOnExit: false
    },
    reload: {
      mode: "hybrid",           // hybrid | hot | restart | off
      debounceMs: 300
    }
  }
}

바인딩 주소 옵션:

가치	설명
`loopback`	로컬 액세스 전용(127.0.0.1)
`lan`	LAN 접속 가능
`tailnet`	Tailscale 네트워크
`auto`	자동 감지
`custom`	맞춤 주소

핫 리로드 모드:

패턴	행동
`hybrid`	안전한 변경 사항을 즉시 적용하고 중요한 변경 사항을 자동으로 다시 시작(기본값)
`hot`	핫 적용 안전 변경 사항만 적용, 재시작이 필요한 경우 경고 기록
`restart`	구성이 변경되면 게이트웨이를 다시 시작하세요.
`off`	파일 모니터링 비활성화

4. 세션 구성(세션)

json5

{
  session: {
    dmScope: "per-channel-peer",  // main | per-peer | per-channel-peer | per-account-channel-peer
    
    threadBindings: {
      enabled: true,
      idleHours: 24,
      maxAgeHours: 0
    },
    
    reset: {
      mode: "daily",            // daily | idle | manual
      atHour: 4,
      idleMinutes: 120
    }
  }
}

DM 범위 옵션:

가치	설명
`main`	공유 세션
`per-peer`	피어별 독립 세션
`per-channel-peer`	채널별 - 피어에 대한 독립 세션(다중 사용자 권장)
`per-account-channel-peer`	계정-채널-피어별 독립 세션

5. 메시지 구성(메시지)

json5

{
  messages: {
    groupChat: {
      mentionPatterns: ["@openclaw"]
    }
  }
}

6. 도구 구성(도구)

json5

{
  tools: {
    profile: "full",              // messaging | default | coding | full | all
    enabled: true,
    web: {
      search: {
        apiKey: "${BRAVE_API_KEY}"
      }
    }
  }
}

도구 구성 파일:

프로필	설명
`messaging`	채팅만 가능, 도구 없음
`default`	기본 도구 세트
`coding`	프로그래밍 도구 세트
`full`	완전한 도구 세트
`all`	모든 도구

7. 스킬 구성(스킬)

json5

{
  skills: {
    entries: {
      "nano-banana-pro": {
        enabled: true,
        apiKey: {
          source: "file",
          provider: "filemain",
          id: "/skills/entries/nano-banana-pro/apiKey"
        }
      }
    }
  }
}

8. 예약된 작업 구성(cron)

json5

{
  cron: {
    enabled: true,
    maxConcurrentRuns: 2,
    sessionRetention: "24h",
    runLog: {
      maxBytes: "2mb",
      keepLines: 2000
    }
  }
}

9. 웹훅 설정(훅)

json5

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

10. 바인딩 구성(바인딩)

json5

{
  bindings: [
    {
      agentId: "home",
      match: {
        channel: "whatsapp",
        accountId: "personal"
      }
    },
    {
      agentId: "work",
      match: {
        channel: "whatsapp",
        accountId: "biz"
      }
    }
  ]
}

11. 환경변수 설정(env)

json5

{
  env: {
    OPENROUTER_API_KEY: "sk-or-...",
    vars: {
      GROQ_API_KEY: "gsk-..."
    },
    shellEnv: {
      enabled: true,
      timeoutMs: 15000
    }
  }
}

환경 변수 소스(우선순위 기준):

상위 프로세스 환경 변수
현재 작업 디렉터리의 .env 파일
~/.openclaw/.env 파일(전역 폴백)

둘 다 기존 환경 변수를 덮어쓰지 않습니다.

12. 구성 분할($include)

대규모 구성을 구성하려면 $include을 사용하세요.

json5

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

규칙:

단일 파일: 포함된 객체 교체
파일 배열: 순서대로 완전 병합(최신 것부터)
형제 키: 포함 후 병합(포함된 값 덮어쓰기)
중첩 포함: 최대 10레벨까지 지원
상대 경로: 포함 파일을 기준으로 확인됩니다.

13. 환경변수 교체

구성 문자열 값의 참조 환경 변수:

json5

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

규칙:

대문자 이름만 일치합니다: [A-Z_][A-Z0-9_]*
누락된/빈 변수는 로드하는 동안 오류가 발생합니다.
리터럴 출력으로 이스케이프하려면 $${VAR}을 사용하십시오.
$include 파일에서도 유효합니다.
인라인 교체: "${BASE}/v1" → "https://api.example.com/v1"

14. SecretRef 인증서

SecretRef 객체의 지원되는 필드:

json5

{
  models: {
    providers: {
      openai: {
        apiKey: {
          source: "env",
          provider: "default",
          id: "OPENAI_API_KEY"
        }
      }
    }
  },
  
  skills: {
    entries: {
      "nano-banana-pro": {
        apiKey: {
          source: "file",
          provider: "filemain",
          id: "/skills/entries/nano-banana-pro/apiKey"
        }
      }
    }
  },
  
  channels: {
    googlechat: {
      serviceAccountRef: {
        source: "exec",
        provider: "vault",
        id: "channels/googlechat/serviceAccount"
      }
    }
  }
}

소스 유형:

env : 환경변수
file: 파일 내용
exec : 명령어 실행 출력

15. 전체 구성 예시

15.1 최소 구성

json5

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

15.2 로컬 개발 구성

json5

{
  agents: {
    defaults: {
      workspace: "~/.openclaw/workspace",
      model: {
        primary: "ollama/llama3.2"
      }
    }
  },
  gateway: {
    port: 18789,
    bind: "loopback",
    auth: {
      mode: "token",
      token: "dev-token"
    }
  }
}

15.3 서버 배포 구성

json5

{
  agents: {
    defaults: {
      workspace: "~/.openclaw/workspace",
      model: {
        primary: "anthropic/claude-sonnet-4-5",
        fallbacks: ["openai/gpt-5.2"]
      }
    }
  },
  
  channels: {
    telegram: {
      enabled: true,
      botToken: "${TELEGRAM_BOT_TOKEN}",
      dmPolicy: "pairing"
    }
  },
  
  gateway: {
    port: 18789,
    bind: "lan",
    auth: {
      mode: "password",
      password: "${GATEWAY_PASSWORD}"
    }
  },
  
  session: {
    dmScope: "per-channel-peer"
  }
}

15.4 다중 에이전트 구성

json5

{
  agents: {
    defaults: {
      model: {
        primary: "anthropic/claude-sonnet-4-5"
      }
    },
    list: [
      {
        id: "home",
        default: true,
        workspace: "~/.openclaw/workspace-home"
      },
      {
        id: "work",
        workspace: "~/.openclaw/workspace-work",
        model: {
          primary: "anthropic/claude-opus-4-6"
        }
      }
    ]
  },
  
  bindings: [
    {
      agentId: "home",
      match: {
        channel: "whatsapp",
        accountId: "personal"
      }
    },
    {
      agentId: "work",
      match: {
        channel: "whatsapp",
        accountId: "biz"
      }
    }
  ]
}

16. 구성 편집 방법

대화형 마법사

bash

openclaw onboard          # 完整设置向导
openclaw configure        # 配置向导

CLI 명령

bash

openclaw config get agents.defaults.workspace
openclaw config set agents.defaults.heartbeat.every "2h"
openclaw config unset tools.web.search.apiKey
openclaw config file      # 查看配置文件路径
openclaw config validate  # 验证配置

웹 콘솔

http://127.0.0.1:18789을 열고 구성 탭을 사용합니다.

직접 편집

~/.openclaw/openclaw.json을 직접 편집하면 게이트웨이가 자동으로 변경 사항을 적용합니다.

17. 엄격한 검증

OpenClaw는 스키마와 정확히 일치하는 구성만 허용합니다. 알 수 없는 키, 잘못된 유형 또는 잘못된 값으로 인해 게이트웨이 시작이 거부될 수 있습니다.

검증에 실패하는 경우:

게이트웨이가 시작되지 않습니다.
진단 명령만 가능합니다. (openclaw doctor, openclaw logs, openclaw health, openclaw status)
특정 문제를 보려면 openclaw doctor을 실행하세요.
수정사항을 적용하려면 openclaw doctor --fix을 실행하세요.

18. 핫 리로드 지침

핫 애플리케이션 구성 지원

카테고리	필드	다시 시작해야 합니까?
채널	`channels.*`	아니요
에이전트 및 모델	`agent`, `agents`, `models`, `routing`	아니요
자동화	`hooks`, `cron`, `agent.heartbeat`	아니요
대화 및 메시지	`session`, `messages`	아니요
도구 및 미디어	`tools`, `browser`, `skills`, `audio`, `talk`	아니요
UI 및 기타	`ui`, `logging`, `identity`, `bindings`	아니요

다시 시작해야 하는 구성

카테고리	필드
게이트웨이 서버	`gateway.*`(포트, 바인딩, 인증, Tailscale, TLS, HTTP)
인프라	`discovery`, `canvasHost`, `plugins`

예외: gateway.reload 및 gateway.remote 변경 사항은 다시 시작을 트리거하지 않습니다.

팁: 이 자세한 구성 설명은 공식 OpenClaw 문서를 기반으로 합니다. 전체 내용을 보려면 docs.openclaw.ai/gateway/configuration을 방문하세요.

구성 파일 위치 ​

구성 파일 구조 개요 ​

1. 에이전트 구성(에이전트) ​

1.1 기본 구성(agents.defaults) ​

1.2 다중 에이전트 구성(agents.list) ​

2. 채널 구성(채널) ​

2.1 일반 DM 정책 구성 ​

2.2 그룹채팅 멘션 게이트 제어 ​

3. 게이트웨이 구성(게이트웨이) ​

4. 세션 구성(세션) ​

5. 메시지 구성(메시지) ​

6. 도구 구성(도구) ​

7. 스킬 구성(스킬) ​

8. 예약된 작업 구성(cron) ​

9. 웹훅 설정(훅) ​

10. 바인딩 구성(바인딩) ​

11. 환경변수 설정(env) ​

12. 구성 분할($include) ​

13. 환경변수 교체 ​

14. SecretRef 인증서 ​

15. 전체 구성 예시 ​

15.1 최소 구성 ​

15.2 로컬 개발 구성 ​

15.3 서버 배포 구성 ​

15.4 다중 에이전트 구성 ​

16. 구성 편집 방법 ​

대화형 마법사 ​

CLI 명령 ​

웹 콘솔 ​

직접 편집 ​

17. 엄격한 검증 ​

18. 핫 리로드 지침 ​

핫 애플리케이션 구성 지원 ​

다시 시작해야 하는 구성 ​

구성 파일 위치

구성 파일 구조 개요

1. 에이전트 구성(에이전트)

1.1 기본 구성(agents.defaults)

1.2 다중 에이전트 구성(agents.list)

2. 채널 구성(채널)

2.1 일반 DM 정책 구성

2.2 그룹채팅 멘션 게이트 제어

3. 게이트웨이 구성(게이트웨이)

4. 세션 구성(세션)

5. 메시지 구성(메시지)

6. 도구 구성(도구)

7. 스킬 구성(스킬)

8. 예약된 작업 구성(cron)

9. 웹훅 설정(훅)

10. 바인딩 구성(바인딩)

11. 환경변수 설정(env)

12. 구성 분할($include)

13. 환경변수 교체

14. SecretRef 인증서

15. 전체 구성 예시

15.1 최소 구성

15.2 로컬 개발 구성

15.3 서버 배포 구성

15.4 다중 에이전트 구성

16. 구성 편집 방법

대화형 마법사

CLI 명령

웹 콘솔

직접 편집

17. 엄격한 검증

18. 핫 리로드 지침

핫 애플리케이션 구성 지원

다시 시작해야 하는 구성