06. OpenClaw 설치 오류 복구

OpenClaw 설치가 막히는 이유는 의외로 단순합니다. 설치 파일 자체보다 설치 직후 인증·연결 단계에서 멈추는 경우가 훨씬 많습니다.
특히 검색에서 자주 들어오는 키워드도 거의 같습니다: openclaw command not found, pairing required, device token mismatch, gateway 1006/not connected.
이 글은 “증상 확인 → 바로 실행 → 성공 판정” 순서로 재정리해, 초보자도 복붙 중심으로 15분 내 복구할 수 있게 구성했습니다.

flowchart TD
A[증상 확인] --> B{어떤 오류?}
B --> C[openclaw not found]
B --> D[pairing required]
B --> E[device token mismatch]
B --> F[DSM gateway 1006 / not connected]
C --> C1[@latest 재설치 + PATH 재주입]
D --> D1[devices approve + pairing approve]
E --> E1[identity 캐시 백업 후 gateway restart]
F --> F1[.npmrc prefix 충돌 제거 + gateway foreground/nohup]
C1 --> Z[정상 연결]
D1 --> Z
E1 --> Z
F1 --> Z

🧠 칠판 치트시트

설치 실패보다 인증/연결에서 더 많이 막힌다

DSM에서는 .bashrc보다 .profile 기준으로 환경을 고정한다

openclaw gateway status와 openclaw devices list를 먼저 본다

먼저 아래 10초 체크부터 하고 시작하면 진단 속도가 확 빨라집니다.

which openclaw
openclaw -V
openclaw gateway status
openclaw devices list

검색 유입 빠른 답 (30초 버전)

openclaw: command not found → 설치보다 PATH 반영부터 확인
pairing required → devices approve + pairing approve 둘 다 필요
token mismatch → identity 파일 백업 후 gateway 재시작
1006/not connected(DSM) → gateway start 반복보다 gateway --bind loopback 우선

30초 자동 분류(복붙용)

아래 4줄 결과만 보면 어디부터 손대야 할지 바로 결정할 수 있습니다.

echo "[1] which openclaw" && which openclaw || true
echo "[2] version" && openclaw -V || true
echo "[3] gateway" && openclaw gateway status || true
echo "[4] devices" && openclaw devices list || true

1·2번 실패 → 문제 1(PATH/PREFIX)
1·2번 성공 + 3번 실패 → 문제 4(gateway 연결)
3번 성공 + TUI에서 pairing required → 문제 2(승인 2단계)
TUI에서 device token mismatch → 문제 3(identity 캐시 재발급)

1분 진단 맵 (증상 → 바로 할 일)

openclaw: command not found → PATH/PREFIX 문제 먼저 확인 (문제 1)
pairing required → devices 승인 + pairing 승인 두 단계 모두 수행 (문제 2)
device token mismatch → identity 백업 후 gateway 재시작 (문제 3)
1006 / not connected to gateway(DSM) → service 모드 집착 금지, foreground/nohup 전환 (문제 4)

가장 빨리 복구되는 순서 (초보자용)

문제를 처음 만났다면 아래 순서대로만 따라가도 대부분 15분 안에 복구됩니다.

CLI 인식 확인: which openclaw와 openclaw -V가 실패하면 문제 1부터
Gateway 연결 확인: openclaw gateway status가 비정상이면 문제 4부터
승인 상태 확인: TUI에서 pairing required가 뜨면 문제 2로 이동
토큰 충돌 확인: token mismatch가 뜨면 문제 3으로 이동

빠른 판단 규칙: 명령 자체가 안 되면 PATH, 명령은 되는데 연결이 안 되면 Gateway/Pairing입니다.

문제 1) `openclaw: command not found`

이 에러는 대부분 “설치 누락”보다 PATH 미반영에서 생깁니다. 즉, 설치는 되었는데 현재 셸이 실행 파일 위치를 모르는 상태예요.

해결

npm i -g openclaw@latest
export PATH="$(npm prefix -g)/bin:$PATH"
rehash
which openclaw
openclaw -V

성공 판정

which openclaw가 경로를 출력
openclaw -V가 버전을 출력

현장 미니 사례

실패 사례: 재설치만 반복하고 PATH를 안 넣어서 동일 에러 반복
성공 사례: PATH 주입 후 새 셸에서 즉시 해결

공식 참고: https://docs.openclaw.ai

문제 2) `gateway connect failed: pairing required`

이건 “앱 고장”이 아니라 승인 절차 미완료인 경우가 많습니다.
장치 승인(devices)과 채널 페어링(pairing)을 둘 다 완료해야 연결이 열립니다.

