책에 포함된 노트오픈클로 OpenClaw: 메신저 안에서 일하는 나만의 AI 에이전트

부록 C. 한국어 환경 트러블슈팅 모음

2026-04-29Views 27약 10분생성형 AI 활용

부록 C. 한국어 환경 트러블슈팅 모음

OpenClaw를 한국어 환경에서 쓰다 보면, 이상하게도 모델보다 운영체제가 더 수수께끼처럼 느껴질 때가 있다. 분명 설치는 끝났는데 한글이 깨지고, 오전 9시 브리핑은 밤에 오고, 같은 컴퓨터인데 Windows와 WSL이 서로 남처럼 굴기도 한다. 이 부록은 그런 순간을 위한 응급상자다.

핵심부터 말하자. 한국 사용자 환경에서 자주 꼬이는 문제는 대개 네 갈래다. 문자 인코딩, 시간대, 로케일, 그리고 Windows와 WSL의 경계다. OpenClaw는 Windows 네이티브보다 WSL2를 더 안정적인 실행 환경으로 권장하므로, 처음부터 "리눅스처럼 다룬다"는 감각을 잡아두면 훨씬 덜 헤맨다.¹

부록 C 한국어 환경 트러블슈팅 모음

먼저 하는 1분 점검

뭔가 이상하다 싶으면 감으로 만지지 말고, 아래 순서대로 상태부터 확인하자.

locale
date
node -v
npm prefix -g
openclaw --version
openclaw status
openclaw gateway status
openclaw doctor

여기서 바로 보이는 것이 많다. locale은 한글 깨짐의 단서를 주고, date는 시간대 문제를 드러내며, npm prefix -g는 openclaw: command not found의 원인을 거의 바로 보여준다. openclaw doctor는 설치·설정·서비스 상태를 한 번에 짚어주는 가장 만만한 청진기다.²

한글이 깨질 때는 번역보다 UTF-8부터 의심하자

한글 환경 문제라고 해서 꼭 ko_KR이 정답인 것은 아니다. 중요한 것은 언어보다 인코딩이다. 즉, OpenClaw가 한국어를 잘 다루려면 최소한 터미널과 파일이 UTF-8로 맞아 있어야 한다.

증상은 대체로 비슷하다. 터미널에서 한글이 ???로 보이거나, ê°ëë¤처럼 깨지고, SKILL.md를 저장했더니 YAML frontmatter가 이상하게 읽힌다. 이런 경우는 거의 항상 파일 저장 인코딩, BOM, 줄바꿈 방식 중 하나다.

WSL Ubuntu에서 locale을 실행했을 때 UTF-8이 보이지 않으면 먼저 로케일을 바로잡자.

sudo apt update
sudo apt install -y locales
sudo locale-gen ko_KR.UTF-8
sudo update-locale LANG=ko_KR.UTF-8
exec bash

그래도 일부 도구가 로케일 때문에 까탈을 부리면, 화면 언어와 시스템 안정성을 잠시 분리해서 생각하는 편이 낫다. 그럴 때는 LANG=C.UTF-8로 돌려서 UTF-8만 확보하는 방식이 의외로 잘 먹힌다. 즉, 한국어 출력이 꼭 필요하지 않은 셸 작업이라면 "한국어 로케일"보다 "UTF-8 로케일"이 더 중요하다.

파일 편집기 쪽에서는 두 가지만 기억하면 된다. 저장 인코딩은 UTF-8, 줄바꿈은 LF다. 특히 Windows 편집기에서 만든 파일을 WSL에서 읽을 때 CRLF 때문에 스크립트나 frontmatter 파서가 삐끗하는 일이 잦다. VS Code를 쓴다면 상태 바에서 UTF-8, LF를 확인하고 저장하는 습관을 들이자.

BOM도 조용한 범인이다. 겉으로는 멀쩡해 보여도 파일 맨 앞에 붙은 BOM 때문에 첫 줄 파싱이 어긋날 수 있다. SKILL.md나 설정 파일은 가능하면 UTF-8 without BOM으로 저장하는 편이 안전하다.

