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

OpenClaw 다국어 및 현지화 설정 튜토리얼

· 14 분 소요

들어가며

OpenClaw는 전 세계적으로 널리 사용되며, 다국어 지원은 핵심 기능 중 하나입니다. 사용자가 중국어, 영어, 일본어 또는 다른 언어를 사용하든 OpenClaw는 유연하게 대응할 수 있습니다. 본 문서에서는 응답 언어, 인터페이스 언어, 채널별 언어 설정 방법과 자동 감지 기능을 활용하여 사용자 언어를 지능적으로 매칭하는 방법을 상세히 안내합니다.

언어 설정 개요

OpenClaw의 언어 설정은 세 가지 계층으로 구성됩니다.

계층 설명 구성 위치
AI 응답 언어 AI가 어떤 언어로 사용자에게 응답하는지 persona.language
Dashboard 인터페이스 언어 관리 패널의 인터페이스 언어 gateway.locale
시스템 로그 언어 실행 로그의 언어 logging.locale

기본 언어 설정

전역 응답 언어 설정

openclaw.json5에서 구성합니다.

{
  persona: {
    language: "zh-CN",  // 간체 중국어
  },
}

지원되는 언어 코드

언어 코드 언어 설명
zh-CN 간체 중국어 중국 대륙
zh-TW 번체 중국어 대만 지역
en 영어 국제 공용
ja 일본어 일본
ko 한국어 한국
fr 프랑스어 프랑스 등 지역
de 독일어 독일 등 지역
es 스페인어 스페인, 중남미
pt 포르투갈어 포르투갈, 브라질
ru 러시아어 러시아
ar 아랍어 중동 지역
auto 자동 감지 사용자 입력에 따라 자동 판단

자동 언어 감지

언어를 auto로 설정하면 OpenClaw가 사용자 입력 언어를 자동으로 감지하고 같은 언어로 응답합니다.

{
  persona: {
    language: "auto",

    // 자동 감지 상세 구성
    languageDetection: {
      // 자동 감지 활성화
      enabled: true,

      // 감지 불가 시 사용하는 기본 언어
      fallbackLanguage: "zh-CN",

      // 감지 신뢰도 임계값 (0-1)
      confidenceThreshold: 0.7,

      // 사용자 언어 선호도 기억 여부
      rememberPreference: true,
    },
  },
}

자동 감지 동작 원리

사용자가 메시지 전송
    ├─ 메시지 텍스트 분석
    ├─ 언어 종류 및 신뢰도 판단
    │   ├─ 신뢰도 > 임계값 → 감지된 언어 사용
    │   └─ 신뢰도 < 임계값 → 기본 언어 사용
    ├─ rememberPreference=true인 경우
    │   └─ 해당 사용자의 언어 선호도 기록
    └─ 매칭된 언어로 응답 생성

실제 효과 예시

language: "auto" 설정 시:

  • 사용자가 "你好" 전송 → AI가 중국어로 응답
  • 사용자가 "Hello" 전송 → AI가 영어로 응답
  • 사용자가 "こんにちは" 전송 → AI가 일본어로 응답
  • 사용자가 혼합 언어 전송 → 비중이 가장 높은 언어로 응답

채널별 언어 설정

서로 다른 통신 채널이 서로 다른 언어의 사용자 그룹에 서비스할 수 있습니다. OpenClaw는 각 채널별로 독립적인 언어 구성을 지원합니다.

{
  persona: {
    // 전역 기본 언어
    language: "zh-CN",

    // 채널별 덮어쓰기
    channelOverrides: {
      // Telegram 중국어 그룹 — 간체 중국어
      telegram: {
        language: "zh-CN",
      },

      // Discord 국제 커뮤니티 — 자동 감지
      discord: {
        language: "auto",
        languageDetection: {
          fallbackLanguage: "en",
        },
      },

      // Slack 일본 팀 — 일본어
      slack: {
        language: "ja",
      },

      // WhatsApp 고객 서비스 — 자동 감지, 기본 중국어
      whatsapp: {
        language: "auto",
        languageDetection: {
          fallbackLanguage: "zh-CN",
          rememberPreference: true,
        },
      },

      // LINE — 번체 중국어
      line: {
        language: "zh-TW",
      },
    },
  },
}

시스템 프롬프트와 함께 사용

언어 설정은 시스템 프롬프트와 결합하여 AI의 응답 언어와 스타일을 일관되게 유지할 수 있습니다.

{
  persona: {
    language: "zh-CN",
    systemPrompt: "당신은 지니라는 친근한 중국어 AI 어시스턴트입니다. 항상 간체 중국어로 응답하고 자연스러운 중국어 표현을 사용하며 영어 어휘의 과도한 사용은 피합니다.",

    channelOverrides: {
      discord: {
        language: "en",
        systemPrompt: "You are Claw, a helpful English-speaking AI assistant. Always respond in natural, conversational English.",
      },
    },
  },
}

다국어 시스템 프롬프트 템플릿

AI 어시스턴트가 여러 언어를 처리해야 하는 경우 프롬프트에서 명확히 안내할 수 있습니다.

{
  persona: {
    language: "auto",
    systemPrompt: `당신은 다국어 AI 어시스턴트입니다.

## 언어 규칙
1. 항상 사용자와 같은 언어로 응답
2. 사용자가 중영 혼합을 사용하면 중국어 응답 우선
3. 전문 용어는 원문 유지, 괄호 안에 중국어 설명 첨부
4. 코드 주석은 영어 사용

## 각 언어 스타일
- 중문：简洁的口语化表达
- English: Use clear and concise language
- 日本語：丁寧語を使用してください`,
  },
}

Dashboard 인터페이스 언어

OpenClaw 관리 패널은 여러 인터페이스 언어를 지원합니다.

{
  gateway: {
    // Dashboard 인터페이스 언어
    locale: "zh-CN",

    // 선택 가능: zh-CN, zh-TW, en, ja, ko, fr, de, es
  },
}

수정 후 OpenClaw를 재시작하면 적용됩니다.

openclaw restart

http://localhost:18789/dashboard에 접속하여 효과를 확인합니다.

시스템 로그 언어

시스템 로그는 기본적으로 영어를 사용하며, 다른 언어로 전환할 수도 있습니다.

{
  logging: {
    // 로그 언어
    locale: "zh-CN",

    // 중국어로 설정한 후의 로그 출력 예시:
    // [정보] 게이트웨이 시작됨, 포트: 18789
    // [정보] 모델 제공업체: Claude (claude-sonnet-4-20250514)
    // [정보] 채널 준비 완료
  },
}

개발 디버그 시에는 이해하기 쉬운 중국어 로그를 사용하고, 프로덕션 환경에서는 검색과 문제 해결에 편리한 영어 로그를 사용하는 것을 권장합니다.

사용자 수동 언어 전환

사용자는 채팅에서 명령어를 통해 언어를 전환할 수 있습니다.

/lang zh-CN    → 간체 중국어로 전환
/lang en       → Switch to English
/lang ja       → 日本語に切り替える
/lang auto     → 자동 감지 활성화
/lang list     → 지원되는 언어 보기

전환 후 즉시 적용되며, 이후 대화는 모두 새로운 언어를 사용합니다.

번역 보조 기능

OpenClaw에는 응답에 번역을 첨부할 수 있는 번역 보조 기능이 내장되어 있습니다.

{
  persona: {
    language: "zh-CN",

    // 번역 보조
    translation: {
      // 이중 언어 응답 활성화 여부
      bilingual: false,

      // 이중 언어 응답의 두 번째 언어
      secondLanguage: "en",

      // 이중 언어 응답 형식
      format: "parallel",  // parallel(병렬), footnote(각주)

      // 명령어로 번역 트리거
      commandEnabled: true,  // 사용자가 /translate 명령어로 번역 가능
    },
  },
}

이중 언어 응답 효과

bilingual: true이고 format: "parallel"인 경우:

사용자: 오늘 날씨 어때?

AI:
오늘은 맑고 기온은 약 25도로 외출 활동에 적합합니다.

Today is sunny with a temperature of about 25°C, perfect for outdoor activities.

format: "footnote"인 경우:

사용자: 오늘 날씨 어때?

