홈 튜토리얼 카테고리 Skills 소개
ZH EN JA KO
기본 설정

OpenClaw 구성 파일 openclaw.json5 완전 가이드

· 16 분 소요

들어가며

OpenClaw의 핵심 구성 파일은 openclaw.json5이며, 기본 위치는 ~/.config/openclaw/openclaw.json5입니다. 이 파일은 JSON5 형식을 사용하여 주석과 더 유연한 구문을 지원하므로 구성 과정이 더욱 편리합니다. 본 문서에서는 모든 구성 섹션과 옵션을 하나씩 상세히 설명합니다.

JSON5 형식 소개

JSON5는 JSON의 상위 집합으로, 주요 추가 기능은 다음과 같습니다.

{
  // 한 줄 주석 지원
  /* 여러 줄 주석도 지원 */

  // 키 이름에 따옴표 불필요
  gateway: {
    port: 18789,
  },

  // 후행 쉼표 지원
  tags: [
    "ai",
    "assistant",
  ],

  // 작은따옴표 문자열 지원
  name: 'OpenClaw',

  // 여러 줄 문자열 지원
  prompt: "첫 번째 줄\
    두 번째 줄",
}

JSON5에 익숙하지 않다면 "주석을 쓸 수 있는 JSON"으로 이해하면 됩니다.

구성 파일 경로

플랫폼 기본 경로
Linux ~/.config/openclaw/openclaw.json5
macOS ~/.config/openclaw/openclaw.json5
Windows %USERPROFILE%\.config\openclaw\openclaw.json5
Docker /app/config/openclaw.json5 (볼륨 매핑을 통해)

환경 변수를 통해 커스텀 경로를 지정할 수도 있습니다.

export OPENCLAW_CONFIG=/path/to/your/openclaw.json5
openclaw up

전체 구성 구조 개요

{
  gateway: { /* 게이트웨이 설정 */ },
  models: { /* 모델 구성 */ },
  channels: { /* 채널 연동 */ },
  skills: { /* 스킬 플러그인 */ },
  persona: { /* AI 페르소나 */ },
  logging: { /* 로그 설정 */ },
  security: { /* 보안 설정 */ },
  advanced: { /* 고급 옵션 */ },
}

아래에서 각 구성 섹션을 하나씩 상세히 설명합니다.

gateway: 게이트웨이 설정

게이트웨이는 OpenClaw의 핵심 진입점으로, 모든 HTTP 요청과 채널 메시지를 처리합니다.

{
  gateway: {
    // 리스닝 포트, 기본값 18789
    port: 18789,

    // 리스닝 주소
    // "127.0.0.1" 로컬만 접근 가능
    // "0.0.0.0" 모든 네트워크에서 접근 허용
    host: "0.0.0.0",

    // Dashboard 비밀번호 (프로덕션 환경에서 설정 권장)
    dashboardPassword: "your-strong-password",

    // API 키 (외부에서 OpenClaw API 호출 시 사용)
    apiKey: "your-api-key",

    // 요청 시간 제한 (밀리초)
    timeout: 120000,

    // 최대 요청 본문 크기
    maxBodySize: "10mb",

    // CORS 설정
    cors: {
      enabled: true,
      origins: ["*"],
    },
  },
}

주요 매개변수 설명

매개변수 유형 기본값 설명
port number 18789 게이트웨이 포트
host string "127.0.0.1" 리스닝 주소
dashboardPassword string 없음 Dashboard 접근 비밀번호
apiKey string 없음 API 인증 키
timeout number 120000 요청 시간 제한 (ms)
maxBodySize string "10mb" 최대 요청 본문

models: 모델 구성

모델 구성은 OpenClaw가 사용할 AI 모델과 호출 방법을 정의합니다.

{
  models: {
    // 기본 모델 제공업체
    default: "claude",

    // 각 모델 제공업체 구성
    providers: {
      claude: {
        apiKey: "sk-ant-xxxxx",
        model: "claude-sonnet-4-20250514",
        maxTokens: 4096,
        temperature: 0.7,
        baseUrl: "https://api.anthropic.com",  // 선택 사항, 커스텀 API 엔드포인트
      },

      openai: {
        apiKey: "sk-xxxxx",
        model: "gpt-4o",
        maxTokens: 4096,
        temperature: 0.7,
        baseUrl: "https://api.openai.com/v1",
      },

      ollama: {
        baseUrl: "http://localhost:11434",
        model: "llama3.1",
        maxTokens: 2048,
      },

      gemini: {
        apiKey: "AIzaSyxxxxx",
        model: "gemini-2.0-flash",
        maxTokens: 4096,
      },

      openrouter: {
        apiKey: "sk-or-xxxxx",
        model: "anthropic/claude-sonnet-4-20250514",
        baseUrl: "https://openrouter.ai/api/v1",
      },
    },

    // 모델 라우팅 규칙 (다중 모델 전환 튜토리얼 참조)
    routing: {
      rules: [],
      fallback: "claude",
    },
  },
}

각 제공업체 필수 매개변수

제공업체 필수 매개변수 선택 매개변수
Claude apiKey, model maxTokens, temperature, baseUrl
OpenAI apiKey, model maxTokens, temperature, baseUrl
Ollama baseUrl, model maxTokens, temperature
Gemini apiKey, model maxTokens, temperature
OpenRouter apiKey, model maxTokens, baseUrl

channels: 채널 연동

채널 구성은 OpenClaw가 연결할 메신저 플랫폼을 정의합니다.

{
  channels: {
    whatsapp: {
      enabled: true,
      phoneNumber: "+86138xxxx",
      // WhatsApp Business API 구성
      accessToken: "your-access-token",
      verifyToken: "your-verify-token",
      webhookPath: "/webhook/whatsapp",
    },

    telegram: {
      enabled: true,
      token: "123456:ABC-DEF...",
      // 선택 사항: 허용된 사용자 제한
      allowedUsers: [12345678, 87654321],
      // 선택 사항: 허용된 그룹 제한
      allowedGroups: [-100123456789],
    },

    discord: {
      enabled: true,
      token: "your-discord-bot-token",
      allowedChannels: ["general", "ai-chat"],
    },

    slack: {
      enabled: true,
      appToken: "xapp-xxxxx",
      botToken: "xoxb-xxxxx",
    },

    // 추가 채널...
    // imessage, signal, teams, googlechat, matrix, line, irc
  },
}

skills: 스킬 플러그인

스킬은 OpenClaw의 확장 메커니즘으로, SKILL.md 파일 형태로 ~/.openclaw/skills/ 디렉토리에 저장됩니다.

{
  skills: {
    // 스킬 파일 저장 디렉토리
    directory: "~/.openclaw/skills",

    // 활성화된 스킬 목록 (비어 있으면 모두 활성화)
    enabled: [
      "weather",
      "calculator",
      "translator",
    ],

    // 비활성화된 스킬 목록
    disabled: [],

    // MCP Server 통합
    mcpServers: {
      filesystem: {
        command: "npx",
        args: ["-y", "@modelcontextprotocol/server-filesystem", "/home/user/documents"],
      },
      web: {
        command: "npx",
        args: ["-y", "@anthropic/mcp-server-web"],
      },
    },
  },
}

persona: AI 페르소나

페르소나 구성은 AI 어시스턴트의 성격과 응답 스타일을 결정합니다.

{
  persona: {
    // 시스템 프롬프트
    systemPrompt: "당신은 친근하고 전문적인 AI 어시스턴트이며, 이름은 '지니'입니다. 간결하고 명확한 한국어로 질문에 답변합니다.",

    // 페르소나 이름
    name: "지니",

    // 응답 언어 (auto는 자동 감지)
    language: "zh-CN",

    // 어조 스타일: formal, casual, friendly, professional
    tone: "friendly",

    // 각 채널별 독립 페르소나 (전역 설정을 덮어씀)
    channelOverrides: {
      telegram: {
        systemPrompt: "당신은 Telegram 그룹의 관리 어시스턴트입니다...",
        tone: "casual",
      },
      slack: {
        systemPrompt: "당신은 팀의 업무 어시스턴트이며, 전문적이고 간결하게 응답합니다...",
        tone: "professional",
      },
    },
  },
}

logging: 로그 설정

{
  logging: {
    // 로그 레벨: debug, info, warn, error
    level: "info",

    // 로그 파일 경로 (비어 있으면 콘솔에만 출력)
    file: "~/.openclaw/logs/openclaw.log",

    // 로그 파일 최대 크기
    maxSize: "10m",

    // 보관할 로그 파일 수
    maxFiles: 5,

    // 콘솔에 컬러 로그 출력 여부
    colorize: true,

    // 로그 형식: json, text
    format: "text",
  },
}

security: 보안 설정

{
  security: {
    // 요청 속도 제한 활성화
    rateLimit: {
      enabled: true,
      maxRequests: 60,     // 분당 최대 요청 수
      windowMs: 60000,     // 윈도우 시간 (밀리초)
    },

    // IP 화이트리스트 (비어 있으면 제한 없음)
    ipWhitelist: [],

    // IP 블랙리스트
    ipBlacklist: [],

    // HTTPS 활성화 (인증서 제공 필요)
    tls: {
      enabled: false,
      cert: "/path/to/cert.pem",
      key: "/path/to/key.pem",
    },
  },
}

advanced: 고급 옵션

{
  advanced: {
    // 작업 스레드 수 (0은 자동)
    workers: 0,

    // 메시지 큐 크기
    queueSize: 100,

    // 컨텍스트 메모리의 최대 메시지 수
    maxContextMessages: 20,

    // 컨텍스트 메모리의 최대 토큰 수
    maxContextTokens: 8000,

    // 데이터 저장 백엔드: memory, sqlite, redis
    storage: "sqlite",

    // SQLite 데이터베이스 경로
    dbPath: "~/.openclaw/data/openclaw.db",

    // Redis 연결 (storage가 redis인 경우)
    redis: {
      url: "redis://localhost:6379",
      db: 0,
    },
  },
}

환경 변수를 통한 덮어쓰기

구성 파일의 일부 민감한 필드는 환경 변수를 통해 덮어쓸 수 있어 키를 파일에 직접 기록하지 않아도 됩니다.

# 모델 API 키
export OPENCLAW_CLAUDE_API_KEY="sk-ant-xxxxx"
export OPENCLAW_OPENAI_API_KEY="sk-xxxxx"

# 채널 Token
export OPENCLAW_TELEGRAM_TOKEN="123456:ABC-DEF..."
export OPENCLAW_DISCORD_TOKEN="your-discord-token"

# 게이트웨이 비밀번호
export OPENCLAW_DASHBOARD_PASSWORD="your-password"

구성 파일에서 $env를 사용하여 참조합니다.

{
  models: {
    providers: {
      claude: {
        apiKey: "$env:OPENCLAW_CLAUDE_API_KEY",
        model: "claude-sonnet-4-20250514",
      },
    },
  },
}

구성 검증

구성 파일 수정 후 시작 전에 구성이 올바른지 검증할 수 있습니다.

# 구성 파일 구문 및 필수 항목 점검
openclaw doctor

# 구성 파일만 검증 (서비스 시작 안 함)
openclaw doctor --config-only

최소 구성 예제

가장 기본적인 기능만 필요하다면 구성 파일을 매우 간결하게 작성할 수 있습니다.

{
  models: {
    default: "claude",
    providers: {
      claude: {
        apiKey: "sk-ant-xxxxx",
        model: "claude-sonnet-4-20250514",
      },
    },
  },
  channels: {
    telegram: {
      enabled: true,
      token: "your-telegram-bot-token",
    },
  },
}

명시적으로 설정하지 않은 옵션은 기본값이 사용됩니다.

마무리

openclaw.json5는 OpenClaw의 핵심 구성 파일로, 인간 친화적인 JSON5 형식을 사용하여 주석과 유연한 구문을 지원합니다. 각 구성 섹션의 역할을 이해한 후에는 실제 요구에 맞게 OpenClaw의 동작을 정밀하게 조정할 수 있습니다. 최소 구성부터 시작하여 필요한 기능 모듈을 점진적으로 추가하는 것을 권장합니다. 구성 수정 후에는 openclaw doctor로 검증하고 openclaw restart로 리로드하는 것을 잊지 마십시오.

OpenClaw는 무료 오픈소스 개인 AI 어시스턴트로, WhatsApp, Telegram, Discord 등 다양한 플랫폼을 지원합니다
더 많은 튜토리얼 Skills 다운로드

관련 튜토리얼

Gateway 설정 완전 레퍼런스
openclaw onboard 대화형 가이드 튜토리얼
openclaw configure 설정 마법사 튜토리얼