Gateway 실행 가이드 (Runbook)
이 페이지는 Gateway 서비스의 day-1 시작 절차와 day-2 운영 작업을 정리한 runbook입니다.심층 문제 해결
증상별 진단 사다리 및 로그 시그니처 분석 가이드.
설정 레퍼런스
작업 중심의 설정 가이드 및 전체 구성 요소 명세.
시크릿 관리
시크릿 참조(SecretRef) 규약, 런타임 스냅샷 동작 및 마이그레이션 안내.
시크릿 플랜 규약
secrets apply 명령어의 대상 경로 규칙 및 보안 정책 상세.5분 로컬 시작 가이드
1
Gateway 시작
2
서비스 상태 확인
Runtime: running 및 RPC probe: ok.3
채널 준비 상태 검증
Gateway 설정 재로드는 활성 설정 파일 경로를 감시합니다. 경로는 프로필/상태 기본값으로 해석되거나,
OPENCLAW_CONFIG_PATH가 설정된 경우 그 값을 사용합니다.
기본 모드는 gateway.reload.mode="hybrid"입니다.런타임 모델
- 라우팅, control plane, 채널 연결을 담당하는 상시 실행 프로세스 하나가 동작합니다.
- 하나의 멀티플렉싱 포트가 다음을 함께 처리합니다:
- WebSocket control/RPC
- HTTP API (OpenAI-compatible, Responses, tools invoke)
- Control UI 및 hooks
- 기본 bind mode는
loopback입니다. - 기본적으로 인증이 필요합니다(
gateway.auth.token/gateway.auth.password, 또는OPENCLAW_GATEWAY_TOKEN/OPENCLAW_GATEWAY_PASSWORD).
포트 및 바인딩 우선순위
핫 리로드 (Hot Reload) 모드
관리자 명령어 세트
원격 접속 (Remote Access)
- 권장 방식: Tailscale 또는 사설 VPN 사용.
- 차선책: SSH 터널링 활용.
ws://127.0.0.1:18789에 연결하세요.
참조: 원격 Gateway, 인증 가이드, Tailscale 연동.
서비스 감독 및 수명 주기 관리
실제 운영 환경의 안정성을 위해 운영체제별 서비스 관리 도구를 활용함.- macOS (launchd)
- Linux (systemd 사용자 유닛)
- Linux (시스템 서비스)
ai.openclaw.gateway (기본값) 또는 ai.openclaw.<프로필명>임. openclaw doctor 명령어로 서비스 설정의 편차(Drift)를 점검하고 복구할 수 있음.단일 호스트 내 다중 Gateway 운영
일반적인 환경에서는 하나의 Gateway만 운영할 것을 권장함. 엄격한 격리나 이중화(예: 복구용 프로필 운영)가 필요한 경우에만 추가 인스턴스를 구동함. 인스턴스별 필수 분리 항목:- 고유한
gateway.port. - 고유한
OPENCLAW_CONFIG_PATH(설정 파일). - 고유한
OPENCLAW_STATE_DIR(상태 디렉터리). - 고유한
agents.defaults.workspace(워크스페이스).
개발용 프로필 빠른 시작 (Dev Profile)
--dev 플래그 사용 시 격리된 상태 폴더와 기본 포트 19001이 자동으로 할당됨.
프로토콜 요약 (운영자 참조용)
- 클라이언트의 첫 프레임은 반드시
connect요청이어야 함. - 성공 시 Gateway는
hello-ok스냅샷(presence,health,stateVersion,uptimeMs, limits/policy`)을 반환함. - 요청/응답 구조:
req(method, params)→res(ok/payload|error). - 주요 이벤트:
connect.challenge,agent,chat,presence,tick,health,heartbeat,shutdown.
- 즉시 수락 확인 (
status: "accepted"). - 최종 완료 응답 (
status: "ok" | "error"). 그 사이 실시간agent스트림 이벤트가 전달됨.
운영 점검 항목
활성 상태 점검 (Liveness)
- WebSocket 연결 후
connect프레임 전송. - 스냅샷 정보가 포함된
hello-ok응답 수신 여부 확인.
준비 상태 점검 (Readiness)
메시지 간격 복구 (Gap Recovery)
과거 이벤트는 재현되지 않음. 시퀀스 갭이 감지되면 계속 진행하기 전 상태 정보(health, system-presence)를 새로 고쳐 데이터 일관성을 확보함.
일반적인 오류 패턴 (Failure Signatures)
상세 진단 절차는 Gateway 문제 해결 가이드 참조.
안전성 보장 (Safety Guarantees)
- Gateway 프로콜 클라이언트는 Gateway 서버가 불능 상태일 때 즉시 실패 처리함 (보안을 위해 채널 직접 접근 방식으로 자동 전환되지 않음).
- 유효하지 않거나
connect가 아닌 첫 번째 프레임은 즉시 차단 및 연결 종료됨. - 정상 종료(Graceful shutdown) 시 소켓이 닫히기 전
shutdown이벤트를 송출함.
관련 문서 목록: