Gateway 운영 지침서

이 페이지는 Gateway 서비스의 첫날 시작과 이후 운영에 사용하십시오.

5분 로컬 시작

openclaw gateway --port 18789# 디버그/추적을 stdio에 미러링openclaw gateway --port 18789 --verbose# 선택한 포트의 리스너를 강제 종료한 다음 시작openclaw gateway --force

openclaw gateway statusopenclaw statusopenclaw logs --follow

openclaw channels status --probe

런타임 모델

• 라우팅, 제어 영역, 채널 연결을 위한 상시 실행 프로세스 하나입니다.
• 다음 용도의 단일 다중화 포트:
  • WebSocket 제어/RPC
  • HTTP API (/v1/models, /v1/embeddings, /v1/chat/completions, /v1/responses, /tools/invoke)
  • 선택적 /api/v1/admin/rpc와 같은 Plugin HTTP 경로
  • 제어 UI 및 훅
• 기본 바인드 모드: loopback. 감지된 컨테이너 환경에서는 포트 전달을 위해 0.0.0.0으로 확인되는 auto가 유효 기본값입니다. 단, Tailscale serve/funnel이 활성 상태이면 항상 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는 항상 구성된 기본 에이전트에 매핑되는 안정적인 별칭입니다. 백엔드 제공자/모델을 재정의하려면 x-openclaw-model을 보내십시오. 그렇지 않으면 선택한 에이전트의 일반 모델 및 임베딩 설정이 제어권을 유지합니다.

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

관리자 HTTP RPC(POST /api/v1/admin/rpc)는 WebSocket RPC를 사용할 수 없는 호스트 도구를 위한 별도의 기본 비활성화 Plugin 경로입니다. 관리자 HTTP RPC를 참조하십시오.

포트 및 바인드 우선순위

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

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

핫 다시 로드 모드

운영자 명령 집합

openclaw gateway statusopenclaw gateway status --deep   # 시스템 수준 서비스 검색 추가openclaw gateway status --jsonopenclaw gateway installopenclaw gateway restartopenclaw gateway stopopenclaw secrets reloadopenclaw logs --followopenclaw doctor

gateway status --deep은 더 심층적인 RPC 상태 프로브가 아니라 추가 서비스 검색(LaunchDaemons/systemd 시스템 단위/schtasks)을 위한 것입니다.

여러 Gateway(동일 호스트)

대부분의 설치에서는 머신당 하나의 Gateway를 실행해야 합니다. 단일 Gateway가 여러 에이전트와 채널을 호스팅할 수 있습니다. 의도적으로 격리하거나 구조용 봇이 필요한 경우에만 여러 Gateway가 필요합니다.

유용한 검사:

openclaw gateway status --deepopenclaw gateway probe

예상되는 결과:

• 오래된 launchd/systemd/schtasks 설치가 아직 남아 있으면 gateway status --deep이 Other gateway-like services detected (best effort)를 보고하고 정리 힌트를 출력할 수 있습니다.
• 서로 다른 Gateway가 응답하거나 OpenClaw가 도달 가능한 대상이 동일한 Gateway임을 입증할 수 없으면 gateway probe가 multiple reachable gateway identities를 경고할 수 있습니다. 동일한 Gateway에 대한 SSH 터널, 프록시 URL 또는 구성된 원격 URL은 전송 포트가 다르더라도 여러 전송 방식을 사용하는 하나의 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 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@gateway-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 $(whoami)

[Unit]Description=OpenClaw GatewayAfter=network-online.targetWants=network-online.targetStartLimitBurst=5StartLimitIntervalSec=60 [Service]ExecStart=/usr/local/bin/openclaw gateway --port 18789Restart=alwaysRestartSec=5RestartPreventExitStatus=78TimeoutStopSec=30TimeoutStartSec=30SuccessExitStatus=0 143OOMPolicy=continueKillMode=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

잘못된 구성 오류는 코드 78로 종료됩니다. Linux systemd 단위는 구성이 수정될 때까지 다시 실행하지 않도록 RestartPreventExitStatus=78을 사용합니다. launchd와 Windows Task Scheduler에는 종료 코드별로 중지하는 동등한 규칙이 없으므로, Gateway는 빠르게 반복되는 비정상 부팅 기록도 영구 저장하고 시작 실패가 반복되면 채널/제공자 계정 자동 시작을 억제합니다. 해당 안전 모드에서도 검사와 복구를 위한 제어 영역은 계속 시작되며, 구성 핫 다시 로드와 secrets.reload는 자동 채널 다시 시작을 거부하고, 명시적인 운영자 channels.start 요청으로 억제를 재정의할 수 있습니다.

개발 프로필 빠른 경로

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

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

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

• 첫 번째 클라이언트 프레임은 connect여야 합니다.
• Gateway는 snapshot(presence, health, stateVersion, uptimeMs)과 policy 제한(maxPayload, maxBufferedBytes, tickIntervalMs)이 포함된 hello-ok 프레임을 반환합니다.
• hello-ok.features.methods / events는 보수적인 검색 목록이며, 호출 가능한 모든 헬퍼 경로를 생성하여 덤프한 목록이 아닙니다.
• 요청: req(method, params) → res(ok/payload|error).
• 일반적인 이벤트에는 connect.challenge, agent, chat, session.message, session.operation, session.tool, 옵트인 방식의 session.approval, sessions.changed, presence, tick, health, heartbeat, 페어링/승인 수명 주기 이벤트, shutdown이 포함됩니다.

에이전트 실행은 2단계로 이루어집니다.

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

전체 프로토콜 문서는 Gateway 프로토콜을 참조하십시오.

운영 점검

활성 상태

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

준비 상태

openclaw gateway statusopenclaw channels status --probeopenclaw health

간격 복구

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

일반적인 오류 징후

전체 진단 절차는 Gateway 문제 해결을 참조하십시오.

안전 보장

• Gateway를 사용할 수 없으면 Gateway 프로토콜 클라이언트가 즉시 실패합니다(암시적인 직접 채널 대체 경로 없음).
• 유효하지 않거나 연결 프레임이 아닌 첫 번째 프레임은 거부되고 연결이 종료됩니다.
• 정상 종료 시 소켓이 닫히기 전에 shutdown 이벤트가 발생합니다.

관련 문서

• 구성
• Gateway 문제 해결
• 백그라운드 프로세스
• 상태 확인
• Doctor
• 인증
• 원격 액세스
• 보안 비밀 관리