OpenClaw 설정 가이드 (2편) — Telegram 연동 + AI 모델 API 설정

- 3월 25, 2026

설정 파일 위치와 형식

OpenClaw의 모든 설정은 ~/.openclaw/openclaw.json 파일 하나에서 관리한다. JSON5 형식을 사용하므로 주석(//)을 추가할 수 있다. 게이트웨이는 이 파일을 감시하다가 변경이 감지되면 재시작 없이 자동으로 설정을 반영한다(Hot Reload).

설정 마법사를 사용하고 싶다면 아래 명령어로 대화형 설정을 진행할 수 있다.

openclaw configure

AI 모델 프로바이더 설정

OpenClaw는 Anthropic, OpenAI, Google 등 여러 AI 프로바이더를 지원한다. 사용할 모델은 provider/model-name 형식의 문자열로 지정한다.

API 키 등록

온보딩 이후 API 키를 변경하거나 추가하려면 CLI 명령어를 사용한다.

# Anthropic
openclaw config set auth.profiles.anthropic.apiKey YOUR_ANTHROPIC_API_KEY

# OpenAI
openclaw config set auth.profiles.openai.apiKey YOUR_OPENAI_API_KEY

API 키는 ~/.openclaw/credentials/ 디렉토리에 암호화되어 저장된다. openclaw.json에 평문으로 작성하는 것도 가능하지만 보안상 CLI 방식을 권장한다.

모델 선택

openclaw.json에서 기본 모델과 폴백 모델을 지정한다.

{
  "agents": {
    "defaults": {
      "model": {
        "primary": "anthropic/claude-haiku-4-5-20251001",
        "fallbacks": ["openai/gpt-4o-mini"]
      }
    }
  }
}

현재 설정된 모델 상태는 아래 명령어로 확인한다.

openclaw models list
openclaw models status

모델을 즉시 변경하려면 아래와 같이 입력한다.

openclaw models set anthropic/claude-sonnet-4-6

Telegram 봇 연동

Telegram은 OpenClaw에서 가장 많이 사용되는 채널이다. 연동을 위해서는 먼저 Telegram에서 봇을 생성해야 한다.

1단계: BotFather로 봇 생성

Telegram에서 @BotFather 를 검색해 대화를 시작한다
/newbot 명령어를 입력한다
봇 이름(표시 이름)과 username(영문, _bot으로 끝나야 함)을 순서대로 입력한다
생성 완료 후 BotFather가 봇 토큰을 발급한다 — 이 값을 안전하게 보관한다

발급된 토큰의 형식은 1234567890:AAxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx 형태다.

2단계: openclaw.json에 Telegram 설정 추가

{
  "channels": {
    "telegram": {
      "enabled": true,
      "botToken": "YOUR_TELEGRAM_BOT_TOKEN",
      "dmPolicy": "pairing",
      "groupPolicy": "allowlist",
      "streaming": "off"
    }
  }
}

3단계: 게이트웨이 시작 및 페어링

설정 저장 후 게이트웨이를 시작한다.

openclaw gateway

Telegram에서 봇에게 처음 메시지를 보내면 페어링 코드가 요청된다. 터미널에서 아래 명령어로 승인한다(코드 유효시간 1시간).

openclaw pairing approve telegram YOUR_PAIRING_CODE

페어링이 완료되면 이후 메시지는 바로 AI 에이전트가 처리한다.

그룹 채팅 설정

그룹에서 봇을 사용하려면 두 가지를 설정해야 한다.

Privacy Mode 비활성화: 기본적으로 Telegram 봇은 그룹에서 자신을 멘션한 메시지만 볼 수 있다. 모든 메시지를 처리하려면 BotFather에서 /setprivacy → 해당 봇 선택 → Disable로 설정한다. 변경 후 봇을 그룹에서 나갔다가 다시 추가해야 적용된다.

그룹 정책 설정: groupPolicy를 open으로 바꾸면 모든 그룹 멤버가 봇과 대화할 수 있다.

{
  "channels": {
    "telegram": {
      "groupPolicy": "open",
      "groups": {
        "*": { "requireMention": true }
      }
    }
  }
}

접근 제어 방식 비교

OpenClaw는 누가 봇과 대화할 수 있는지를 세밀하게 제어한다.

DM 정책 (dmPolicy)

pairing (기본값): 처음 대화하는 사용자는 페어링 코드 승인이 필요. 가장 안전한 방식
allowlist: 사전에 등록한 Telegram 사용자 ID만 대화 가능
open: 누구나 봇에게 DM 가능 (allowFrom: ["*"] 필요)
disabled: DM 완전 차단

그룹 정책 (groupPolicy)

allowlist (기본값): 설정된 그룹만 허용. 미설정 그룹은 차단
open: 봇이 추가된 모든 그룹에서 작동
disabled: 그룹 기능 완전 차단

세션 관리

여러 사용자가 동일한 봇을 사용할 경우 대화 컨텍스트를 분리할 수 있다.

{
  "session": {
    "dmScope": "per-channel-peer"
  }
}

per-channel-peer 설정은 사용자별로 독립된 대화 세션을 유지한다. 사용자 A의 대화 내용이 사용자 B에게 노출되지 않는다.

게이트웨이 기본 설정

게이트웨이의 포트, 인증 방식, 외부 접근 여부 등을 gateway섹션에서 관리한다.

{
  "gateway": {
    "port": 18789,
    "mode": "local",
    "bind": "loopback",
    "auth": {
      "mode": "token",
      "token": "YOUR_GATEWAY_TOKEN"
    }
  }
}

bind: "loopback" — 127.0.0.1에서만 접근 가능 (외부 차단). 외부 접근이 필요하면 "all"로 변경
mode: "local" — 로컬 전용 운용. VPS나 클라우드 환경에서는 "cloud"로 설정
게이트웨이 토큰은 웹 대시보드 접근 시 인증에 사용된다

자동화: 크론 작업 설정

에이전트가 정해진 시간에 자율적으로 작업을 수행하도록 크론을 설정할 수 있다.

{
  "agents": {
    "defaults": {
      "heartbeat": {
        "every": "1h"
      }
    }
  }
}

heartbeat는 설정된 주기마다 에이전트에게 신호를 보내 배치 작업, 상태 점검, 알림 전송 등을 수행하게 한다. ~/.openclaw/cron/ 디렉토리에 더 세밀한 크론 작업을 정의할 수도 있다.

설정 변경 적용 방법

OpenClaw는 openclaw.json 파일 변경을 실시간으로 감지해 대부분의 설정을 무중단으로 반영한다. 게이트웨이 포트 변경처럼 인프라 수준의 변경만 재시작이 필요하다.

# 강제 재시작이 필요한 경우
openclaw gateway restart

설정 변경 후 반영이 안 된다면 openclaw doctor로 진단하거나 게이트웨이를 재시작한다.

정리

두 편에 걸쳐 OpenClaw의 설치부터 Telegram 연동, AI 모델 설정, 접근 제어까지 다뤘다. 핵심을 정리하면 다음과 같다.

설치는 curl -fsSL https://openclaw.ai/install.sh | bash 한 줄로 끝난다
모든 설정은 ~/.openclaw/openclaw.json 파일 하나에서 관리된다
Telegram 봇은 BotFather에서 토큰을 발급받아 config에 등록하고 페어링으로 승인한다
API 키는 CLI 명령어로 등록하면 암호화되어 안전하게 저장된다
접근 제어는 dmPolicy와 groupPolicy로 세밀하게 조정할 수 있다

이 블로그 검색

multibagger