# 설정 시스템

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

---

## 📋 목록

1. [설정 파일 위치](https://#%EC%84%A4%EC%A0%95-%ED%8C%8C%EC%9D%BC-%EC%9C%84%EC%B9%98)

2. [설정 구조](https://#%EC%84%A4%EC%A0%95-%EA%B5%AC%EC%A1%B0)

3. [게이트웨이 설정](https://#%EA%B2%8C%EC%9D%B4%ED%8A%B8%EC%9B%A8%EC%9D%B4-%EC%84%A4%EC%A0%95)

4. [채널 설정](https://#%EC%B1%84%EB%84%90-%EC%84%A4%EC%A0%95)

5. [에이전트 설정](https://#%EC%97%90%EC%9D%B4%EC%A0%84%ED%8A%B8-%EC%84%A4%EC%A0%95)

6. [브라우저 설정](https://#%EB%B8%8C%EB%9D%BC%EC%9A%B0%EC%A0%80-%EC%84%A4%EC%A0%95)

7. [샌드박스 설정](https://#%EC%83%8C%EB%93%9C%EB%B0%95%EC%8A%A4-%EC%84%A4%EC%A0%95)

8. [보안 설정](https://#%EB%B3%B4%EC%95%88-%EC%84%A4%EC%A0%95)

---

## 📁 설정 파일 위치

### 기본 경로

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

### 설정 파일 구조

```javascript
~/.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`)

```javascript
{
  // ========== 게이트웨이 설정 ==========
  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               // 분석 수집
  }
}
```

---

## 🔧 게이트웨이 설정

### 포트 및 바인딩

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

### 인증 설정

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

### TLS 설정

```javascript
{
  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 설정

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

### Telegram 설정

```javascript
{
  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"
    }
  }
}
```

### 채널별 공통 설정

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

---

## 🤖 에이전트 설정

### 기본 에이전트 설정

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

### 다중 워크스페이스

```javascript
{
  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
    }
  }
}
```

---

## 🛠 샌드박스 설정

### 샌드박스 모드

```javascript
{
  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.*` | ❌ |

---

## 🔍 설정 관리 명령어

### 설정 조회

```javascript
# 전체 설정 조회
clawdbot config get

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

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

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

### 설정 변경

```javascript
# 설정 변경
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
```

### 설정 편집

```javascript
# 설정 편집기 열기
clawdbot config edit

# 특정 파일 편집
clawdbot config edit channels
```

### 설정 검증

```javascript
# 설정 검증
clawdbot config validate

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

---

## 🔗 관련 문서

- [설치 가이드](https://../deployment/installation.md)

- [CLI 명령어](https://commands.md)

- [워크스페이스](https://workspace.md)

- [보안 설정](https://../security/README.md)

For the site tree, see the [root Markdown](https://slashpage.com/techkwon.md).