설정 시스템

Clawdbot의 설정 파일 구조와 관리 방법

📋 목록

설정 파일 위치

설정 구조

📁 설정 파일 위치

기본 경로

플랫폼	기본 경로	설명
macOS	~/.clawdbot/	사용자 홈 디렉토리
Linux	~/.clawdbot/	사용자 홈 디렉토리
Windows	%APPDATA%\clawdbot\	사용자 앱 데이터 디렉토리
Docker	/root/.clawdbot/	컨테이너 내

설정 파일 구조

~/.clawdbot/
├── clawdbot.json          # 메인 설정 파일
├── credentials/             # API 키 및 채널 크레덴셜
│   ├── anthropic.json
│   ├── openai.json
│   ├── whatsapp.json
│   ├── telegram.json
│   └── ...
├── channels/               # 채널별 설정
│   ├── whatsapp/
│   │   ├── allowlist.json
│   │   └── session.json
│   ├── telegram/
│   └── ...
├── gateway/               # Gateway 전용 설정
│   ├── tls/
│   │   ├── cert.pem
│   │   └── key.pem
│   └── state.json
└── logs/                  # 로그 파일들

🎨 설정 구조

메인 설정 파일 (clawdbot.json)

{
  // ========== 게이트웨이 설정 ==========
  gateway: {
    port: 18789,                    // WebSocket 서버 포트
    bind: "loopback",               // 바인드 주소
    host: "127.0.0.1",             // 호스트 주소 (선택적)
    controlUi: true,                // 웹 UI 활성화
    controlUiPort: 18792,           // 웹 UI 포트
    auth: {
      mode: "password",              // 인증 모드: password, token, none
      password: "secure-password"      // mode="password" 시 필요
      // 또는
      // token: "auth-token-xyz123"   // mode="token" 시 필요
    },
    tls: {
      enabled: true,                 // TLS 활성화
      certPath: "~/.clawdbot/gateway/tls/cert.pem",
      keyPath: "~/.clawdbot/gateway/tls/key.pem",
      caPath: "~/.clawdbot/gateway/tls/ca.pem",  // 선택적
      autoGenerate: true             // 자체 서명 인증서 자동 생성
    },
    tailscale: {
      enabled: true,                 // Tailscale 통합 활성화
      allowTailscale: true         // Tailscale IP 자동 인증 허용
    },
    remote: {
      enabled: false,                // 원격 Gateway 활성화
      url: "ws://remote-host:18789"  // 원격 Gateway URL
      auth: {
        token: "remote-auth-token"   // 원격 Gateway 인증 토큰
      }
    }
  },

  // ========== 에이전트 설정 ==========
  agent: {
    model: "anthropic/claude-opus-4-5",  // 기본 모델
    thinkingLevel: "high",              // 사고 레벨: low, medium, high
    temperature: 0.7,                 // 온도 (0.0 ~ 1.0)
    maxTokens: 100000,                // 최대 토큰 수
    workspace: "~/clawd",              // 워크스페이스 경로
    systemPrompt: "~/.clawdbot/system.md",  // 시스템 프롬프트 (선택적)
    persona: "~/.clawdbot/persona.md",    // 페르소나 설정 (선택적)
    memory: {
      enabled: true,                 // 메모리 기능 활성화
      maxEntries: 1000,             // 최대 기록 수
      compaction: true               // 기록 압축 활성화
    }
  },

  // ========== 채널 설정 ==========
  channels: {
    // WhatsApp
    whatsapp: {
      enabled: true,
      dmPolicy: "pairing",            // DM 정책: pairing, open
      allowFrom: ["+1234567890", "*"],  // 연결 허용
      groupPolicy: {
        mode: "mention",            // 그룹 정책: mention, always
        mentions: ["clawdbot", "@clawdbot"]
      },
      replyTag: "[clawdbot]",          // 리플 태그
      maxAttachments: 10               // 최대 첨부 수
    },

    // Telegram
    telegram: {
      enabled: true,
      botToken: "123456:ABCDEF1234...",
      dmPolicy: "open",
      groupPolicy: {
        mode: "mention",
        mentions: ["clawdbot_bot", "@clawdbot_bot"]
      },
      inlineMode: false,
      webhookUrl: "https://your-domain.com/webhook"
    },

    // Slack
    slack: {
      enabled: true,
      token: "xoxb-1234567890-ABCDEF...",
      dm: {
        policy: "open",
        allowFrom: ["U1234567890", "*"]
      },
      appLevelToken: "xapp-...",
      signingSecret: "..."
    },

    // Discord
    discord: {
      enabled: true,
      token: "MTIyNzE1234...",
      dm: {
        policy: "open",
        allowFrom: ["1234567890123456789", "*"]
      },
      commandPrefix: "!",
      intents: ["guilds", "messages", "message_content"]
    },

    // Google Chat
    googlechat: {
      enabled: false,
      clientId: "...",
      clientSecret: "...",
      redirectUri: "https://your-domain.com/callback"
    },

    // Signal
    signal: {
      enabled: false,
      phoneNumber: "+1234567890",
      groupPolicy: {
        mode: "always"
      }
    },

    // iMessage
    imessage: {
      enabled: false,
      dmPolicy: "open",
      groupPolicy: {
        mode: "always"
      }
    },

    // WebChat
    webchat: {
      enabled: true,
      corsOrigins: ["https://your-domain.com"],
      allowAnonymous: true
    }
  },

  // ========== 브라우저 설정 ==========
  browser: {
    enabled: true,
    controlUrl: "http://127.0.0.1:18791",
    color: "#FF4500",
    headless: false,
    userDataDir: "~/.clawdbot/browser"
  },

  // ========== 캔버스 설정 ==========
  canvas: {
    enabled: true,
    port: 18793,
    host: "127.0.0.1",
    maxCanvasSize: 10485760,    // 10MB
    enableSnapshots: true
  },

  // ========== 샌드박스 설정 ==========
  sandbox: {
    mode: "non-main",              // none, non-main, all
    allowlist: [
      "bash",
      "process",
      "read",
      "write",
      "edit",
      "sessions_list",
      "sessions_history"
    ],
    denylist: [
      "browser",
      "canvas",
      "nodes",
      "cron",
      "discord",
      "slack",
      "gateway"
    ],
    dockerImage: "clawdbot/sandbox:latest",
    dockerTimeout: 300,             // 5분
    hostVolumePath: "/workspace"
  },

  // ========== 로깅 설정 ==========
  logging: {
    level: "info",                 // debug, info, warn, error
    file: {
      enabled: true,
      path: "~/.clawdbot/logs",
      maxSize: "100MB",
      maxFiles: 10
    },
    console: {
      enabled: true,
      colorize: true
    }
  },

  // ========== 세션 설정 ==========
  sessions: {
    maxSessions: 100,             // 최대 세션 수
    compaction: true,              // 기록 압축 활성화
    maxHistory: 1000,             // 최대 기록 수
    compactionThreshold: 10000,     // 압축 임계값
    compactionAfter: 3600,         // 1시간 후 압축
    autoExpire: false,            // 자동 만료 비활성화
    maxAge: 604800               // 7일 (초)
  },

  // ========== 에이전트 바인딩 ==========
  agents: {
    bindings: {
      // 채널:계정:피어 → 워크스페이스
      "whatsapp:+1234567890": "main",
      "whatsapp:+9876543210": "personal",
      "telegram:@clawdbot_bot": "main",
      "discord:server:123456789": "work",
      "slack:workspace:U1234567890": "main"
    },

    // 다중 워크스페이스
    workspaces: {
      "main": "~/clawd",
      "personal": "~/clawd-personal",
      "work": "~/clawd-work"
    },

    // 에이전트별 설정
    defaults: {
      thinkingLevel: "medium",
      temperature: 0.7,
      maxTokens: 100000
    }
  },

  // ========== 자동화 설정 ==========
  automation: {
    cron: {
      enabled: true,
      timezone: "UTC"
    },
    webhooks: {
      enabled: true,
      verifySecret: true
    },
    gmail: {
      enabled: false,
      watchInbox: false
    }
  },

  // ========== 피처 플래그 ==========
  features: {
    backgroundSync: true,           // 백그라운드 동기화
    presence: true,                // 프레즌스 기능
    voiceWake: true,               // 음성 웨이크
    metrics: false,                // 메트릭 수집
    analytics: false               // 분석 수집
  }
}

