OpenClaw 기초 세팅

GitHub - openclaw/openclaw: Your own personal AI assistant. Any OS. Any Platform. The lobster way. 🦞

전체흐름

Info

1. 사전 준비 (Node.js, PowerShell 설정)

2. OpenClaw 설치

3. PATH 설정 (핵심 - 반드시 GUI 또는 PowerShell로)

4. PATH 유실 복구 (setx 사고 시)

5. 온보딩 마법사 실행

6. Ollama 연동 (로컬/클라우드 모델)

7. ChatGPT 구독 연동 (Codex CLI 인증, 권장)

8. 메신저 채널 연동 - 텔레그램

9. 메신저 채널 연동 - 디스코드

10. 게이트웨이 시작 및 확인

11. 워크스페이스 커스터마이징

2026년 3월 14일 기준 문서

OpenClaw(구 클로드봇/몰트봇)는 로컬 머신에서 실행되는 오픈소스 AI 에이전트다. 텔레그램, WhatsApp, Discord 등 메신저로 명령을 보내면 파일 조작, 메일 발송, 코드 실행, 일정 관리 등을 대신 수행한다

들어가기에 앞서서

대부분의 경로는 설치시 바로 설치되는 권장 설치로 한다

<UserName>의 경우에는 일반적으로 설치되는 사용자명(경로)이다.

1. 사전 준비

1단계: WSL2 및 Ubuntu 24.04 설치

관리자 권한으로 PowerShell을 실행한 뒤 아래 명령어를 입력한다.

wsl --update
wsl --install -d Ubuntu-24.04

설치 완료 후 반드시 재부팅한다. 재부팅 후 Ubuntu 터미널이 열리면 사용자 이름과 비밀번호를 설정한다.

자동으로 열리지 않는 경우:

wsl -d Ubuntu-24.04

트러블슈팅: WSL_E_DISTRO_NOT_FOUND 에러

WSL 기능이 처음 활성화되는 과정에서 발생할 수 있다.

wsl --update
wsl --list --online
wsl --install -d Ubuntu-24.04

2단계: systemd 활성화

Ubuntu 터미널에서 실행한다.

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

PowerShell에서 WSL 종료 후 재시작한다.

wsl --shutdown

1.1 Node.js 22 이상 설치

OpenClaw는 Node.js 22 이상이 필요하다.

아직 없다면 공식 사이트에서 LTS 버전을 받는다.

다운로드: https://nodejs.org
"Recommended For Most Users" 버전 선택
설치 마법사에서 기본값으로 진행

설치 확인:

node --version
# v22.x.x 이상이면 정상

OpenClaw 설치 스크립트가 Node.js를 자동 감지하고 없으면 설치를 시도하지만, 미리 설치해두는 것이 오류를 줄인다.

1.2 Git 설치 (권장)

일부 npm 패키지가 GitHub에서 소스를 내려받을 때 Git이 필요하다.

다운로드: https://git-scm.com
설치 마법사에서 기본값으로 진행

1.3 CMD vs PowerShell 구분

Windows에서 터미널을 열 때 CMD(명령 프롬프트)와 PowerShell은 다른 환경이다. OpenClaw 설치 스크립트는 PowerShell 전용이므로 반드시 PowerShell에서 실행해야 한다.

구분법:

CMD 프롬프트: C:\Users\<UserName>>
PowerShell 프롬프트: PS C:\Users\<UserName>>

CMD에서 PowerShell로 전환하려면 powershell을 입력한다.

1.4 PowerShell 실행 정책 확인

Windows의 기본 실행 정책이 스크립트 실행을 차단할 수 있다. PowerShell을 관리자 모드로 열고 실행 정책을 변경한다:

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

확인 메시지가 뜨면 Y를 입력한다.

2. OpenClaw 설치

PowerShell을 관리자 모드로 열고 설치 스크립트를 실행한다:

iwr -useb https://openclaw.ai/install.ps1 | iex

이 스크립트가 수행하는 작업:

- Node.js 버전 확인
- npm으로 OpenClaw CLI를 글로벌 설치
- 초기 설정 디렉토리 생성 (~/.openclaw/)
- 온보딩 마법사 실행

3. PATH 설정 (핵심)

OpenClaw를 설치해도 openclaw 명령이 인식되지 않는 경우가 대부분이다. npm 글로벌 바이너리 경로가 사용자 PATH에 등록되어 있지 않기 때문이다.

3.1 문제 확인

C:\Users\<UserName>>openclaw --version
'openclaw'은(는) 내부 또는 외부 명령, 실행할 수 있는 프로그램, 또는
배치 파일이 아닙니다.

3.2 바이너리 존재 확인

먼저 설치 자체가 됐는지 확인한다:

npm prefix -g
# 출력 예: C:\Users\<UserName>\AppData\Roaming\npm

dir "C:\Users\<UserName>\AppData\Roaming\npm\openclaw*"
# openclaw, openclaw.cmd, openclaw.ps1 파일이 있으면 설치는 완료된 상태

직접 경로 지정으로 동작 확인:

"C:\Users\<UserName>\AppData\Roaming\npm\openclaw.cmd" --version
# 버전이 출력되면 바이너리는 정상

3.3 PATH 추가 방법 (2가지)

방법 A: GUI (sysdm.cpl) - 가장 안전

Win + R 누르고 sysdm.cpl 입력 후 엔터
고급 탭 클릭
환경 변수 버튼 클릭
위쪽 사용자 변수 섹션에서 Path를 선택하고 편집
새로 만들기 클릭
C:\Users\<UserName>\AppData\Roaming\npm 입력
확인 -> 확인 -> 확인
CMD/PowerShell 창을 완전히 닫고 새로 열어야 반영된다

방법 B: PowerShell - 기존 값에 안전하게 추가

$current = [Environment]::GetEnvironmentVariable("PATH", "User")
[Environment]::SetEnvironmentVariable("PATH", "$current;C:\Users\<UserName>\AppData\Roaming\npm", "User")

경고: CMD에서 setx PATH를 절대 사용하지 말 것.

setx PATH "%PATH%;새경로" 명령은 사용자 PATH + 시스템 PATH를 합쳐서 사용자 PATH에 덮어쓰는데, 1024자 제한으로 내용이 잘린다. 이렇게 되면 기존에 등록되어 있던 Ollama, Go, Python 등의 경로가 유실된다.

실제 사례:
C:\Windows\System32>setx PATH "%PATH%;C:\Users\<UserName>\AppData\Roaming\npm"
경고: 저장하는 데이터를 1024문자로 잘라냅니다.
성공: 지정한 값을 저장했습니다.
이후 ollama 명령이 인식되지 않는 상황이 발생한다. 자세한 복구 방법은 4절 참고.

3.4 확인

새 터미널에서:

openclaw --version
ollama --version

둘 다 정상 동작하면 PATH 설정 완료다.

4. PATH 유실 복구 (setx 사고 발생 시)

setx PATH를 실수로 실행하여 기존 경로가 날아간 경우의 복구 방법이다.

4.1 setx가 PATH를 파괴하는 메커니즘

Windows 환경변수 PATH는 두 종류가 있다:

최종 PATH = 시스템 PATH + 사용자 PATH

CMD에서 %PATH%를 참조하면 이 합쳐진 값이 나온다. setx PATH "%PATH%;새경로"를 실행하면:

합쳐진 전체 PATH(수천 자)를 사용자 PATH에 넣으려고 시도
시스템 PATH 내용이 사용자 PATH에 중복 복사됨
1024자 제한으로 뒷부분 잘림
Ollama, Rancher Desktop 등 뒤쪽에 있던 경로 소실

4.2 현재 상태 진단

PowerShell에서 사용자 PATH와 시스템 PATH를 분리해서 확인한다:

Write-Host "=== USER PATH ==="
[Environment]::GetEnvironmentVariable("PATH", "User")
Write-Host ""
Write-Host "=== SYSTEM PATH ==="
[Environment]::GetEnvironmentVariable("PATH", "Machine")

setx는 사용자 PATH만 덮어쓴다. 시스템 PATH는 무사할 가능성이 높다. 사용자 PATH에 시스템 PATH 전체가 중복 복사되어 들어가고, 1024자 잘림으로 뒷부분(Ollama 등)이 소실된 상태일 것이다.

4.3 유실된 경로 찾기

Ollama 등 인식 안 되는 프로그램의 실제 위치를 찾는다:

where /R "C:\Users\<UserName>" ollama.exe
# 출력 예: C:\Users\<UserName>\AppData\Local\Programs\Ollama\ollama.exe

4.4 사용자 PATH 리셋

시스템 PATH에 이미 Git, Python, Go, Node, Windows 기본 경로 등이 들어있으므로 사용자 PATH에는 사용자가 직접 설치한 프로그램 경로만 남기면 된다.

PowerShell에서:

[Environment]::SetEnvironmentVariable("PATH", "C:\Users\<UserName>\AppData\Local\Programs\Ollama;C:\Users\<UserName>\AppData\Roaming\npm", "User")

필요에 따라 다른 사용자 프로그램 경로도 세미콜론으로 구분하여 추가한다.

4.5 확인

CMD/PowerShell을 완전히 닫고 새로 열어서:

ollama --version
openclaw --version

둘 다 인식되면 복구 완료다.

4.6 교훈

