메인 콘텐츠로 건너뛰기

​
게이트웨이 런북

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

심층 문제 해결

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

설정

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

Secrets 관리

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

Secrets plan 계약

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

​
5분 내 로컬 시작

1

게이트웨이 시작

openclaw gateway --port 18789
# debug/trace mirrored to stdio
openclaw gateway --port 18789 --verbose
# force-kill listener on selected port, then start
openclaw gateway --force
2

서비스 상태 확인

openclaw gateway status
openclaw status
openclaw logs --follow
건강한 기준선: Runtime: running 그리고 RPC probe: ok.
3

채널 준비 상태 확인

openclaw channels status --probe
게이트웨이 설정 리로드는 활성 설정 파일 경로(프로파일/상태 기본값에서 해결되거나 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).

​
포트 및 바인드 우선순위

설정해결 순서
게이트웨이 포트--port → OPENCLAW_GATEWAY_PORT → gateway.port → 18789
바인드 모드CLI/override → gateway.bind → 로컬 루프백

​
핫 리로드 모드

gateway.reload.mode동작
off설정 리로드 안 함
hot핫-세이프한 변경 만 적용
restart리로드가 필요한 변경 시 재시작
hybrid (기본)안전할 때 핫 적용, 필요 시 재시작

​
운영자 명령 세트

openclaw gateway status
openclaw gateway status --deep
openclaw gateway status --json
openclaw gateway install
openclaw gateway restart
openclaw gateway stop
openclaw secrets reload
openclaw logs --follow
openclaw doctor

​
원격 액세스

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

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

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

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

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

​
Dev 프로필 빠른 경로

openclaw --dev setup
openclaw --dev gateway --allow-unconfigured
openclaw --dev status
기본값에는 격리된 상태/설정과 기본 게이트웨이 포트 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 응답을 기대합니다.

​
준비 상태 확인

openclaw gateway status
openclaw channels status --probe
openclaw health

​
간극 복구

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

​
일반적인 실패 시그니처

시그니처가능성 있는 문제
refusing to bind gateway ... without auth인증 정보가 없는 비-로컬 루프백 바인드
another gateway instance is already listening / EADDRINUSE포트 충돌
Gateway start blocked: set gateway.mode=local원격 모드로 설정된 구성
unauthorized during connect클라이언트와 게이트웨이 간의 인증 불일치
전체 진단 단계는 게이트웨이 문제 해결을 참조하십시오.

​
안전 보장

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