​

Gateway 서비스 런북

​

5분 로컬 시작

openclaw gateway --port 18789
# for full debug/trace logs in stdio:
openclaw gateway --port 18789 --verbose
# if the port is busy, terminate listeners then start:
openclaw gateway --force
# dev loop (auto-reload on TS changes):
pnpm gateway:watch

openclaw --profile main gateway install
openclaw --profile rescue gateway install

openclaw channels status --probe

​

런타임 모델

• 라우팅, 제어 플레인 및 채널 연결을 위한 항상 실행되는 단일 프로세스.
• 단일 포트 멀티플렉스입니다.
  • WebSocket 제어/RPC
  • OpenResponses (HTTP): /v1/responses.
  • 제어 UI 및 훅
• 기본 바인드 모드: loopback.
• Gateway 인증은 기본적으로 필요합니다: gateway.auth.token (또는 OPENCLAW_GATEWAY_TOKEN) 또는 gateway.auth.password를 설정하십시오.

​

포트 및 바인드 우선순위

​

핫 리로드 모드

​

운영자 명령 세트

openclaw gateway status
openclaw gateway install
openclaw gateway stop
openclaw gateway restart
openclaw logs --follow

​

원격 접근

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

​

감독 및 서비스 수명 주기

재시작하려면 `openclaw gateway restart` (또는 `launchctl kickstart -k gui/$UID/bot.molt.gateway`)를 사용하십시오.

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

sudo loginctl enable-linger youruser

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

​

다중 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

​

Dev 프로필 (--dev)

openclaw --dev setup
openclaw --dev gateway --allow-unconfigured
# then target the dev instance:
openclaw --dev status
openclaw --dev health

​

프로토콜 (운영자 관점)

• 클라이언트는 재연결해야 합니다.
• Gateway는 hello-ok 스냅샷(presence, health, stateVersion, uptimeMs, limits/policy)을 반환합니다.
• 요청: {type:"req", id, method, params} → {type:"res", id, ok, payload|error}
• 일반 이벤트: connect.challenge, agent, chat, presence, tick, health, heartbeat, shutdown.

1. 즉시 수락 확인 응답(status:"accepted")
2. agent 응답은 2단계입니다: 먼저 res ack {runId,status:"accepted"}, 이후 실행이 끝나면 최종 res {runId,status:"ok"|"error",summary}; 스트리밍 출력은 event:"agent"로 도착합니다.

​

운영 점검

​

활성 상태 확인

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

​

준비 상태

`openclaw gateway health|status` — Gateway WS를 통해 상태/헬스를 요청합니다.

​

갭 복구

​

일반적인 실패 시그니처

​

안전 보장

• Gateway가 다운되면 전송은 즉시 실패합니다.
• 유효하지 않거나 connect가 아닌 첫 프레임은 거부되고 연결이 종료됩니다.
• 정상 종료: 닫기 전에 shutdown 이벤트를 발행합니다.

• Troubleshooting
• Background Process
• Configuration
• Health
• Doctor
• Authentication