해결

openclaw devices list
openclaw devices approve --latest
openclaw pairing list telegram
openclaw pairing approve telegram <PAIRING_CODE>

성공 판정

TUI 접속 시 pairing required가 더 이상 나오지 않음
텔레그램 접근 거부 메시지 사라짐

현장 미니 사례

실패 사례: devices approve만 하고 pairing approve를 빼먹음
성공 사례: 승인 2단계를 순서대로 완료 후 즉시 복구

공식 참고: https://docs.openclaw.ai

문제 3) `unauthorized: device token mismatch`

이 에러는 로컬 identity 캐시와 현재 게이트웨이 토큰이 어긋났을 때 발생합니다.
핵심은 파일을 바로 지우는 게 아니라 백업 후 재발급입니다.

해결

STATE_DIR="${OPENCLAW_STATE_DIR:-$HOME/.openclaw}"
TS="$(date +%s)"
mkdir -p "$STATE_DIR/identity/backup-$TS"
mv "$STATE_DIR/identity/device-auth.json" "$STATE_DIR/identity/backup-$TS/" 2>/dev/null || true
mv "$STATE_DIR/identity/device.json" "$STATE_DIR/identity/backup-$TS/" 2>/dev/null || true
openclaw gateway restart
openclaw gateway status
openclaw tui

성공 판정

TUI에서 idle 상태 진입
token mismatch 재발 없음

현장 미니 사례

실패 사례: identity 파일을 백업 없이 삭제해 원인 추적이 어려워짐
성공 사례: 백업 후 재시작으로 복구 + 동일 문제 재현 시 비교 가능

공식 참고: https://docs.openclaw.ai

문제 4) Synology DSM에서 `gateway 1006` / `not connected to gateway`

Synology DSM에서는 systemd --user가 기본적으로 동작하지 않아, 일반 리눅스처럼 서비스 모드로 올릴 때 연결이 끊긴 것처럼 보일 수 있습니다. 이때 gateway 1006과 not connected to gateway가 연달아 나옵니다.

특히 openclaw gateway start에서 failed to D-bus connection: connection refused가 뜨면, 게이트웨이 자체 고장이라기보다 서비스 매니저(D-Bus) 경로가 없는 환경일 가능성이 큽니다. 이 경우 start/restart 반복보다 openclaw gateway run(foreground) 또는 nohup 유지 실행으로 전환하는 게 정석입니다.

또한 ~/.npmrc에 prefix/globalconfig가 남아 있으면 nvm과 충돌해 Node 22는 보이는데 CLI 동작이 불안정해질 수 있습니다.

해결 (DSM 표준 복구 순서)

# 1) nvm/npm prefix 충돌 제거
nvm use --delete-prefix v22.22.0 --silent
npm config delete prefix
npm config delete globalconfig

# 2) .profile 기준 nvm 로드
echo 'export NVM_DIR="$HOME/.nvm"' >> ~/.profile
echo '[ -s "$NVM_DIR/nvm.sh" ] && . "$NVM_DIR/nvm.sh"' >> ~/.profile
source ~/.profile

# 3) gateway는 foreground 또는 nohup으로 실행
openclaw gateway --port 18789 --bind loopback

다른 터미널에서:

openclaw gateway status
openclaw tui

터미널 종료해도 유지하려면

nohup openclaw gateway --port 18789 --bind loopback > /tmp/openclaw/gateway-nohup.log 2>&1 &
disown

성공 판정

openclaw gateway status에서 RPC probe: ok
openclaw tui에서 not connected to gateway가 사라짐
Telegram DM 응답 확인

현장 미니 사례

실패 사례: openclaw gateway --force만 반복(DSM에선 systemd user unavailable)
성공 사례: --bind loopback foreground 기동 후 별도 터미널에서 TUI 연결 성공

공식 참고:

자주 검색하는 질문 (바로 답)

Q1. `openclaw: command not found`가 재설치해도 계속 떠요.

거의 항상 PATH 반영 문제입니다. 재설치보다 npm prefix -g 경로가 현재 셸 PATH에 잡혀 있는지 먼저 확인하세요.

Q2. `pairing required`가 계속 뜨는데 devices approve는 했어요.

devices approve와 pairing approve는 다른 단계입니다. 장치 승인 후 채널 페어링(telegram 등)까지 완료해야 접속이 열립니다.

Q3. token mismatch가 무서워서 파일 삭제가 걱정돼요.

