OpenClaw - Arch Linux 설치

• Arch Linux 환경에서 OpenClaw 설치부터 실제 장애 해결까지 전체 흐름 정리함
• 단순 설치 가이드가 아니라 구조 이해 + 트러블슈팅 중심으로 정리함
• 설치 → 온보딩 → 장애 원인 → 해결 플레이북 순서로 구성함

⚙️ Node.js 설치 (v22 이상)

sudo pacman -S nodejs npm
node -v

# 결과
v25.6.1

• OpenClaw는 최신 Node 환경 필요함
• Arch Linux에서는 pacman으로 바로 설치 가능함

📦 pnpm 설치

sudo pacman -S pnpm
pnpm -v

# 결과
10.28.2

• OpenClaw는 pnpm 글로벌 설치 방식 사용함
• npm 대신 pnpm 사용 권장됨

🧩 pnpm 글로벌 경로 설정

pnpm setup

# zsh
exec zsh

# bash
exec bash

# fish
exec fish

• pnpm 글로벌 바이너리 경로를 shell에 반영해야 CLI 실행 가능함
• setup 이후 shell 재시작 필요함

🤖 OpenClaw 설치

pnpm add -g openclaw@latest

• pnpm 글로벌 패키지로 OpenClaw 설치 진행함
• 설치 완료 후 openclaw 명령어 정상 동작 확인함

🚀 온보딩 (Onboarding)

openclaw onboard --install-daemon

• OpenClaw는 CLI 단독 구조가 아니라 Gateway + Control UI 구조임
• 최초 온보딩 과정이 pairing 및 인증에 매우 중요함

온보딩 선택 예시

◇  I understand this is powerful and inherently risky. Continue?
│  Yes
│
◇  Onboarding mode
│  QuickStart
│
◇  Model/auth provider
│  OpenAI
│
◇  OpenAI auth method
│  OpenAI Codex (ChatGPT OAuth)
│
◇  Model configured ────────────────────────────────╮
│                                                   │
│  Default model set to openai-codex/gpt-5.3-codex  │
│                                                   │
├───────────────────────────────────────────────────╯
│
◇  Default model
│  Keep current (openai-codex/gpt-5.3-codex)
│
◇  Select channel (QuickStart)
│  Skip for now
│
◇  Configure skills now? (recommended)
│  Yes
│
◇  Install missing skill dependencies
│  Skip for now
│
◇  Set GOOGLE_PLACES_API_KEY for goplaces?
│  No
│
◇  Set GEMINI_API_KEY for nano-banana-pro?
│  No
│
◇  Set NOTION_API_KEY for notion?
│  No
│
◇  Set OPENAI_API_KEY for openai-image-gen?
│  No
│
◇  Set OPENAI_API_KEY for openai-whisper-api?
│  No
│
◇  Set ELEVENLABS_API_KEY for sag?
│  No
│
◇  Enable hooks?
│  Skip for now
│
└  Onboarding complete. Dashboard opened; keep that tab to control OpenClaw.

🧰 로컬 설정 초기화

openclaw setup

# 결과
Config OK: ~/.openclaw/openclaw.json
Workspace OK: ~/.openclaw/workspace
Sessions OK: ~/.openclaw/agents/main/sessions

• 워크스페이스 및 설정 파일 정상 생성 여부 확인 단계

🧠 OpenClaw 구조 이해 (핵심)

CLI → Gateway(daemon) → Device Pairing → Control UI(Browser)

• CLI만 정상이어도 동작하지 않음
• Gateway 인증 상태 + 브라우저 토큰 상태까지 일치해야 정상 동작함

🚨 장애 사례 — pairing required 무한루프 발생

openclaw agent --agent main --message "hello"

gateway connect failed: Error: pairing required

• Gateway는 실행 중
• CLI만 연결 거부되는 상태 발생

🔎 무한루프 발생 원인

• CLI 디바이스는 pairing 완료 상태
• 브라우저 Control UI는 gateway token 없음
• Gateway는 이를 device token mismatch로 판단하고 WebSocket 연결을 차단함
• gateway 인증 필요한 명령도 막혀 무한루프처럼 보이게 됨

🛠 장애 해결 플레이북

1. Gateway 프로세스 확인

ss -lntp | grep 18789

• 18789 포트를 어떤 프로세스가 사용 중인지 먼저 확인함

2. Gateway 강제 재기동

sudo pacman -S lsof
openclaw gateway --force

• Arch Linux에서 --force 사용 시 lsof 필요
• 기존 gateway 종료 후 재실행됨

3. 온보딩 재진입 (핵심)

openclaw onboard

• setup은 pairing을 해결하지 못함
• 반드시 onboard를 다시 실행해야 함
• 마지막 단계에서 Gateway restart 선택

4. systemd user 서비스 충돌 확인

• PID가 계속 바뀌면 자동 서비스 실행 가능성 있음

systemctl --user list-units --type=service | grep -i openclaw

• 서비스 존재 시 중지 및 비활성화

systemctl --user stop openclaw-gateway.service
systemctl --user disable openclaw-gateway.service

ss -lntp | grep 18789 || echo "18789 free"

5. Dashboard(Control UI) 인증 초기화

• Gateway 로그에 아래 메시지 발생 시 브라우저 토큰 문제 가능성 높음

device_token_mismatch
unauthorized

해결 방법

1. http://127.0.0.1:18789 접속
2. 브라우저 쿠키 및 사이트 데이터 삭제
3. Dashboard 설정에서 Gateway Token 재등록

6. Gateway 상태 확인 및 시작

openclaw gateway start
openclaw gateway status

7. 최종 검증

openclaw agent--agent main--message"hello"

정상이라면

• pairing required 에러 사라짐
• Dashboard unauthorized 상태 해제됨

📌 핵심 정리

• OpenClaw는 단순 CLI가 아니라 Gateway + Browser 인증 구조임
• pairing 문제는 setup이 아니라 onboard에서 해결됨
• Arch Linux에서는 systemd user 서비스 충돌 여부를 반드시 확인해야 함
• Dashboard 브라우저 토큰 문제도 주요 원인 중 하나임