OpenClaw gateway 심화 2026: 포트 충돌·데몬 장애·프록시 설정 모든 서브커맨드 완전 해결
이 글에서 다루는 내용: OpenClaw gateway의 모든 서브커맨드(start/stop/restart/status/probe/discover/install/uninstall/health/call)를 완전 해설하고, 포트 18789 충돌 해결, 데몬 장애 복구, Copilot 프록시 설정, 다중 게이트웨이 설정 방법까지 심화 내용을 단계별로 설명합니다.
OpenClaw gateway란? 핵심 역할 이해
OpenClaw의 gateway는 AI 비서의 심장이라고 할 수 있습니다. CLI 명령어, 메신저 채널(텔레그램, WhatsApp, Discord), 브라우저 익스텐션, cron 작업 등 모든 인터페이스를 하나로 연결하는 중앙 허브 프로세스입니다.
gateway 아키텍처
텔레그램
Discord
CLI
OpenClaw Gateway (포트 18789)
모든 채널의 메시지를 받아 AI 모델로 라우팅
Claude API
OpenAI API
로컬 LLM
gateway 전체 서브커맨드 완전 해설
# gateway 전체 명령어 구조
openclaw gateway start # 게이트웨이 시작
openclaw gateway stop # 게이트웨이 종료
openclaw gateway restart # 재시작 (stop + start)
openclaw gateway status # 현재 상태 확인
openclaw gateway health # 헬스 체크 (채널·모델 연결 확인)
openclaw gateway probe # RPC 프로브 (CLI↔게이트웨이 통신 테스트)
openclaw gateway discover # 로컬 네트워크에서 실행 중인 게이트웨이 검색
openclaw gateway install # 시스템 서비스로 설치 (자동 시작 설정)
openclaw gateway uninstall # 시스템 서비스 제거
openclaw gateway call # 게이트웨이에 직접 RPC 호출
openclaw gateway run # 게이트웨이를 포어그라운드로 실행 (디버깅용)
기본 제어 명령어: start·stop·restart
게이트웨이를 백그라운드 데몬으로 시작합니다. 이미 gateway install로 시스템 서비스에 등록한 경우에만 효과가 있습니다. 설치 전이라면 install 먼저 실행하세요.
openclaw gateway install # 시스템 서비스 등록 (최초 1회)
openclaw gateway start # 게이트웨이 시작
openclaw gateway status # 시작 확인
게이트웨이를 안전하게 종료합니다. 진행 중인 AI 응답이 있다면 완료 후 종료합니다. 강제 종료(kill)보다 항상 이 명령어를 권장합니다.
stop 후 start를 자동으로 실행합니다. 설정 파일을 변경하거나(SOUL.md, openclaw.json 수정 등) 1008 토큰 오류 후 재동기화했을 때 반드시 실행해야 새 설정이 적용됩니다.
openclaw gateway restart
# 설정 변경, 토큰 수정, 업데이트 후 필수!
진단 명령어: status·health·probe
게이트웨이 프로세스의 전반적인 상태를 보여줍니다. PID, 포트, 업타임, 연결된 채널 수, 현재 AI 모델을 한눈에 확인합니다.
$ openclaw gateway status
Gateway Status: 🟢 Running
PID: 23847
Port: 18789 (localhost)
Uptime: 3h 42m
Model: claude-opus-4.5
Channels: telegram ✅, discord ✅, webchat ✅
RPC probe: ok
Auth token: ✅ Synced
채널·모델 연결의 헬스 체크를 실행합니다. 각 메신저 채널이 정상적으로 연결돼 있는지, AI API에 접근 가능한지를 실제로 테스트합니다.
$ openclaw gateway health
Health Check:
Telegram Bot: ✅ Connected (latency: 45ms)
Discord Bot: ✅ Connected (latency: 123ms)
Claude API: ✅ Reachable (latency: 890ms)
WebChat: ✅ Listening on :8080
Memory: ✅ Indexed (234 entries)
Overall: ✅ Healthy
CLI와 게이트웨이 간 RPC 통신 연결을 테스트합니다. 1008 토큰 불일치 오류 수정 후 통신이 복구됐는지 확인하는 데 가장 직접적인 도구입니다.
$ openclaw gateway probe
→ Probing RPC at localhost:18789...
✅ RPC probe: ok (3ms)
# 실패 시 (1008 오류 상태):
❌ RPC probe: failed — unauthorized: device token mismatch
포트 18789 충돌 해결 완전 가이드
OpenClaw gateway는 기본적으로 포트 18789를 사용합니다. 다른 프로세스가 이 포트를 점유하고 있으면 게이트웨이 시작에 실패합니다. 아래와 같은 오류 메시지가 나타납니다.
Error: Failed to start gateway
listen tcp 127.0.0.1:18789: bind: address already in use
# 또는:
Error: port 18789 is already in use by PID 45321
포트 충돌 진단 및 해결
① 포트 점유 프로세스 확인
lsof -i :18789 # macOS/Linux
netstat -ano | findstr 18789 # Windows
② 이전 게이트웨이 프로세스 강제 종료
kill -9 [PID] # Linux/macOS
taskkill /PID [PID] /F # Windows
③ 다른 포트로 게이트웨이 실행 (충돌 회피)
openclaw gateway start --port 18790
# 또는 설정에 영구 저장
openclaw config set gateway.port 18790
openclaw gateway restart
gateway discover — 로컬 네트워크 게이트웨이 검색
openclaw gateway discover는 로컬 네트워크에서 실행 중인 모든 OpenClaw 게이트웨이를 자동으로 찾아줍니다. NAS나 다른 컴퓨터에서 실행 중인 게이트웨이에 연결할 때 유용합니다.
$ openclaw gateway discover
Scanning local network for OpenClaw gateways...
Found 2 gateways:
1. 127.0.0.1:18789 (localhost, current device)
2. 192.168.1.100:18789 (NAS-Server, "홈 서버 게이트웨이")
# 다른 게이트웨이에 연결 (원격 게이트웨이 사용)
openclaw config set gateway.host 192.168.1.100
openclaw config set gateway.port 18789
시스템 서비스 등록 — install과 uninstall
openclaw gateway install은 게이트웨이를 컴퓨터 부팅 시 자동 시작하는 시스템 서비스로 등록합니다. 이것이 설정돼야 컴퓨터를 재시작해도 AI 비서가 자동으로 켜집니다.
macOS (LaunchAgent)
openclaw gateway install
# → ~/Library/LaunchAgents/
# ai.openclaw.gateway.plist 생성
# → 로그인 시 자동 시작 설정
launchctl list | grep openclaw # 확인
Linux (systemd)
openclaw gateway install
# → ~/.config/systemd/user/
# openclaw-gateway.service 생성
# → 로그인 시 자동 시작 설정
systemctl --user status openclaw-gateway
# 서비스 재설치 (업데이트 후 권장)
openclaw gateway uninstall # 기존 서비스 제거
openclaw gateway install # 새로 설치
openclaw gateway start # 시작
openclaw gateway status # 상태 확인
Copilot 프록시 설정 — GitHub 토큰으로 Claude 무제한 사용
X.com에서 @jonahships_가 공유해 폭발적인 반응을 얻은 방법입니다. GitHub Copilot 구독이 있다면 Claude API를 추가 비용 없이 무제한으로 사용하는 Copilot 프록시 방식을 gateway에 설정할 수 있습니다.
⚠️ 주의사항
이 방법은 GitHub Copilot 서비스 약관의 해석에 따라 다를 수 있습니다. 개인 프로젝트 학습 목적으로 사용하되, 상업적 이용 시 GitHub 약관을 반드시 확인하세요.
# Copilot 프록시 gateway 설정
# 1. GitHub 토큰 추가 (Copilot 구독 필요)
openclaw models auth add --provider github-copilot --token ghp_xxxx
# 2. Copilot 프록시 모델을 기본으로 설정
openclaw models set claude-3.5-sonnet --provider github-copilot
# 3. 게이트웨이 재시작
openclaw gateway restart
# 4. 확인
openclaw gateway status
# → Model: claude-3.5-sonnet (via GitHub Copilot)
고급 명령어 — gateway call과 gateway run
게이트웨이의 내부 RPC API를 직접 호출하는 고급 명령어입니다. 주로 디버깅이나 스크립트 자동화에서 사용합니다.
openclaw gateway call status # 상태 RPC 호출
openclaw gateway call health # 헬스 체크 RPC
openclaw gateway call --method send \
--body '{"channel":"telegram","message":"안녕"}' # 메시지 직접 전송
게이트웨이를 백그라운드가 아닌 포어그라운드로 실행합니다. 모든 로그가 실시간으로 터미널에 출력돼 문제를 디버깅할 때 사용합니다. Ctrl+C로 종료하면 게이트웨이가 중단됩니다.
openclaw gateway run --verbose # 상세 로그와 함께 포어그라운드 실행
# → 실시간 채널 연결 로그
# → API 요청/응답 로그
# → 오류 발생 즉시 출력
gateway 자주 발생하는 오류 총정리
① gateway: command not found
OpenClaw가 올바르게 설치되지 않았거나 PATH에 등록되지 않은 경우입니다.
which openclaw # 설치 경로 확인
export PATH="$PATH:$(which openclaw | xargs dirname)"
② gateway starts but channels show offline
게이트웨이는 실행됐지만 텔레그램/Discord 봇 토큰이 만료됐거나 잘못된 경우입니다.
openclaw gateway health # 채널별 연결 상태 확인
openclaw channels status # 채널 토큰 재확인
openclaw configure # 봇 토큰 재설정
③ API timeout — Claude/OpenAI 응답 없음
해외 AI API 서버까지의 네트워크 지연이 높아 타임아웃이 발생합니다. 특히 국내 일반 ISP에서 Anthropic API 서버까지 높은 지연이 발생할 수 있습니다.
openclaw config set gateway.timeout 60000 # 타임아웃 60초로 연장
# 근본 해결: 안정적인 해외 API 연결 확보 (VPN 사용)
④ gateway exits immediately after start
설정 파일(openclaw.json)이 손상됐거나 필수 값이 없는 경우입니다.
openclaw gateway run --verbose # 상세 오류 확인
openclaw doctor # 전체 설정 진단
openclaw doctor --fix # 자동 수리 시도
gateway 초기 설정 완료 체크리스트
시스템 서비스 설치 (최초 1회)
openclaw gateway install게이트웨이 시작
openclaw gateway start상태 확인: status + probe + health
openclaw gateway status && openclaw gateway probe && openclaw gateway health포트 충돌 여부 확인
lsof -i :18789 # 다른 프로세스가 점유하지 않는지 확인채널 연결 상태 확인
openclaw channels status # telegram ✅, discord ✅전체 진단 실행
openclaw doctor # 모든 항목 ✅ 확인메신저에서 실제 AI 응답 테스트
텔레그램/Discord에서 "안녕" 입력 후 AI 비서가 응답하면 완료!
gateway 자주 묻는 질문 (FAQ)
Q. openclaw gateway install과 openclaw gateway start의 차이는?
install은 게이트웨이를 시스템 서비스(macOS LaunchAgent, Linux systemd)로 등록해 컴퓨터 재시작 후에도 자동으로 실행되게 합니다. start는 이미 설치된 서비스를 지금 시작하는 명령어입니다. 처음 설정할 때는 install을 먼저 실행하고, 이후에는 start/stop/restart로 제어합니다.
Q. 게이트웨이를 포트 18789 대신 다른 포트로 바꿀 수 있나요?
네. openclaw config set gateway.port 18790으로 포트를 변경한 후 openclaw gateway uninstall && openclaw gateway install로 서비스를 재설치하면 됩니다. 단, 동일 호스트에서 여러 OpenClaw 인스턴스를 실행할 때만 포트 변경이 필요합니다.
Q. 외부 네트워크(집 밖)에서 집 PC의 게이트웨이에 접속할 수 있나요?
기본적으로 게이트웨이는 localhost(127.0.0.1)에만 바인딩되어 외부 접속이 불가능합니다. 외부 접속을 허용하려면 openclaw config set gateway.host 0.0.0.0으로 설정하고, 방화벽에서 포트를 열어야 합니다. 보안상 VPN을 통해 접속하는 것을 강력히 권장합니다.
Q. openclaw daemon 명령어는 gateway와 다른 건가요?
openclaw daemon은 gateway의 구 버전 별칭(legacy alias)입니다. 과거 버전과의 호환성을 위해 남아있지만, 현재는 gateway 명령어를 사용하는 것이 권장됩니다. daemon status, daemon start 등은 gateway status, gateway start와 동일하게 동작합니다.
Q. 게이트웨이가 메모리를 너무 많이 사용합니다. 어떻게 줄이나요?
메모리 사용량이 높은 원인은 대부분 ① 너무 많은 스킬 로드, ② MEMORY.md 파일이 너무 큰 경우, ③ 오래 실행된 세션입니다. openclaw gateway restart로 주기적으로 재시작하거나, 불필요한 스킬을 비활성화하세요.
OpenClaw gateway 안정 운영 VPN 추천
gateway 오류의 상당수는 API 서버까지의 네트워크 품질 문제입니다. 안정적인 해외 연결을 위한 VPN 비교입니다.
VPN07 — gateway 운영 최적화 1위
국제 대역폭 1000Mbps의 IEPL 전용선으로 Anthropic·OpenAI API 최단 경로 연결. gateway timeout 오류 원천 차단. $1.5/월, 70+국가, 30일 환불, 10년 운영.
🥈 2위 — 일반 VPN 서비스
7.0/10속도 제한 있음. 특정 시간대 gateway API 타임아웃 빈번. OpenClaw 전용 최적화 없음.
🥉 3위 — 무료 VPN
4.5/10대역폭 극히 제한, 잦은 연결 끊김으로 gateway 운영에 적합하지 않음.
VPN07 - gateway API 타임아웃 완전 해결
Anthropic·OpenAI API를 1000Mbps로 지연 없이 연결
10년 이상 안정 운영. OpenClaw gateway의 가장 흔한 문제인 API 타임아웃은 해외 서버까지의 네트워크 품질이 원인입니다. VPN07의 70개국 IEPL 전용선으로 Anthropic·OpenAI API 서버에 최단 경로로 연결해 gateway timeout 오류를 원천 차단합니다. 국제 대역폭 1000Mbps로 모든 명령이 즉각 응답합니다.