방법	안전성	비고
`setx PATH` (CMD)	위험	1024자 잘림, 시스템+사용자 PATH 혼합
`sysdm.cpl` (GUI)	안전	사용자/시스템 PATH를 분리해서 편집
`[Environment]::SetEnvironmentVariable()` (PowerShell)	안전	사용자 PATH만 정확히 조작 가능

PATH 추가는 항상 GUI 또는 PowerShell로 한다. setx PATH는 사용하지 않는다.

5. 온보딩 마법사

설치 스크립트가 자동으로 온보딩을 시작한다. 건너뛴 경우 수동 실행:

openclaw onboard --install-daemon

마법사에서 설정하는 항목:

순서	항목	설명
1	모델 프로바이더	Ollama, Anthropic, OpenAI, Google 등 선택
2	API 키 또는 인증	선택한 프로바이더에 맞는 인증 정보 입력
3	메신저 채널	Telegram, WhatsApp, Discord 등 연동할 채널 선택
4	스킬	번들 스킬 설치 여부 (나중에 추가 가능, Skip 가능)
5	Hook / Webhook	필요 없으면 Skip

Yes를 눌러서 진행한다.

이후 모델명이 뜰텐데 어떤 AI를 쓰냐에 따라서 다르다.

API의 경우 비용이 생각보다 많기때문에 개인적인 추천은 Open AI의 구독제와 연동하거나, 로컬 LLM과 연동하는 것이다.

Ollama란?

Ollama는 로컬컴퓨터에서 대형 언어 모델(LLM)을 쉽게 실행하고 사용할 수 있게 도와주는 오픈소스 플랫폼
DeepSeek나 LLaMA 같은 모델을 별도의 복잡한 설정 없이 간단한 명령어로 실행하고 API처럼 사용할 수 있게 해준다

6. Ollama 연동

Ollama의 버전 0.17 이후 오픈클로와 연동할 수 있는데, 여기선 Ollmama가 이미 Windows에 설치되어 있는 상태를 가정한다.

6.1 ollama launch 명령

OpenClaw 설치와 PATH 설정이 완료되었으므로 이제 정상 동작한다:

ollama launch openclaw

여기서 모델을 선택하는데, 필자는 gpt-oss 20b 모델을 선택하겠다.

정상 실행 시 출력 예:

This will modify your OpenClaw configuration:
  C:\Users\<Username>\.openclaw\openclaw.json
Backups will be saved to C:\Users\<Username>\AppData\Local\Temp\ollama-backups/
Added gpt-oss:20b to OpenClaw
Launching OpenClaw with gpt-oss:20b...

Ollama가 처리하는 작업:

기존 설정 백업
모델 선택 화면 표시
선택한 모델을 OpenClaw 설정에 자동 등록
게이트웨이 시작
TUI(Text User Interface) 콘솔 실행

6.2 모델 선택 기준

OpenClaw는 최소 64K 토큰의 컨텍스트 윈도우를 권장한다.

Ollama Cloud 모델 (권장, 무료 티어 제공):

모델	특징
gpt-oss:20b	범용, 기본 선택
Kimi-K2.5	비용 효율

로컬 모델 (VRAM에 따라 선택):

모델	VRAM	용도
qwen3:8b	8GB	가벼운 질의응답
qwen2.5-coder:32b	24GB	코딩 특화, tool calling 지원
deepseek-r1:32b	24GB	추론 특화
glm-4.7-flash	25GB	추론 + 코드 생성

6.3 설정만 변경하고 게이트웨이를 시작하지 않으려면

ollama launch openclaw --config

6.4 수동으로 모델 변경

게이트웨이가 이미 실행 중일 때 모델을 바꾸려면:

openclaw models set ollama/qwen2.5-coder:32b

또는 설정 파일을 직접 수정:

notepad %USERPROFILE%\.openclaw\openclaw.json

설정 예시 (openclaw.json 내 models 섹션):

{
  "models": {
    "providers": {
      "ollama": {
        "baseUrl": "http://localhost:11434/v1",
        "apiKey": "ollama-local",
        "api": "openai-completions",
        "models": [
          {
            "id": "gpt-oss:20b",
            "name": "gpt-oss:20b",
            "reasoning": false,
            "input": ["text"],
            "cost": {
              "input": 0,
              "output": 0,
              "cacheRead": 0,
              "cacheWrite": 0
            },
            "contextWindow": 131072,
            "maxTokens": 8192
          }
        ]
      }
    }
  },
  "agents": {
    "defaults": {
      "model": {
        "primary": "ollama/gpt-oss:20b"
      }
    }
  }
}

설정 파일 수정 후 게이트웨이 재시작:

openclaw gateway restart

이후, 웹 대시보드를 통하여 체크해본다.

대시보드는 기본적으로 http://127.0.0.1:18789/ 에서 접근 가능하다.

