Gateway 런북

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

# 5분 로컬 시작

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

openclaw gateway status
openclaw status
openclaw 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 리버스 프록시 설정은 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를 감독자 메타데이터에 기록합니다. gateway.port를 변경한 후에는 launchd/systemd/schtasks가 새 포트에서 프로세스를 시작하도록 openclaw doctor --fix 또는 openclaw gateway install --force를 실행하세요.

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

# 핫 다시 로드 모드

# 운영자 명령 집합

openclaw gateway status
openclaw gateway status --deep   # adds a system-level service scan
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는 오래된 launchd/systemd/schtasks 설치가 아직 남아 있으면 Other gateway-like services detected (best effort)를 보고하고 정리 힌트를 출력할 수 있습니다.
• 둘 이상의 대상이 응답하면 gateway probe가 multiple reachable gateways에 대해 경고할 수 있습니다.
• 이것이 의도된 경우 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/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 install
openclaw gateway status
openclaw gateway restart
openclaw gateway stop

openclaw gateway install
systemctl --user enable --now openclaw-gateway[-<profile>].service
openclaw gateway status

sudo loginctl enable-linger <user>

[Unit]
Description=OpenClaw Gateway
After=network-online.target
Wants=network-online.target

[Service]
ExecStart=/usr/local/bin/openclaw gateway --port 18789
Restart=always
RestartSec=5
TimeoutStopSec=30
TimeoutStartSec=30
SuccessExitStatus=0 143
KillMode=control-group

[Install]
WantedBy=default.target

openclaw gateway install
openclaw gateway status --json
openclaw gateway restart
openclaw gateway stop

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

# 개발 프로필 빠른 경로

openclaw --dev setup
openclaw --dev gateway --allow-unconfigured
openclaw --dev status

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

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

• 첫 번째 클라이언트 프레임은 connect여야 합니다.
• Gateway는 hello-ok 스냅샷(presence, health, stateVersion, uptimeMs, 제한/정책)을 반환합니다.
• 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. 즉시 수락 ack(status:"accepted")
2. 최종 완료 응답(status:"ok"|"error"), 그 사이에 스트리밍되는 agent 이벤트 포함.

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

# 운영 확인

# 활성 상태

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

# 준비 상태

openclaw gateway status
openclaw channels status --probe
openclaw health

# 간격 복구

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

# 일반적인 실패 시그니처

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

# 안전 보장

• Gateway 프로토콜 클라이언트는 Gateway를 사용할 수 없을 때 즉시 실패합니다(암시적인 직접 채널 대체 경로 없음).
• 잘못되었거나 connect가 아닌 첫 프레임은 거부되고 닫힙니다.
• 정상 종료는 소켓이 닫히기 전에 shutdown 이벤트를 내보냅니다.

관련:

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

# 관련

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