메인 콘텐츠로 건너뛰기

​
Gateway 런북

이 페이지는 Gateway 서비스의 첫날 시작 작업과 이후 운영 작업에 사용합니다.

심층 문제 해결

증상 우선 진단과 정확한 명령 단계 및 로그 시그니처를 제공합니다.

구성

작업 중심 설정 가이드 + 전체 구성 참조입니다.

시크릿 관리

SecretRef 계약, 런타임 스냅샷 동작, 마이그레이션/리로드 작업을 설명합니다.

시크릿 계획 계약

정확한 secrets apply 대상/경로 규칙과 ref-only auth-profile 동작을 설명합니다.

​
5분 로컬 시작

1

Gateway 시작

openclaw gateway --port 18789
# debug/trace를 stdio로 미러링
openclaw gateway --port 18789 --verbose
# 선택한 포트의 리스너를 강제 종료한 다음 시작
openclaw gateway --force
2

서비스 상태 확인

openclaw gateway status
openclaw status
openclaw logs --follow
정상 기준: Runtime: running, Connectivity probe: ok, 그리고 기대한 값과 일치하는 Capability: ...가 표시됩니다. 단순한 도달 가능성뿐 아니라 읽기 범위 RPC 증명이 필요할 때는 openclaw gateway status --require-rpc를 사용하세요.
3

채널 준비 상태 검증

openclaw channels status --probe
연결 가능한 Gateway가 있으면 계정별 실시간 채널 프로브와 선택적 감사를 실행합니다. Gateway에 연결할 수 없으면 CLI는 실시간 프로브 출력 대신 구성 전용 채널 요약으로 대체합니다.
Gateway 구성 리로드는 활성 구성 파일 경로를 감시합니다(프로필/상태 기본값에서 확인되거나, 설정된 경우 OPENCLAW_CONFIG_PATH 사용). 기본 모드는 gateway.reload.mode="hybrid"입니다. 첫 번째 로드가 성공한 후 실행 중 프로세스는 활성 메모리 내 구성 스냅샷을 제공하며, 리로드가 성공하면 해당 스냅샷을 원자적으로 교체합니다.

​
런타임 모델

  • 라우팅, 제어 플레인, 채널 연결을 위한 단일 상시 실행 프로세스입니다.
  • 다음을 위한 단일 다중화 포트:
    • WebSocket 제어/RPC
    • HTTP API, OpenAI 호환 (/v1/models, /v1/embeddings, /v1/chat/completions, /v1/responses, /tools/invoke)
    • 제어 UI 및 훅
  • 기본 바인드 모드: loopback.
  • 기본적으로 인증이 필요합니다. 공유 시크릿 구성은 gateway.auth.token / gateway.auth.password(또는 OPENCLAW_GATEWAY_TOKEN / OPENCLAW_GATEWAY_PASSWORD)를 사용하고, 비-루프백 리버스 프록시 구성은 gateway.auth.mode: "trusted-proxy"를 사용할 수 있습니다.

​
OpenAI 호환 엔드포인트

현재 OpenClaw의 가장 활용도 높은 호환 표면은 다음과 같습니다:
  • GET /v1/models
  • GET /v1/models/{id}
  • POST /v1/embeddings
  • POST /v1/chat/completions
  • POST /v1/responses
이 집합이 중요한 이유:
  • 대부분의 Open WebUI, LobeChat, LibreChat 통합은 먼저 /v1/models를 확인합니다.
  • 많은 RAG 및 메모리 파이프라인은 /v1/embeddings를 기대합니다.
  • 에이전트 중심 클라이언트는 점점 더 /v1/responses를 선호합니다.
계획 참고:
  • /v1/models는 에이전트 우선입니다: openclaw, openclaw/default, openclaw/<agentId>를 반환합니다.
  • openclaw/default는 항상 구성된 기본 에이전트에 매핑되는 안정적인 별칭입니다.
  • 백엔드 provider/model 재정의를 원할 때는 x-openclaw-model을 사용하세요. 그렇지 않으면 선택된 에이전트의 일반 모델 및 임베딩 설정이 계속 제어를 맡습니다.
이 모든 항목은 기본 Gateway 포트에서 실행되며, 나머지 Gateway HTTP API와 동일한 신뢰된 운영자 인증 경계를 사용합니다.

​
포트 및 바인드 우선순위

설정확인 순서
Gateway 포트--port → OPENCLAW_GATEWAY_PORT → gateway.port → 18789
바인드 모드CLI/재정의 → gateway.bind → loopback

​
핫 리로드 모드

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
gateway status --deep는 추가 서비스 검색용입니다(LaunchDaemons/systemd 시스템 유닛/schtasks). 더 심층적인 RPC 상태 프로브용은 아닙니다.

​
여러 Gateway(동일 호스트)