이미 CRLF로 꼬인 파일이라면 WSL에서 이렇게 정리할 수 있다.

sudo apt install -y dos2unix
dos2unix SKILL.md
dos2unix ~/.openclaw/openclaw.json

시간대와 로케일은 전혀 다른 문제다

많이 헷갈리는 지점이 하나 있다. ko_KR.UTF-8은 언어와 문자 처리에 가깝고, Asia/Seoul은 시계 문제다. 둘은 친구일 수는 있어도 같은 사람이 아니다.

OpenClaw는 메시지를 모델에 넘길 때 타임스탬프를 표준화해서 보여주며, 기본적으로는 호스트의 로컬 시간대를 쓴다. 또 agents.defaults.userTimezone, envelopeTimezone, timeFormat으로 동작을 조정할 수 있다.³

한국에서 가장 덜 헷갈리는 설정은 대개 아래와 같다.

{
  "agents": {
    "defaults": {
      "userTimezone": "Asia/Seoul",
      "envelopeTimezone": "user",
      "timeFormat": "24"
    }
  }
}

이렇게 해두면 모델은 사용자의 기준 시간을 더 일관되게 이해한다. 특히 한국 사용자는 오전·오후보다 24시간제를 많이 쓰므로 timeFormat: "24"가 일정 처리에서 덜 헷갈린다.³

증상이 "분명 오늘 아침이라고 했는데 에이전트가 어제 밤 기준으로 말한다"라면, 아래 둘 중 하나일 가능성이 크다. 첫째, WSL 호스트의 시간대가 서울이 아니다. 둘째, OpenClaw 설정에서 사용자 시간대를 명시하지 않았다. 이때는 시스템 시간을 억지로 손보기 전에, 먼저 OpenClaw에 Asia/Seoul을 분명히 알려주는 것이 더 안전하다.

WSL에서 현재 시간대와 시간을 확인하려면 이렇게 본다.

date
timedatectl
cat /etc/timezone

timedatectl이 제대로 동작하려면 WSL에서 systemd가 켜져 있어야 한다. OpenClaw가 WSL2에서 데몬 형태로 안정적으로 돌기 위해서도 systemd 활성화는 사실상 필수다.¹

오전 9시 브리핑이 밤에 오는 이유

HEARTBEAT나 cron 자동화를 써보기 시작하면 시간대 문제는 더 노골적으로 드러난다. 한국 사용자가 가장 자주 겪는 실수는 "호스트 시간은 다른 나라 기준인데, 프롬프트에는 한국 시간으로 이해하길 기대하는 것"이다.

OpenClaw 문서 기준으로 Heartbeat의 활성 시간대와 cron 스케줄은 시간대 설정의 영향을 받는다.³ 따라서 매일 오전 9시 브리핑이 정확히 오전 9시에 오게 하려면, 단순히 프롬프트에 "한국 시간으로"라고 적는 것만으로는 부족하다. 설정 자체가 한국 시간을 가리켜야 한다.

문제가 반복되면 이렇게 정리하자.

첫째, 호스트의 현재 시간을 date로 확인한다. 둘째, OpenClaw 설정에 userTimezone: "Asia/Seoul"를 넣는다. 셋째, 메시지 봉투 기준도 envelopeTimezone: "user"로 맞춘다. 넷째, 테스트용으로 5분 뒤에 한 번 울리는 짧은 작업을 만들어 실제 시각이 맞는지 확인한다.

이 순서를 지키면 "모델은 한국인인데 시계는 샌프란시스코 사람" 같은 괴상한 상황을 줄일 수 있다.

WSL과 Windows는 같은 집에 사는 다른 세대라고 생각하자

한국 사용자에게 가장 많은 삽질을 안기는 것은 사실 인코딩보다 경계다. 같은 노트북 안에 있지만, Windows와 WSL은 파일 경로도 다르고 서비스 방식도 다르며, 네트워크도 완전히 한 몸처럼 움직이지 않는다.