바로 삭제하지 말고 identity/backup-<timestamp>에 먼저 이동(백업)한 뒤 gateway를 재시작하세요. 추적 가능성이 크게 올라갑니다.

Q4. DSM에서 `.bashrc`가 없다고 나와요.

Synology는 .profile 기준인 경우가 많습니다. source ~/.profile로 진행하고 nvm 로드도 .profile에 고정하세요.

Q5. `Invalid --bind`가 떠요.

--bind 127.0.0.1처럼 IP를 직접 넣는 옵션이 아닙니다. --bind loopback처럼 키워드(loopback, lan, tailnet, auto)를 사용하세요.

Q6. `failed to D-bus connection: connection refused`가 떠요.

Synology 환경에서 gateway start가 서비스 매니저 경로를 타며 실패할 때 자주 보입니다. openclaw gateway run --allow-unconfigured으로 먼저 살리고, 필요하면 nohup ... &로 유지 실행하세요.

15분 복구 루틴 (초보자용)

5분: which, -V, gateway status, devices list로 현재 상태 확인
5분: 해당 에러 섹션 명령을 한 줄씩 실행
5분: TUI 진입 확인 + Telegram 접근 확인 + 로그 메모

다음 액션

설치/연결이 정상화되면 바로 02. 시작하기 루트로 진행하세요.

본 문서는 생성형 AI를 활용해 작성되었습니다.

일하는 ai

탐색기

06. OpenClaw 설치 오류 복구

검색 유입 빠른 답 (30초 버전)

30초 자동 분류(복붙용)

1분 진단 맵 (증상 → 바로 할 일)

가장 빨리 복구되는 순서 (초보자용)

문제 1) `openclaw: command not found`

해결

성공 판정

현장 미니 사례

문제 2) `gateway connect failed: pairing required`

해결

성공 판정

현장 미니 사례

문제 3) `unauthorized: device token mismatch`

해결

성공 판정

현장 미니 사례

문제 4) Synology DSM에서 `gateway 1006` / `not connected to gateway`

해결 (DSM 표준 복구 순서)

터미널 종료해도 유지하려면

성공 판정

현장 미니 사례

자주 검색하는 질문 (바로 답)

Q1. `openclaw: command not found`가 재설치해도 계속 떠요.

Q2. `pairing required`가 계속 뜨는데 devices approve는 했어요.

Q3. token mismatch가 무서워서 파일 삭제가 걱정돼요.

Q4. DSM에서 `.bashrc`가 없다고 나와요.

Q5. `Invalid --bind`가 떠요.

Q6. `failed to D-bus connection: connection refused`가 떠요.

15분 복구 루틴 (초보자용)

관련 문서 10선

다음 액션

그래프 뷰

목차

백링크

일하는 ai

탐색기

06. OpenClaw 설치 오류 복구

검색 유입 빠른 답 (30초 버전)

30초 자동 분류(복붙용)

1분 진단 맵 (증상 → 바로 할 일)

가장 빨리 복구되는 순서 (초보자용)

문제 1) openclaw: command not found

해결

성공 판정

현장 미니 사례

문제 2) gateway connect failed: pairing required

해결

성공 판정

현장 미니 사례

문제 3) unauthorized: device token mismatch

해결

성공 판정

현장 미니 사례

문제 4) Synology DSM에서 gateway 1006 / not connected to gateway

해결 (DSM 표준 복구 순서)

터미널 종료해도 유지하려면

성공 판정

현장 미니 사례

자주 검색하는 질문 (바로 답)

Q1. openclaw: command not found가 재설치해도 계속 떠요.

Q2. pairing required가 계속 뜨는데 devices approve는 했어요.

Q3. token mismatch가 무서워서 파일 삭제가 걱정돼요.

Q4. DSM에서 .bashrc가 없다고 나와요.

Q5. Invalid --bind가 떠요.

Q6. failed to D-bus connection: connection refused가 떠요.

15분 복구 루틴 (초보자용)

관련 문서 10선

다음 액션

그래프 뷰

목차

백링크

문제 1) `openclaw: command not found`

문제 2) `gateway connect failed: pairing required`

문제 3) `unauthorized: device token mismatch`

문제 4) Synology DSM에서 `gateway 1006` / `not connected to gateway`

Q1. `openclaw: command not found`가 재설치해도 계속 떠요.

Q2. `pairing required`가 계속 뜨는데 devices approve는 했어요.

Q4. DSM에서 `.bashrc`가 없다고 나와요.

Q5. `Invalid --bind`가 떠요.

Q6. `failed to D-bus connection: connection refused`가 떠요.