Skip to main content

​
게이트웨이 런북

이 페이지는 게이트웨이 서비스의 초기 시작 및 두 번째 단계 운영에 사용됩니다.

심층 문제 해결

증상 중심의 진단, 명확한 명령어 단계 및 로그 특성.

설정

작업 지향 설정 가이드 + 전체 설정 참조.

Secrets 관리

SecretRef 계약, 런타임 스냅샷 동작, migrate/reload 작업.

Secrets plan 계약

secrets apply의 정확한 target/path 규칙과 ref-only auth-profile 동작.

​
5분 내 로컬 시작

1

게이트웨이 시작

2

서비스 상태 확인

건강한 기준선: Runtime: running 그리고 RPC probe: ok.
3

채널 준비 상태 확인

게이트웨이 설정 리로드는 활성 설정 파일 경로(프로파일/상태 기본값에서 해결되거나 OPENCLAW_CONFIG_PATH로 설정된 경로)를 감시합니다. 기본 모드는 gateway.reload.mode="hybrid"입니다.

​
런타임 모델

  • 항상 실행되는 프로세스로 라우팅, 제어 평면 및 채널 연결을 처리.
  • 다음을 위한 단일 멀티플렉스 포트:
    • WebSocket 제어/RPC
    • HTTP APIs (OpenAI 호환, 응답, 도구 호출)
    • 제어 UI 및 훅
  • 기본 바인드 모드: 로컬 루프백.
  • 인증은 기본적으로 필요(gateway.auth.token / gateway.auth.password, 또는 OPENCLAW_GATEWAY_TOKEN / OPENCLAW_GATEWAY_PASSWORD).

​
포트 및 바인드 우선순위

​
핫 리로드 모드

​
운영자 명령 세트

​
원격 액세스

선호: Tailscale/VPN. 대체: SSH 터널.
그런 다음 클라이언트를 로컬에서 ws://127.0.0.1:18789에 연결합니다.
게이트웨이 인증이 설정된 경우, 클라이언트는 SSH 터널을 통해서도 인증(token/password)을 보내야 합니다.
참조: 원격 게이트웨이, 인증, Tailscale.

​
감시 및 서비스 라이프사이클

상용 환경과 유사한 신뢰성을 위해 감시 실행을 사용하십시오.
LaunchAgent 레이블은 기본적으로 ai.openclaw.gateway 이며, 이름이 지정된 프로파일일 경우 ai.openclaw.<profile>. openclaw doctor는 서비스 설정 드리프트를 검사 및 수정합니다.

​
하나의 호스트에 여러 게이트웨이

대부분의 설정은 하나의 게이트웨이를 실행해야 합니다. 엄격한 격리 또는 중복성을 위해 여러 게이트웨이를 사용할 수 있습니다 (예: 구출 프로필). 인스턴스별 체크리스트:
  • 고유한 gateway.port
  • 고유한 OPENCLAW_CONFIG_PATH
  • 고유한 OPENCLAW_STATE_DIR
  • 고유한 agents.defaults.workspace
예시:
참조: 여러 게이트웨이.

​
Dev 프로필 빠른 경로

기본값에는 격리된 상태/설정과 기본 게이트웨이 포트 19001이 포함되어 있습니다.

​
프로토콜 빠른 참조 (운영자 관점)

  • 클라이언트의 첫 프레임은 connect 여야 합니다.
  • 게이트웨이는 hello-ok 스냅샷(presence, health, stateVersion, uptimeMs, 제한/정책)을 반환합니다.
  • 요청: req(method, params) → res(ok/payload|error).
  • 일반 이벤트: connect.challenge, agent, chat, presence, tick, health, heartbeat, shutdown.
에이전트 실행은 두 단계로 진행됩니다:
  1. 즉각적인 수락 확인 (status:"accepted")
  2. 최종 완료 응답 (status:"ok"|"error"), 중간에 스트리밍된 agent 이벤트 포함.
전체 프로토콜 문서 참조: 게이트웨이 프로토콜.

​
운영 점검

​
활성 상태 확인

  • WS를 열고 connect를 전송합니다.
  • 스냅샷과 함께 hello-ok 응답을 기대합니다.

​
준비 상태 확인

​
간극 복구

이벤트는 재생되지 않습니다. 시퀀스 간극이 발생하면 상태(health, system-presence)를 갱신한 후 계속합니다.

​
일반적인 실패 시그니처

전체 진단 단계는 게이트웨이 문제 해결을 참조하십시오.

​
안전 보장

  • 게이트웨이 프로토콜 클라이언트는 게이트웨이를 사용할 수 없을 때 빠르게 실패합니다(암시적인 직접 채널 백업 없음).
  • 잘못된 메시지나 연결이 아닌 첫 프레임은 거부되고 소켓이 닫힙니다.
  • 정상적인 종료: 소켓 닫힘 전 shutdown 이벤트 발생.
관련 항목: