1. 아키텍처                                                                                                                                                                                                                           
================================================================================                                                                                                                                                      

  [Telegram Bot API]
        │
  [bot] ── polling ──→ [openclaw-gateway :18789]
                                       │
  [Caddy WAF :80/443]   ├── Claude Sonnet 4 (Anthropic API)
    IP 화이트리스트           ├── Brave Search (web_search 도구)
    ↓                                 ├── workspace 볼륨 (영구 메모리)
  [Traefik :8080]              └── config 볼륨 (설정/인증)
    ↓
  [openclaw-gateway :18789]

 

2. 파일 구조
================================================================================

  openclaw
  ├── docker/
  │   ├── docker-compose.yml      # 서비스 정의
  │   ├── .env.example            # 환경변수 템플릿
  │   └── .env                    # 실제 환경변수 (gitignored)
  ├── .gitlab-ci.yml              # CI/CD 파이프라인
  ├── .healthcheck-url            # 헬스체크 URL
  ├── .gitignore
  └── README.md

  Docker 볼륨:
  ├── docker_config   → /home/node/.openclaw/          (설정, 인증)
  └── docker_workspace → /home/node/.openclaw/workspace/ (메모리, 대화)

3. 주요 설정 파일
================================================================================

  [openclaw.json] — 메인 설정
  ─────────────────────────────────────────────────────────────────────
  - agents.defaults.model.primary: anthropic/claude-sonnet-4-20250514
  - gateway.port: 18789
  - gateway.mode: local
  - gateway.controlUi.dangerouslyDisableDeviceAuth: true
  - gateway.trustedProxies: ["172.19.0.6", "172.19.0.8"]
  - channels.telegram.enabled: true
  - channels.telegram.dmPolicy: pairing
  - channels.telegram.groupPolicy: open
  - channels.telegram.groups.*.requireMention: true
  - channels.telegram.streamMode: partial
  - session.reset.mode: idle
  - session.reset.idleMinutes: 240 (DM: 4시간)
  - session.resetByType.group.idleMinutes: 60 (그룹: 1시간)
  - session.resetTriggers: ["/new", "/reset"]

  [auth-profiles.json] — LLM 인증
  ─────────────────────────────────────────────────────────────────────
  경로: /home/node/.openclaw/agents/main/agent/auth-profiles.json
  방식: setup-token (type: "token", provider: "anthropic")
  주의: alpine sh heredoc으로 쓰면 따옴표 제거됨 → base64 인코딩 필수

  [.env] — 환경변수
  ─────────────────────────────────────────────────────────────────────
  OPENCLAW_GATEWAY_TOKEN=<게이트웨이 인증 토큰>
  TELEGRAM_BOT_TOKEN=<@BotFather 발급 토큰>
  BRAVE_API_KEY=<Brave Search API 키>

 

4. Anthropic 인증 (setup-token 방식)
================================================================================

  1. 로컬 PC에서: claude setup-token → 토큰 생성 (sk-ant-oat01-...)
  2. auth-profiles.json에 저장:
     {
       "profiles": {
         "anthropic:default": {
           "type": "token",
           "provider": "anthropic",
           "token": "sk-ant-oat01-..."
         }
       }
     }
  3. 경로: /home/node/.openclaw/agents/main/agent/auth-profiles.json
  4. 파일 소유자: 1000:1000 (node 사용자)

  ※ 파일 작성 시 주의:
     - docker run alpine sh heredoc → 따옴표 제거됨 (JSON 깨짐)
     - 해결: base64 인코딩 후 base64 -d로 디코딩하여 작성

 

5. Telegram 봇 연동
================================================================================

  설정 방법:
  1. @BotFather에서 봇 생성 → 토큰 발급
  2. .env에 TELEGRAM_BOT_TOKEN 추가
  3. openclaw.json에 channels.telegram 섹션 추가
  4. docker compose up -d (환경변수 반영은 restart가 아닌 up -d)
  5. 봇에 첫 메시지 → 페어링 코드 발급
  6. openclaw pairing approve telegram <CODE> --notify

  DM 정책 옵션:
  - pairing: 페어링 코드 승인 필요 (권장)
  - allowlist: 지정된 사용자만
  - open: 모두 허용
  - disabled: DM 비활성화

  토큰 해석 우선순위:
  1. channels.telegram.accounts.<id>.tokenFile
  2. channels.telegram.accounts.<id>.botToken
  3. channels.telegram.tokenFile
  4. channels.telegram.botToken
  5. 환경변수 TELEGRAM_BOT_TOKEN

 

6. 웹 검색 도구 (web_search)
================================================================================

  [Brave Search — 선택됨]
  - 무료: 2,000건/월, 1건/초
  - 환경변수: BRAVE_API_KEY
  - 기본 프로바이더 (별도 설정 불필요)
  - 응답: 검색 결과 목록 (제목, URL, 요약)

  [Perplexity — 대안]
  - 무료 없음. Pro 구독($20/월) 시 $5 크레딧 포함
  - 환경변수: PERPLEXITY_API_KEY 또는 OPENROUTER_API_KEY
  - openclaw.json: tools.web.search.provider: "perplexity"
  - 응답: AI 합성 답변 + 출처 URL
  - LLM 에이전트와 중복 (비효율적)

 

7. 세션 리셋 정책
================================================================================

  모드:
  - daily: 매일 지정 시각에 리셋 (기본: 새벽 4시)
  - idle: 마지막 메시지 후 N분 비활동 시 리셋

  현재 설정:
  - DM: idle 240분 (4시간)
  - 그룹: idle 60분 (1시간)
  - 수동: /new 또는 /reset

  평가 시점: 메시지 수신 시 (백그라운드 타이머 없음)
  daily + idle 동시 설정 시: 먼저 만료되는 쪽이 적용

 

8. 봇 성격 커스터마이징 (workspace 파일)
================================================================================

  /home/node/.openclaw/workspace/
  ├── IDENTITY.md   — 이름, 이모지, 성격 요약
  ├── SOUL.md       — 말투, 원칙, 톤 (깊은 성격)
  ├── AGENTS.md     — 운영 매뉴얼 (메모리, 안전, 그룹 예절)
  ├── USER.md       — 사용자 프로필
  ├── TOOLS.md      — 환경별 도구 메모
  ├── HEARTBEAT.md  — 주기적 백그라운드 작업
  └── memory/       — 일별 메모리 로그

  현재 설정:
  - 이름: 클로이 (Chloe)
  - 이모지: 🤖
  - 사용자: 김영훈 (영훈님)
  - SOUL.md: 기본 영문 템플릿

  프리셋 없음. 파일 직접 편집으로 커스터마이징.
  openclaw.json identity 블록 추가 시 Telegram 접두어/리액션에 반영.

 

9. 트러블슈팅 기록
================================================================================

  [이미지 없음] openclaw/agent:latest → Docker Hub에 없음
  → github.com/openclaw/openclaw 클론 후 openclaw:local 빌드

  [gateway token missing] 토큰 인증 비활성화 불가
  → 토큰 유지, URL에 ?token=<token> 파라미터 사용

  [pairing required] 디바이스 페어링 요구
  → gateway.controlUi.dangerouslyDisableDeviceAuth: true

  [trustedProxies CIDR 불가] 172.19.0.0/16 미작동
  → isTrustedProxyAddress()가 정확한 IP 매칭만 지원
  → 정확한 IP 지정: ["172.19.0.6", "172.19.0.8"]

  [auth-profiles.json 깨짐] alpine sh heredoc에서 따옴표 제거
  → base64 인코딩/디코딩으로 우회

  [.env 변경 미반영] docker compose restart는 환경변수 미갱신
  → docker compose up -d 사용

 

10. 유용한 CLI 명령어
================================================================================

  # 채널 상태 확인
  docker exec openclaw-gateway node dist/index.js channels status

  # 페어링 승인
  docker exec openclaw-gateway node dist/index.js pairing approve telegram <CODE> --notify

  # 에이전트 테스트
  docker exec openclaw-gateway node dist/index.js agent --message "hello" --local --agent main

  # 진단
  docker exec openclaw-gateway node dist/index.js doctor
  docker exec openclaw-gateway node dist/index.js doctor --fix

  # 세션 목록
  docker exec openclaw-gateway node dist/index.js sessions

  # 로그
  docker logs openclaw-gateway --tail 30