7. GPT 연동 CLI 연동

OPENAI를 클릭 후 OAuth를 하게 된다면 GPT 구독과 연동하거나 OPEN AI에서 API를 발급받아서 API를 통해서 접근할 수 있다.

8. 메신저 채널 연동 (텔레그램)

텔레그램이 설정 난이도가 가장 낮다.

8.1 텔레그램 봇 생성

텔레그램 앱에서 @BotFather 검색 후 대화 시작
/newbot 명령 입력
봇 이름 입력 (예: MyOpenClaw)
봇 username 입력 (예: my_openclaw_bot, 반드시 _bot으로 끝나야 함)
BotFather가 발급하는 Bot Token을 복사 (형식: 123456789:ABCdefGHI...)

8.2 OpenClaw에 텔레그램 토큰 등록

온보딩 마법사에서 텔레그램을 선택했다면 토큰 입력 화면이 나온다.

openclaw onboard

모델을 등록 한 후, 텔레그램 채널을 선택한 후,

토큰 입력창에 토큰을 입력하면된다.

수동으로 등록하려면:

openclaw channels add --channel telegram --token <YOUR_BOT_TOKEN>

주의: openclaw configure --section channels (인터랙티브 위자드)에서도 등록할 수 있지만, CLI로 직접 등록할 때는 반드시 channels add 명령을 사용한다. openclaw config set channels.telegram.token ...은 동작하지 않는다 (키 이름이 다르다).

토큰 등록 후 게이트웨이를 재시작해야 반영된다:

openclaw gateway restart

8.2.1 401 Unauthorized 에러

게이트웨이 로그에 아래와 같은 에러가 반복되면:

[telegram] telegram deleteWebhook failed: Call to 'deleteWebhook' failed! (401: Unauthorized)
[telegram] [default] channel exited: Call to 'deleteWebhook' failed! (401: Unauthorized)
[telegram] [default] auto-restart attempt 1/10 in 5s

원인: 텔레그램 봇 토큰이 잘못되었거나 만료되었다.

해결:

텔레그램에서 @BotFather -> /mybots -> 봇 선택 -> API Token으로 토큰 재확인
토큰이 맞지 않으면 /revoke로 재발급
새 토큰으로 다시 등록:

openclaw channels add --channel telegram --token <새_토큰>
openclaw gateway restart

토큰 문제가 해결되지 않으면 새 봇을 만들어 시도한다.

8.3 페어링

텔레그램에서 방금 만든 봇을 찾아 /start 전송
봇이 페어링 코드를 포함한 메시지를 보냄
터미널에서 페어링 승인:

openclaw pairing approve telegram <CODE>

8.4 확인

텔레그램에서 봇에게 아무 메시지나 보내본다.

응답이 오면 연동 완료다.

9. 메신저 채널 연동 (디스코드)

텔레그램 대신 또는 추가로 디스코드를 연동할 수 있다.

9.1 Discord 봇 생성

https://discord.com/developers/applications 접속
New Application 클릭, 이름 입력 (예: OpenClawBot)
왼쪽 메뉴에서 Bot 탭 클릭
Reset Token 클릭하여 봇 토큰 복사

9.2 Privileged Gateway Intents 설정 (필수)

Bot 탭에서 스크롤하여 Privileged Gateway Intents 섹션을 찾는다. 다음 세 개를 모두 활성화(ON)한다:

Presence Intent - 온라인 상태 감지
Server Members Intent - 서버 멤버 조회
Message Content Intent - 메시지 내용 읽기 (필수)

활성화 후 반드시 Save Changes를 클릭한다.

이 단계를 빠뜨리면 봇이 동작하지 않는다. 게이트웨이 로그에 다음과 같은 에러가 반복된다:
[discord] discord: gateway closed with code 4014 (missing privileged gateway intents)
[discord] [default] auto-restart attempt 1/10 in 5s
이 에러가 보이면 Discord Developer Portal에서 Intent 토글이 켜져 있는지 확인한다. 토글을 켜고 저장하면 게이트웨이가 자동 재시도 시 정상 연결된다.

9.3 서버에 봇 초대

왼쪽 메뉴에서 OAuth2 클릭
스크롤하여 OAuth2 URL Generator 섹션 확인
Scopes 목록에서 bot 체크 (왼쪽 열 위에서 5번째)
bot을 체크하면 아래에 Bot Permissions 패널이 나타난다
Bot Permissions에서 체크:
- Send Messages
- Read Message History
- Read Messages/View Channels
- Embed Links
- Attach Files
페이지 하단에 Generated URL이 표시된다
URL을 복사하여 브라우저에 붙여넣기
봇을 초대할 서버를 선택하고 승인

9.4 OpenClaw에 디스코드 토큰 등록

openclaw channels add --channel discord --token "YOUR_BOT_TOKEN"

주의: PowerShell에서는 토큰을 반드시 따옴표로 감싸야 한다. 디스코드 봇 토큰에 포함된 특수문자(. 등)가 셸 연산자로 해석될 수 있다. CMD에서는 따옴표 없이도 동작하지만, 습관적으로 감싸는 것을 권장한다.

등록 후 게이트웨이를 재시작한다:

openclaw gateway restart

9.5 페어링

디스코드에서 봇에게 DM으로 아무 메시지를 보내면 페어링 코드가 나온다.

openclaw pairing approve discord <CODE>

9.6 확인

디스코드에서 봇에게 DM으로 메시지를 보내본다. 응답이 오면 연동 완료다.

주의: 서버 채널이 아닌 DM으로 먼저 테스트한다. 서버 채널에서 봇을 사용하려면 멘션(@OpenClawBot)으로 호출하거나 OpenClaw 설정에서 mention gating을 조정해야 한다.

10. 게이트웨이 시작 및 확인

# 게이트웨이 시작
openclaw gateway start

# 상태 확인
openclaw gateway status

# 웹 대시보드 열기
openclaw dashboard

웹 대시보드는 기본적으로 http://127.0.0.1:18789/ 에서 접근 가능하고, 상태를 GUI로 한눈에 보기 좋다.

포트를 변경하려면:

openclaw gateway --port 18790

11. 워크스페이스 커스터마이징

설치 후 %USERPROFILE%\.openclaw\ 디렉토리에 다음 구조가 생성된다:

%USERPROFILE%\.openclaw\
  openclaw.json          # 메인 설정 (모델, 채널, 게이트웨이 등)
  workspace\
    AGENTS.md            # 에이전트 행동 지침 (부트스트래퍼)
    SOUL.md              # 페르소나 (성격, 말투, 태도)
    USER.md              # 사용자 정보 (이름, 업무 맥락, 선호)
    MEMORY.md            # 장기 기억 (대화에서 학습한 내용)
    IDENTITY.md          # 에이전트 자기 소개 (이름, 이모지 등)
    skills/              # 스킬 플러그인 디렉토리

11.1 각 파일의 역할

OpenClaw는 매 세션 시작 시 워크스페이스 파일을 읽어서 에이전트의 성격과 맥락을 구성한다. 에이전트는 대화 간 기억이 없으므로 이 파일들이 곧 기억이다.

파일	역할	누가 편집하나	예시
SOUL.md	에이전트의 성격, 말투, 행동 원칙 정의. "너는 어떤 존재인가"에 대한 답.	사용자가 직접 작성	비꼬는 말투, 직설적 스타일, 독설 수위 등
USER.md	사용자 정보. 이름, 직업, 업무 맥락, 선호하는 커뮤니케이션 스타일.	사용자가 직접 작성하거나 온보딩 시 에이전트가 생성	"JDW, 기술 CEO, 인사치레 불필요"
AGENTS.md	에이전트 행동 지침 (부트스트래퍼). 도구 사용 규칙, 응답 형식, 작업 흐름 정의.	사용자가 직접 작성	"외부 발신 전 항상 확인", "파일 수정 전 백업"
MEMORY.md	대화에서 학습한 장기 기억. 에이전트가 대화 중 기록할 사항을 여기에 저장.	에이전트가 자동 업데이트 (사용자도 편집 가능)	"JDW는 setx PATH를 싫어한다"
IDENTITY.md	에이전트의 자기 소개. 이름, 이모지, 한 줄 소개.	에이전트가 온보딩 시 생성 (사용자도 편집 가능)	"이름: Secretary, 이모지: 🦞"

11.2 SOUL.md vs AGENTS.md 차이

혼동하기 쉬운 두 파일의 차이:

SOUL.md = "누구인가" (성격)

말투, 태도, 유머 스타일
비꼬는 수위, 칭찬 기준
감정적 경계선 (언제 진지해질 것인가)

AGENTS.md = "무엇을 어떻게 하는가" (행동 규칙)

도구 사용 권한과 제한
작업 수행 절차와 우선순위
응답 형식 (코드 스타일, 언어 등)
승인이 필요한 작업 목록

예를 들어 "비꼬는 말투로 대답해라"는 SOUL.md에, "이메일 발송 전 반드시 사용자 확인을 받아라"는 AGENTS.md에 넣는다.

11.3 SOUL.md 편집

에이전트의 페르소나를 설정한다:

notepad %USERPROFILE%\.openclaw\workspace\SOUL.md

11.4 USER.md 편집

사용자 정보를 입력하면 에이전트가 맥락에 활용한다:

notepad %USERPROFILE%\.openclaw\workspace\USER.md

11.5 AGENTS.md 편집