🔧 게이트웨이 설정

포트 및 바인딩

{
  gateway: {
    port: 18789,                    // 기본 포트
    bind: "loopback",               // 루프백만 허용
    // 또는
    // bind: "0.0.0.0"              // 모든 인터페이스 허용
  }
}

인증 설정

{
  gateway: {
    auth: {
      mode: "password",              // password, token, none
      password: "secure-password"      // mode="password" 시 필요
      // 또는
      // token: "auth-token-xyz123"   // mode="token" 시 필요
    }
  }
}

TLS 설정

{
  gateway: {
    tls: {
      enabled: true,                 // TLS 활성화
      certPath: "~/.clawdbot/gateway/tls/cert.pem",
      keyPath: "~/.clawdbot/gateway/tls/key.pem",
      caPath: "~/.clawdbot/gateway/tls/ca.pem",  // 선택적
      autoGenerate: true             // 자체 서명 인증서 자동 생성
    }
  }
}

📱 채널 설정

WhatsApp 설정

{
  channels: {
    whatsapp: {
      enabled: true,
      dmPolicy: "pairing",            // pairing, open
      allowFrom: ["+1234567890", "*"],  // "*": 모든 연결 허용
      groupPolicy: {
        mode: "mention",            // mention, always
        mentions: ["clawdbot", "@clawdbot"]
      },
      replyTag: "[clawdbot]",          // 리플 태그
      maxAttachments: 10               // 최대 첨부 수
    }
  }
}