대부분의 설치에서는 머신당 하나의 Gateway를 실행해야 합니다. 하나의 Gateway로 여러 에이전트와 채널을 호스팅할 수 있습니다. 여러 Gateway가 필요한 경우는 의도적으로 격리나 구조용 봇을 원할 때뿐입니다. 유용한 확인 명령: 
openclaw gateway status --deep
openclaw gateway probe
예상 동작:
  • gateway status --deep는 Other gateway-like services detected (best effort)를 보고할 수 있으며, 오래된 launchd/systemd/schtasks 설치가 남아 있을 때 정리 힌트를 출력합니다.
  • 둘 이상의 대상이 응답하면 gateway probe가 multiple reachable gateways를 경고할 수 있습니다.
  • 이것이 의도된 경우 Gateway마다 포트, 구성/상태, 워크스페이스 루트를 분리하세요.
자세한 설정: /gateway/multiple-gateways.

​
원격 액세스

권장: Tailscale/VPN. 대안: SSH 터널. 
ssh -N -L 18789:127.0.0.1:18789 user@host
그런 다음 클라이언트를 로컬에서 ws://127.0.0.1:18789에 연결하세요.
SSH 터널은 Gateway 인증을 우회하지 않습니다. 공유 시크릿 인증의 경우 클라이언트는 터널을 통해서도 여전히 token/password를 보내야 합니다. 신원 포함 모드에서는 요청이 여전히 해당 인증 경로를 충족해야 합니다.
참고: 원격 Gateway, 인증, Tailscale.

​
감독 및 서비스 수명 주기

프로덕션 수준의 신뢰성을 위해 감독된 실행을 사용하세요. 
openclaw gateway install
openclaw gateway status
openclaw gateway restart
openclaw gateway stop
LaunchAgent 레이블은 ai.openclaw.gateway(기본값) 또는 ai.openclaw.<profile>(이름 있는 프로필)입니다. openclaw doctor는 서비스 구성 드리프트를 감사하고 복구합니다.

​
하나의 호스트에서 여러 Gateway

대부분의 구성은 하나의 Gateway를 실행해야 합니다. 엄격한 격리/중복성(예: 구조 프로필)을 위해서만 여러 개를 사용하세요. 인스턴스별 체크리스트:
  • 고유한 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
참고: 여러 Gateway.

​
dev 프로필 빠른 경로

openclaw --dev setup
openclaw --dev gateway --allow-unconfigured
openclaw --dev status
기본값에는 격리된 상태/구성과 기본 Gateway 포트 19001이 포함됩니다.

​
프로토콜 빠른 참조(운영자 보기)

  • 첫 번째 클라이언트 프레임은 반드시 connect여야 합니다.
  • Gateway는 hello-ok 스냅샷(presence, health, stateVersion, uptimeMs, limits/policy)을 반환합니다.
  • hello-ok.features.methods / events는 보수적인 검색 목록이며, 호출 가능한 모든 헬퍼 라우트를 자동 생성한 덤프가 아닙니다.
  • 요청: req(method, params) → res(ok/payload|error).
  • 일반 이벤트에는 connect.challenge, agent, chat, session.message, session.tool, sessions.changed, presence, tick, health, heartbeat, 페어링/승인 수명 주기 이벤트, shutdown이 포함됩니다.
에이전트 실행은 2단계입니다:
  1. 즉시 수락 확인 응답(status:"accepted")
  2. 최종 완료 응답(status:"ok"|"error"), 그 사이에 스트리밍되는 agent 이벤트 포함
전체 프로토콜 문서: Gateway 프로토콜.

​
운영 점검

​
라이브니스

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

​
레디니스

openclaw gateway status
openclaw channels status --probe
openclaw health

​
갭 복구

이벤트는 재생되지 않습니다. 시퀀스 갭이 있으면 계속하기 전에 상태를 새로 고치세요(health, system-presence).

​
일반적인 실패 시그니처

시그니처가능성 높은 문제
refusing to bind gateway ... without auth유효한 Gateway 인증 경로 없이 비-루프백 바인드 시도
another gateway instance is already listening / EADDRINUSE포트 충돌
Gateway start blocked: set gateway.mode=local구성이 원격 모드로 설정되었거나, 손상된 구성에서 로컬 모드 스탬프가 누락됨
unauthorized during connect클라이언트와 Gateway 간 인증 불일치
전체 진단 단계는 Gateway 문제 해결을 사용하세요.

​
안전 보장

  • Gateway 프로토콜 클라이언트는 Gateway를 사용할 수 없을 때 빠르게 실패합니다(암시적 직접 채널 대체 없음).
  • 유효하지 않거나 connect가 아닌 첫 프레임은 거부되고 연결이 닫힙니다.
  • 정상 종료 시 소켓이 닫히기 전에 shutdown 이벤트를 전송합니다.
관련 항목: