Gateway 런북

이 페이지는 Gateway 서비스의 1일 차 시작과 2일 차 운영에 사용하세요.

5분 로컬 시작

openclaw gateway --port 18789# debug/trace mirrored to stdioopenclaw gateway --port 18789 --verbose# force-kill listener on selected port, then startopenclaw gateway --force

openclaw gateway statusopenclaw statusopenclaw logs --follow

openclaw channels status --probe

런타임 모델

• 라우팅, 컨트롤 플레인, 채널 연결을 위한 항상 켜져 있는 프로세스 하나입니다.
• 다음을 위한 단일 다중화 포트:
  • 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)를 사용하며, non-loopback reverse-proxy 설정은 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는 항상 구성된 기본 에이전트에 매핑되는 안정적인 별칭입니다.
• 백엔드 제공자/모델 재정의가 필요할 때는 x-openclaw-model을 사용하세요. 그렇지 않으면 선택된 에이전트의 일반 모델 및 임베딩 설정이 계속 제어합니다.

이 모든 항목은 기본 Gateway 포트에서 실행되며 나머지 Gateway HTTP API와 동일한 신뢰할 수 있는 운영자 인증 경계를 사용합니다.

포트 및 바인드 우선순위

설치된 Gateway 서비스는 해석된 --port를 supervisor 메타데이터에 기록합니다. gateway.port를 변경한 후에는 launchd/systemd/schtasks가 새 포트에서 프로세스를 시작하도록 openclaw doctor --fix 또는 openclaw gateway install --force를 실행하세요.

Gateway 시작은 non-loopback 바인드용 로컬 제어 UI origin을 시드할 때 동일한 유효 포트와 바인드를 사용합니다. 예를 들어 --bind lan --port 3000은 런타임 검증이 실행되기 전에 http://localhost:3000 및 http://127.0.0.1:3000을 시드합니다. HTTPS 프록시 URL 같은 원격 브라우저 origin은 gateway.controlUi.allowedOrigins에 명시적으로 추가하세요.

핫 리로드 모드

운영자 명령 집합

openclaw gateway statusopenclaw gateway status --deep   # adds a system-level service scanopenclaw gateway status --jsonopenclaw gateway installopenclaw gateway restartopenclaw gateway stopopenclaw secrets reloadopenclaw logs --followopenclaw doctor

gateway status --deep는 더 깊은 RPC 상태 프로브가 아니라 추가 서비스 탐색(LaunchDaemons/systemd 시스템 units/schtasks)을 위한 것입니다.

여러 Gateway(동일 호스트)

대부분의 설치는 머신당 하나의 Gateway를 실행해야 합니다. 단일 Gateway는 여러 에이전트와 채널을 호스트할 수 있습니다.

의도적으로 격리 또는 구조 봇을 원할 때만 여러 Gateway가 필요합니다.

유용한 확인:

openclaw gateway status --deepopenclaw gateway probe

예상 동작:

• gateway status --deep는 오래된 launchd/systemd/schtasks 설치가 아직 남아 있을 때 Other gateway-like services detected (best effort)를 보고하고 정리 힌트를 출력할 수 있습니다.
• gateway probe는 둘 이상의 대상이 응답할 때 multiple reachable gateways에 대해 경고할 수 있습니다.
• 의도한 경우 각 Gateway별로 포트, 구성/상태, workspace 루트를 격리하세요.

인스턴스별 체크리스트:

• 고유한 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 19001OPENCLAW_CONFIG_PATH=~/.openclaw/b.json OPENCLAW_STATE_DIR=~/.openclaw-b openclaw gateway --port 19002

자세한 설정: /gateway/multiple-gateways.

원격 접근

권장: Tailscale/VPN. 대안: SSH 터널.

ssh -N -L 18789:127.0.0.1:18789 user@host

그런 다음 클라이언트를 로컬에서 ws://127.0.0.1:18789에 연결하세요.

참조: 원격 Gateway, 인증, Tailscale.

감독 및 서비스 수명 주기

프로덕션과 유사한 안정성을 위해 감독 실행을 사용하세요.

openclaw gateway installopenclaw gateway statusopenclaw gateway restartopenclaw gateway stop

openclaw gateway installsystemctl --user enable --now openclaw-gateway[-<profile>].serviceopenclaw gateway status

sudo loginctl enable-linger <user>

[Unit]Description=OpenClaw GatewayAfter=network-online.targetWants=network-online.target [Service]ExecStart=/usr/local/bin/openclaw gateway --port 18789Restart=alwaysRestartSec=5TimeoutStopSec=30TimeoutStartSec=30SuccessExitStatus=0 143KillMode=control-group [Install]WantedBy=default.target

openclaw gateway installopenclaw gateway status --jsonopenclaw gateway restartopenclaw gateway stop

sudo systemctl daemon-reloadsudo systemctl enable --now openclaw-gateway[-<profile>].service

개발 프로필 빠른 경로

openclaw --dev setupopenclaw --dev gateway --allow-unconfiguredopenclaw --dev status

기본값에는 격리된 상태/구성과 기본 Gateway 포트 19001이 포함됩니다.

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

• 첫 번째 클라이언트 프레임은 connect여야 합니다.
• Gateway는 hello-ok 스냅샷(presence, health, stateVersion, uptimeMs, limits/policy)을 반환합니다.
• hello-ok.features.methods / events는 보수적인 탐색 목록이며, 호출 가능한 모든 helper route의 생성된 덤프가 아닙니다.
• 요청: req(method, params) → res(ok/payload|error).
• 일반 이벤트에는 connect.challenge, agent, chat, session.message, session.tool, sessions.changed, presence, tick, health, heartbeat, 페어링/승인 수명 주기 이벤트, shutdown이 포함됩니다.

에이전트 실행은 2단계입니다.

1. 즉시 수락 ack(status:"accepted")
2. 최종 완료 응답(status:"ok"|"error"), 그 사이에 agent 이벤트가 스트리밍됩니다.

전체 프로토콜 문서 참조: Gateway 프로토콜.

운영 확인

Liveness

• WS를 열고 connect를 보냅니다.
• 스냅샷이 포함된 hello-ok 응답을 예상합니다.

Readiness

openclaw gateway statusopenclaw channels status --probeopenclaw health

갭 복구

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

일반적인 실패 시그니처

전체 진단 단계는 Gateway 문제 해결을 사용하세요.

안전 보장

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

관련 항목:

• 문제 해결
• 백그라운드 프로세스
• 구성
• 상태
• 진단
• 인증

관련 항목

• 구성
• Gateway 문제 해결
• 원격 액세스
• 비밀 정보 관리