Telegram 설정

{
  channels: {
    telegram: {
      enabled: true,
      botToken: "123456:ABCDEF1234...",
      dmPolicy: "open",
      groupPolicy: {
        mode: "mention",
        mentions: ["clawdbot_bot", "@clawdbot_bot"]
      },
      inlineMode: false,
      webhookUrl: "https://your-domain.com/webhook"
    }
  }
}

채널별 공통 설정

{
  channels: {
    [channel-name]: {
      enabled: true,                  // 채널 활성화
      dmPolicy: "pairing",            // DM 정책
      allowFrom: ["user1", "*"],    // 연결 허용
      groupPolicy: {
        mode: "mention",            // 그룹 정책
        mentions: ["bot-name"]
      }
    }
  }
}

🤖 에이전트 설정

기본 에이전트 설정

{
  agent: {
    model: "anthropic/claude-opus-4-5",  // 기본 모델
    thinkingLevel: "high",              // 사고 레벨: low, medium, high
    temperature: 0.7,                 // 온도 (0.0 ~ 1.0)
    maxTokens: 100000,                // 최대 토큰 수
    workspace: "~/clawd"               // 워크스페이스 경로
  }
}

다중 워크스페이스

{
  agents: {
    bindings: {
      // 채널:계정:피어 → 워크스페이스
      "whatsapp:+1234567890": "main",
      "whatsapp:+9876543210": "personal",
      "telegram:@clawdbot_bot": "main",
      "discord:server:123456789": "work"
    },

    // 다중 워크스페이스
    workspaces: {
      "main": "~/clawd",
      "personal": "~/clawd-personal",
      "work": "~/clawd-work"
    },

    // 에이전트별 기본 설정
    defaults: {
      thinkingLevel: "medium",
      temperature: 0.7,
      maxTokens: 100000
    }
  }
}

🛠 샌드박스 설정

샌드박스 모드

{
  sandbox: {
    mode: "non-main",              // none, non-main, all
    allowlist: [
      "bash",
      "process",
      "read",
      "write",
      "edit",
      "sessions_list",
      "sessions_history"
    ],
    denylist: [
      "browser",
      "canvas",
      "nodes",
      "cron",
      "discord",
      "slack",
      "gateway"
    ],
    dockerImage: "clawdbot/sandbox:latest",
    dockerTimeout: 300,             // 5분
    hostVolumePath: "/workspace"
  }
}

도구 권한

도구 그룹	포함 도구	비-Main 허용
파일	read, write, edit, list, delete	✅
프로세스	process, bash	✅
세션	sessions_list, sessions_history	✅
브라우저	browser.*	❌
Canvas	canvas.*	❌
노드	camera., screen., location.*	❌
자동화	cron., webhook.	❌
Gateway	gateway.*	❌
채널	discord., slack.	❌

🔍 설정 관리 명령어

설정 조회

# 전체 설정 조회
clawdbot config get

# 특정 설정 조회
clawdbot config get agent.model

# 중첩 설정 조회
clawdbot config get channels.whatsapp.enabled

# 스키마 조회
clawdbot config get --schema

설정 변경

# 설정 변경
clawdbot config set agent.model "anthropic/claude-opus-4-5"

# 중첩 설정 변경
clawdbot config set channels.whatsapp.dmPolicy "open"

# 복수 설정 변경
clawdbot config set sandbox.allowlist '["bash","read","write"]'

# 설정 삭제
clawdbot config set channels.whatsapp.dmPolicy null

설정 편집

# 설정 편집기 열기
clawdbot config edit

# 특정 파일 편집
clawdbot config edit channels

설정 검증

# 설정 검증
clawdbot config validate

# 스키마 검증
clawdbot config validate --schema

🔗 관련 문서

•

•

•

•