AI:
오늘은 맑고 기온은 약 25도로 외출 활동에 적합합니다.
[EN] Today is sunny with a temperature of about 25°C.

현지화 구성 모범 사례

중국어 사용자를 위한 최적화

{
  persona: {
    language: "zh-CN",
    systemPrompt: `당신은 중국어 사용자를 위한 AI 어시스턴트입니다.

## 중국어 응답 규범
- 간체 중국어 사용
- 숫자는 아라비아 숫자 사용
- 날짜 형식: YYYY년 MM월 DD일
- 시간 형식: HH:MM (24시간제)
- 통화 형식: ¥100.00
- 중국어 문장부호 사용 (，。！？)
- 단락 사이에 한 줄 띄우기
- 기술 용어는 영어 원문 유지 가능`,
  },
}

다지역 중국어 사용자 대응

{
  persona: {
    language: "auto",
    languageDetection: {
      // 간체/번체 구분
      distinguishVariants: true,
      fallbackLanguage: "zh-CN",
    },

    // 간체/번체 변환
    chineseVariant: {
      // auto: 사용자 입력에 자동 매칭
      // simplified: 항상 간체 사용
      // traditional: 항상 번체 사용
      mode: "auto",
    },
  },
}

다국어 그룹 채팅 처리

다국어 그룹 채팅(예: 국제 Discord 서버)에서는 다음 구성을 권장합니다.

{
  persona: {
    language: "auto",
    languageDetection: {
      enabled: true,
      fallbackLanguage: "en",
      confidenceThreshold: 0.8,
      rememberPreference: true,
    },

    systemPrompt: `You are a multilingual AI assistant in an international community.

## Language Rules
- Detect and respond in the same language as the user
- If unsure, respond in English
- For mixed-language messages, use the predominant language
- Always be respectful of cultural differences
- Use culturally appropriate expressions`,
  },
}

전체 다국어 구성 예제

다음은 일반적인 시나리오를 포괄하는 완전한 다국어 구성입니다.

{
  gateway: {
    port: 18789,
    locale: "zh-CN",
  },

  persona: {
    name: "지니",
    language: "auto",

    languageDetection: {
      enabled: true,
      fallbackLanguage: "zh-CN",
      confidenceThreshold: 0.7,
      rememberPreference: true,
    },

    systemPrompt: "당신은 지니라는 다국어 AI 어시스턴트입니다. 사용자와 같은 언어로 응답하며 친근하고 전문적인 태도를 유지합니다.",

    channelOverrides: {
      telegram: {
        language: "zh-CN",
        name: "지니",
      },
      discord: {
        language: "auto",
        name: "Claw",
        languageDetection: {
          fallbackLanguage: "en",
        },
      },
      slack: {
        language: "zh-CN",
        name: "업무 어시스턴트",
      },
      line: {
        language: "zh-TW",
        name: "지니",
      },
    },

    translation: {
      bilingual: false,
      commandEnabled: true,
    },
  },

  logging: {
    locale: "en",
    level: "info",
  },
}

언어 설정 검증

구성 완료 후 언어 설정이 적용되었는지 확인합니다.

# OpenClaw 재시작
openclaw restart

# 구성 점검
openclaw doctor

# Dashboard 인터페이스 언어가 변경되었는지 확인
# http://localhost:18789/dashboard 접속

그런 다음 각 채널에서 다른 언어로 테스트 메시지를 보내 응답 언어가 올바른지 확인합니다.

마무리

OpenClaw의 다국어 지원을 통해 하나의 시스템으로 전 세계 사용자에게 서비스를 제공할 수 있습니다. 자동 언어 감지 기능으로 AI 어시스턴트가 사용자의 언어를 지능적으로 매칭할 수 있으며, 채널별 언어 구성으로 각 사용자 그룹에게 현지화된 경험을 제공할 수 있습니다. 대부분의 사용자에게는 auto 모드와 적절한 fallbackLanguage를 함께 사용하는 것을 권장합니다. 이렇게 하면 유연하면서도 안정적입니다. 특정 언어 시나리오(예: 고객 서비스)에서는 고정 언어를 직접 지정하여 일관성을 보장하십시오.

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

관련 튜토리얼

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