OpenClaw 공식 설치 가이드는 Windows에서도 네이티브 PowerShell 방식보다 WSL2를 더 안정적인 경로로 본다. 특히 백그라운드 Gateway를 쓰려면 WSL의 systemd 활성화가 중요하다.¹

WSL에서 아직 systemd를 켜지 않았다면 아래를 먼저 끝내자.

sudo tee /etc/wsl.conf >/dev/null <<'EOF'
[boot]
systemd=true
EOF

그리고 PowerShell에서 WSL을 완전히 내렸다가 다시 올린다.

wsl --shutdown

이 과정을 건너뛰면 openclaw onboard --install-daemon이 어설프게 끝나거나, 서비스 상태가 묘하게 불안정해질 수 있다.¹

또 하나, 경로 감각을 분리해야 한다. WSL 안의 홈 디렉터리와 Windows의 C:Users...는 이름만 비슷할 뿐 사용감이 다르다. 에이전트 워크스페이스와 설정 파일은 가능하면 WSL 내부 홈 디렉터리 아래에 두는 편이 낫다. Windows 쪽 /mnt/c/...에서 직접 작업하면 권한, 속도, 줄바꿈 문제가 한꺼번에 끼어드는 경우가 있다.

`openclaw` 명령어가 갑자기 사라졌을 때

설치는 끝났는데 새 터미널을 열자마자 openclaw: command not found가 뜨는 일은 꽤 흔하다. 대개 npm 글로벌 bin 경로가 PATH에 없어서 그렇다.

macOS, Linux, WSL에서는 아래 방식이 정석이다.²

npm prefix -g
echo "$PATH"
export PATH="$(npm prefix -g)/bin:$PATH"

이 줄을 ~/.bashrc 또는 ~/.zshrc에 넣고 새 터미널을 열면 된다.²

Windows PowerShell 네이티브 설치라면 개념이 조금 다르다. 그 경우에는 npm config get prefix 결과값, 보통 %AppData%npm 계열 경로를 PATH에 넣어야 한다.¹

즉, WSL에서는 보통 .../bin까지 포함해서 넣고, Windows는 글로벌 prefix 경로 자체를 PATH에 넣는다고 기억하면 덜 헷갈린다.¹²

붙여넣기 하나로 막히는 터미널 문제

한국어 환경에서는 이상하게 복붙이 설치 실패의 진짜 원인인 경우도 많다. 특히 Ubuntu on WSL 터미널에서 Ctrl+V가 안 먹는다고 토큰을 다시 발급받는 분들이 있다. 사실 토큰은 멀쩡하고, 터미널 붙여넣기 키가 다른 것뿐이다.

Windows Terminal이나 VS Code 터미널에서는 보통 Ctrl+Shift+V 또는 마우스 오른쪽 클릭 붙여넣기가 더 잘 작동한다. 비밀번호 입력 중에는 글자가 안 보이는 것도 정상이다. 입력이 안 된 것이 아니라 보안 때문에 숨겨진 것이다.

토큰 입력 전후로 공백이 섞이는 것도 흔한 실수다. 한국어 IME가 켜진 상태에서 붙여넣다가 앞뒤에 공백이나 줄바꿈이 들어가면 인증이 실패할 수 있다. 토큰은 붙여넣은 뒤 한 번 더 왼쪽·오른쪽으로 커서를 움직여 길이를 확인하는 습관이 좋다.

브라우저는 Windows, Gateway는 WSL일 때 생기는 미묘한 함정

이른바 split-host 구성이다. OpenClaw Gateway는 WSL 안에서 돌고, Chrome은 Windows에서 돌며, 사용자는 Windows 브라우저로 대시보드를 열고 싶어 한다. 이 조합은 충분히 가능하지만, 한 층씩 확인하지 않으면 문제 원인이 자꾸 바뀐 얼굴로 나타난다.⁴

핵심 규칙은 단순하다. Control UI는 Windows에서 열더라도 가능하면 http://127.0.0.1:18789/로 접속한다. 괜히 LAN IP로 열면 insecure origin, 인증, CDP 문제처럼 전혀 다른 에러가 튀어나올 수 있다.⁴

또 Windows Chrome의 원격 디버깅 포트를 WSL에서 붙이려면, "Windows에서 되는 주소"가 아니라 "WSL에서 실제로 닿는 주소"를 써야 한다. 먼저 Windows에서 /json/version이 열리는지 보고, 그다음 WSL에서 같은 주소가 열리는지 검증한 뒤에 OpenClaw 브라우저 프로파일을 만지는 순서가 맞다.⁴

즉, 브라우저 제어가 안 될 때 곧바로 OpenClaw 설정을 의심하기보다, 먼저 네트워크 경계부터 확인해야 한다. 같은 노트북 안이라고 자동으로 통하는 것이 아니다.

Tailscale로 외부에서 붙을 때 WSL이 말썽이면

한국 사용자 중에는 집 PC의 WSL에서 OpenClaw를 돌리고, 밖에서는 휴대폰이나 다른 노트북으로 붙고 싶어 하는 경우가 많다. 이때 WSL 안에서 직접 Tailscale을 다루려다 꼬이는 일이 자주 생긴다.

실전에서는 Windows 쪽 Tailscale Serve가 TLS를 처리하고, WSL의 OpenClaw는 HTTP만 맡도록 역할을 나누는 편이 안정적이다. 이 구성에서는 OpenClaw Gateway를 WSL에서 bind: "lan"으로 열고, trustedProxies에 127.0.0.1을 넣어 Windows 프록시를 신뢰하게 만든다.⁵

대표적인 증상은 세 가지다.

Proxy headers detected from untrusted address
pairing-required
Connection refused

첫 번째는 trustedProxies가 빠졌을 가능성이 높고, 두 번째는 Control UI의 Nodes 화면에서 승인 절차가 남아 있을 가능성이 크며, 세 번째는 WSL에서 Gateway가 실제로 떠 있는지와 Windows의 Tailscale Serve 상태를 함께 봐야 한다.⁵

WSL은 재시작할 때 IP가 바뀔 수 있으므로, Tailscale 구성이 어제는 됐는데 오늘 안 된다면 이상 현상이 아니라 구조적인 특성일 수 있다. 이럴 때는 OpenClaw보다 먼저 WSL IP와 Serve 상태를 다시 확인하는 편이 빠르다.⁵

한국어 파일명, 공백 경로, Windows 편집기의 조합이 위험한 이유

한글 파일명 자체는 요즘 큰 문제가 아니다. 진짜 문제는 한글 파일명에 공백이 섞이고, 그 파일을 Windows 편집기에서 저장한 뒤, WSL 셸에서 따옴표 없이 다루는 순간 시작된다.

예를 들어 주간 보고서 최종.md 같은 파일은 WSL에서 명령어 인자로 쓸 때 반드시 따옴표로 감싸는 편이 안전하다.

cat "주간 보고서 최종.md"

경로도 마찬가지다. /mnt/c/Users/.../내 문서/... 같은 경로는 공백과 한글, Windows 권한, CRLF까지 한꺼번에 등장하기 쉽다. 그래서 자동화 대상 파일은 가능하면 WSL 홈 아래의 단순한 영문 경로로 옮겨두는 편이 덜 피곤하다. 한글은 콘텐츠에 쓰고, 경로는 최대한 단순화하는 것이 운영에서 이긴다.

이상할 때 가장 잘 먹히는 복구 순서

OpenClaw 공식 문제 해결 문서는 아주 좋은 습관을 하나 알려준다. 막히면 무조건 아래 순서대로 보라는 것이다.⁶

openclaw status
openclaw status --all
openclaw gateway probe
openclaw gateway status
openclaw doctor
openclaw channels status --probe
openclaw logs --follow

이 순서가 좋은 이유는, 문제를 "모델 문제"로 뭉뚱그리지 않고 계층별로 쪼개 주기 때문이다. 설정 문제인지, Gateway 문제인지, 채널 문제인지, 로그에 반복되는 치명적 오류가 있는지 차례대로 보이기 시작한다.⁶

여기에 한국어 환경 체크를 하나만 더 얹으면 거의 완성이다.