에이전트 행동 규칙을 정의한다:

notepad %USERPROFILE%\.openclaw\workspace\AGENTS.md

11.6 세션 내 모델 변경

대화 중에도 모델을 바꿀 수 있다:

/model opus4.5

12. 스킬 추가

스킬은 OpenClaw에 기능을 추가하는 플러그인이다.

12.1 ClawHub CLI로 스킬 검색 및 설치

npm i -g clawhub

clawhub search "calendar"
clawhub install <skill-slug>
clawhub list

12.2 직접 스킬 파일 생성

workspace/skills/ 폴더에 SKILL.md 파일을 직접 만들어 넣을 수도 있다. 새 세션을 시작하면 자동으로 로드된다.

13. 주요 명령어 정리

명령어	설명
`openclaw --version`	설치 버전 확인
`openclaw doctor`	설정 문제 진단
`openclaw status`	전체 상태 확인
`openclaw gateway start`	게이트웨이 시작
`openclaw gateway restart`	게이트웨이 재시작
`openclaw gateway status`	게이트웨이 상태 확인
`openclaw dashboard`	웹 대시보드 열기
`openclaw models set <model>`	모델 변경
`openclaw config get gateway.auth.token`	게이트웨이 인증 토큰 확인
`openclaw channels login`	채널 로그인
`openclaw pairing approve <channel> <code>`	채널 페어링 승인
`openclaw pairing list <channel>`	페어링 목록 확인
`ollama launch openclaw`	Ollama 경유 실행
`ollama launch openclaw --config`	설정만 변경 (게이트웨이 미시작)

14. 트러블슈팅

14.1 openclaw 명령이 인식되지 않음

원인: npm 글로벌 경로가 PATH에 없다.

진단:

# 바이너리 위치 확인
npm prefix -g
# 출력 예: C:\Users\<UserName>\AppData\Roaming\npm

# 파일 존재 여부 확인
dir "C:\Users\<UserName>\AppData\Roaming\npm\openclaw*"

# 직접 경로로 실행 테스트
"C:\Users\<UserName>\AppData\Roaming\npm\openclaw.cmd" --version

직접 경로로 버전이 출력되면 설치는 완료된 상태이고 PATH만 추가하면 된다. 3.3절 (PATH 추가 방법) 참고.

14.2 ollama 명령이 인식되지 않음

원인 A: setx PATH로 인한 사용자 PATH 유실 (아래 12.3절 참고)

원인 B: Ollama 경로가 PATH에 등록되지 않은 상태

진단:

where /R "C:\Users\<UserName>" ollama.exe
# 출력 예: C:\Users\<UserName>\AppData\Local\Programs\Ollama\ollama.exe

경로가 나오면 설치는 되어 있으나 PATH에 없는 것이다. 3.3절의 방법으로 해당 경로의 디렉토리를 PATH에 추가한다.

14.3 setx PATH로 인한 환경변수 유실

증상:

CMD에서 setx PATH "%PATH%;새경로" 실행 후
"경고: 저장하는 데이터를 1024문자로 잘라냅니다" 메시지 출력
이후 ollama, go, python 등 기존에 되던 명령이 인식되지 않음

원인 분석:

%PATH%는 사용자 PATH + 시스템 PATH가 합쳐진 값이다. setx PATH는 사용자 PATH만 덮어쓴다. 합쳐진 긴 문자열이 1024자에서 잘려서 사용자 PATH에 들어가면서 뒷부분에 있던 경로(Ollama 등)가 소실된다.

복구: 4절 (PATH 유실 복구) 참고.

예방: PATH 추가는 항상 GUI(sysdm.cpl) 또는 PowerShell로 한다.

14.4 CMD에서 PowerShell 전용 명령 실행 시 오류

증상:

C:\Windows\System32>[Environment]::SetEnvironmentVariable(...)
파일 이름, 디렉터리 이름 또는 볼륨 레이블 구문이 잘못되었습니다.

원인: [Environment]::SetEnvironmentVariable()은 PowerShell 전용 .NET 문법이다. CMD(명령 프롬프트)에서는 실행할 수 없다.

해결:

CMD에서 powershell을 입력하여 PowerShell로 전환한 뒤 실행
또는 시작 메뉴에서 PowerShell을 직접 열기

구분법:

CMD 프롬프트: C:\Users\<UserName>>
PowerShell 프롬프트: PS C:\Users\<UserName>>

14.5 PATH 변경 후 명령이 여전히 인식되지 않음

원인: 환경변수 변경은 현재 열려 있는 터미널에 반영되지 않는다.

해결: CMD/PowerShell 창을 완전히 닫고 새로 열어야 반영된다. 같은 창에서 아무리 다시 입력해도 이전 PATH를 계속 사용한다.

14.6 ollama 명령이 출력 없이 종료됨 (system32 유령 파일)

증상: PowerShell에서 ollama --version을 실행해도 아무 출력 없이 프롬프트가 돌아온다. 또는 ollama launch openclaw 실행 시 "앱을 선택하여 'ollama'을(를) 여세요" 대화상자가 뜬다.

진단:

Get-Command ollama
# Source가 C:\Windows\system32\ollama 이면 문제

(Get-Item "C:\Windows\system32\ollama").Length
# 0 이면 유령 파일 확정

원인: C:\Windows\system32에 0바이트 빈 ollama 파일이 존재한다. 이 파일이 진짜 ollama.exe(사용자 PATH)보다 우선순위가 높아서 가로챈다. WSL 설치 과정에서 생성되었을 가능성이 있다.

해결: 관리자 PowerShell에서:

Remove-Item "C:\Windows\system32\ollama" -Force

삭제 후 새 터미널에서:

ollama --version
# 정상적으로 버전 출력되면 해결

14.7 ollama launch openclaw가 지원되지 않음 (버전 문제)

증상: ollama launch openclaw 실행 시 아무 반응 없거나 에러가 발생한다.

진단:

ollama --version

원인: ollama launch openclaw는 Ollama 0.17 이상에서 지원한다. 0.16.x 이하에서는 이 명령이 없다.

해결: https://ollama.com/download/windows 에서 최신 버전을 다운로드하여 설치한다.

설치 후 확인:

ollama --version
# 0.17.x 이상이면 정상

14.8 node.exe 크래시 (0xc0000005)

Windows Defender가 node.exe를 오탐하는 경우다.

해결:

Windows Defender 실시간 보호를 일시 비활성화
설치 스크립트를 다시 실행
설치 완료 후 실시간 보호를 다시 활성화

14.9 PowerShell에서 스크립트 실행 차단

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

14.10 온보딩 보안 경고에서 자동으로 No가 선택됨

증상: ollama launch openclaw 실행 후 온보딩 보안 경고 프롬프트에서 키 입력 없이 자동으로 "No"가 선택되어 종료된다.

o  I understand this is personal-by-default and shared/multi-user use requires lock-down. Continue?
|  No
Error: exit status 1

원인: Windows 네이티브 CMD에서 OpenClaw TUI의 인터랙티브 프롬프트가 키 입력을 인식하지 못한다. OpenClaw 자체가 다음과 같이 경고한다:

Windows detected -- OpenClaw runs great on WSL2!
Native Windows might be trickier.

해결: Windows Terminal에서 실행한다. Microsoft Store에서 "Windows Terminal"을 검색하여 설치한 후 그 안에서 실행하면 TUI 입력이 정상 동작한다.

14.11 ollama launch openclaw에서 모델 연결 실패

Ollama 서비스가 실행 중인지 확인:

ollama ps

실행 중이 아니면 Ollama 앱을 시작하거나:

ollama serve

14.12 게이트웨이가 시작되지 않음

# 진단
openclaw doctor

# 로그 확인
openclaw gateway --verbose

14.13 npm install 중 메모리 부족

PowerShell에서:

$env:NODE_OPTIONS="--max-old-space-size=4096"
iwr -useb https://openclaw.ai/install.ps1 | iex

CMD에서:

set NODE_OPTIONS=--max-old-space-size=4096

14.14 Discord 봇 연결 실패 (code 4014)

증상: 게이트웨이 로그에 다음이 반복된다:

[discord] discord: gateway closed with code 4014 (missing privileged gateway intents)
[discord] [default] auto-restart attempt 1/10 in 5s

원인: Discord Developer Portal에서 Privileged Gateway Intents가 비활성화 상태다.

해결:

https://discord.com/developers/applications 접속
봇 앱 클릭 -> 왼쪽 Bot 탭
스크롤하여 Privileged Gateway Intents 섹션에서 세 개 모두 ON:
- Presence Intent
- Server Members Intent
- Message Content Intent
Save Changes 클릭
게이트웨이가 자동 재시도하므로 별도 재시작 불필요. 로그에서 에러 없이 연결되면 성공.

14.15 PowerShell에서 Discord 토큰 입력 시 에러

증상:

openclaw channels add --channel discord --token <MTQ3NzY3...>
At line:1 char:49
+ ... --token <MTQ3NzY3...
+             ~
The '<' operator is reserved for future use.

원인: PowerShell이 토큰의 <> 또는 특수문자를 셸 연산자로 해석한다.

해결: 토큰을 따옴표로 감싼다:

openclaw channels add --channel discord --token "MTQ3NzY3..."

또는 인터랙티브 위자드를 사용하면 따옴표 문제가 없다:

openclaw configure --section channels

15.보안 주의사항

OpenClaw 제작자(Peter Steinberger)가 공식 문서에서 직접 경고하고 있다:

"개인 컴퓨터에서 AI 에이전트를 실행하는 것은 위험하다."

지켜야 할 원칙:

금융 정보가 있는 환경과 분리한다. 은행 앱, 증권 계좌, 암호화폐 지갑이 있는 사용자 계정에서는 실행하지 않는다.
별도 사용자 계정을 만들어 실행하는 것을 권장한다. Windows에서 표준 사용자 계정을 하나 더 만들어 격리 운영한다.
출처 불명의 스킬을 설치하지 않는다. 악성 스킬을 통한 공격 사례가 보고되고 있다.
로컬 모델 사용 시 더 주의한다. 작은 로컬 모델은 의도를 오해석하여 잘못된 파일 조작을 할 수 있다. 파일 조작이나 자동화 같은 에이전트 액션은 API 모델(Claude, GPT 등)로 돌리는 것이 안전하다.

보안 감사를 주기적으로 실행한다.

openclaw doctor

16. 비용

OpenClaw 자체는 오픈소스로 무료다.

하지만 LLM 사용에 따른 비용이 발생할 수 있다:

구분	비용	과금 방식
Ollama 로컬 모델	무료 (전기요금만 발생)	없음
Ollama Cloud 모델	무료 티어 제공, 초과 시 과금	종량제
ChatGPT Plus (Codex CLI)	월 $20 정액	무제한
ChatGPT Pro	월 $200 정액	무제한 (상위 모델 사용 가능)
Anthropic Claude API	사용량에 따라 과금	종량제
OpenAI GPT API	사용량에 따라 과금	종량제

에이전트가 자율적으로 동작하면 토큰 소비가 예측하기 어렵다. API 종량제를 사용할 경우 사용량 모니터링과 일일 한도 설정을 권장한다.

17.마치며

여기까지 따라왔다면 OpenClaw는 아마 잘 돌아갈 것이다. 텔레그램으로 메시지 보내면 대답도 한다. 필자는 윈도우 말고 도커 환경에서 설치했지만, 어차피 도커 환경 설정 할 줄 알면 이걸 안봐도 알아서 할 것이다.

그런데 솔직히 말하자면, 이게 그렇게 유용한지는 의문이다.

"AI가 내 컴퓨터를 대신 제어한다"는 개념은 인상적으로 들린다. 그런데 실제로 쓰다 보면 대부분의 작업은 그냥 직접 하는 게 빠르다. 파일 하나 옮기려고 텔레그램에 명령 입력하고 확인 기다리는 것보다, 탐색기에서 드래그하는 게 3초 빠르다.

그렇다면 이 생태계는 왜 존재하는가.

답은 간단하다. 공포 비즈니스다.

"AI 에이전트를 구축하지 못하면 뒤처진다"는 불안을 판다. 자신의 컴퓨터에 AI 비서가 없으면 비효율적인 사람처럼 느끼게 만든다. 설치 과정이 복잡할수록, 트러블슈팅이 많을수록, 완성했을 때의 성취감도 커진다. 그 성취감이 실제 생산성 향상과 무관하더라도.

개인적으로 이를 가짜 성취감이라고 부른다. 어떤 생산성이 늘어난 게 아니다. 단순히 해결 했다는 느낌을 판다. 나의 경우에는 굉장히 손쉽게 설치가 가능하지만 비개발자에게는 상당히 어려운 과정이다.

실제로 이 가이드에서 가장 긴 섹션이 트러블슈팅이다. 이게 말해주는 게 무엇일까?

로컬 AI 에이전트가 의미 있는 순간은 극소수이다. 반복 작업이 명확하고, 그 작업이 실제로 자주 발생하고, 직접 하기보다 위임하는 게 유리할 때다. 그 조건을 충족하지 못하면 그냥 전기 먹는 채팅봇이다. 그냥 챗봇 사이트에서 채팅치는것보다 장점이 무엇인가?

파이썬을 쓰면 간단한 엑셀 툴 정도는 자동화가 된다.

섹션간 맥락 문제로 엑셀 툴 수정도 생각보다 별로인 경우가 많다.

PPT도 요즘은 어지간한 건 된다. CLI 켜서 멀티 에이전트 키면 코딩도 굳이 오픈클로를 쓸 이유가 없다.

에이전트로 자동화 한다는 행동을 면면히 따지자면 굳이 자유화할 필요가 없는 것이 대부분이다. 실제로 일부 사람들에게는 쓸만한 부분들이 있을 것이다.

선택지가 늘어난다는 것은 굉장히 훌륭하다. 하지만 그것이 과연 언론에서 말하는만큼 폭발적인 생산성을 늘려주는가에 대해서는 여전히 회의적이다.