게이트웨이 런북

이 페이지는 게이트웨이 서비스의 첫날 시작과 둘째 날 운영을 위해 사용합니다.

• 심층 문제 해결 — 증상 우선 진단과 정확한 명령어 사다리 및 로그 서명.
• 설정 — 작업 중심 설정 가이드 + 전체 설정 레퍼런스.
• 시크릿 관리 — SecretRef 계약, 런타임 스냅샷 동작, 마이그레이션/리로드 작업.
• 시크릿 플랜 계약 — 정확한 secrets apply 대상/경로 규칙과 ref 전용 인증 프로필 동작.

5분 로컬 시작

1단계: 게이트웨이 시작

openclaw gateway --port 18789
# stdio로 미러링되는 디버그/트레이스
openclaw gateway --port 18789 --verbose
# 선택한 포트의 리스너를 강제 종료 후 시작
openclaw gateway --force

2단계: 서비스 상태 확인

openclaw gateway status
openclaw status
openclaw logs --follow

정상 기준: Runtime: running 및 RPC probe: ok.

3단계: 채널 준비 상태 확인

openclaw channels status --probe

참고: 게이트웨이 설정 리로드는 활성 설정 파일 경로(프로필/상태 기본값에서 해석되거나 OPENCLAW_CONFIG_PATH가 설정된 경우 해당 경로)를 감시합니다. 기본 모드는 gateway.reload.mode="hybrid"입니다.

런타임 모델

• 라우팅, 제어 플레인, 채널 연결을 위한 항시 가동 프로세스.
• 단일 다중화 포트:
  • WebSocket 제어/RPC
  • HTTP API (OpenAI 호환, Responses, 도구 호출)
  • 제어 UI 및 웹훅
• 기본 바인딩 모드: loopback.
• 기본적으로 인증 필요 (gateway.auth.token / gateway.auth.password, 또는 OPENCLAW_GATEWAY_TOKEN / OPENCLAW_GATEWAY_PASSWORD).

포트 및 바인딩 우선순위

핫 리로드 모드

오퍼레이터 명령어 세트

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

원격 접근

권장: Tailscale/VPN. 폴백: SSH 터널.

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

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

경고: 게이트웨이 인증이 설정된 경우, SSH 터널을 통해서도 클라이언트는 여전히 인증(token/password)을 전송해야 합니다.

참조: 원격 게이트웨이, 인증, Tailscale.

슈퍼비전 및 서비스 라이프사이클

프로덕션 수준의 안정성을 위해 감독 실행을 사용합니다.

macOS (launchd)

openclaw gateway install
openclaw gateway status
openclaw gateway restart
openclaw gateway stop

LaunchAgent 레이블은 ai.openclaw.gateway (기본값) 또는 ai.openclaw.<profile> (이름 있는 프로필)입니다. openclaw doctor는 서비스 설정 드리프트를 감사하고 수리합니다.

Linux (systemd 사용자)

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

로그아웃 후 지속을 위해 linger를 활성화합니다:

sudo loginctl enable-linger <user>

Linux (시스템 서비스)

다중 사용자/항시 가동 호스트에는 시스템 유닛을 사용합니다.

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

단일 호스트에서 여러 게이트웨이

대부분의 설정은 하나의 게이트웨이를 실행해야 합니다. 엄격한 격리/중복성이 필요한 경우에만 여러 개를 사용합니다 (예: 구조 프로필).

인스턴스별 체크리스트:

• 고유한 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

참조: 여러 게이트웨이.

개발 프로필 빠른 경로

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

기본값에는 격리된 상태/설정 및 기본 게이트웨이 포트 19001이 포함됩니다.

프로토콜 빠른 참조 (오퍼레이터 관점)

• 첫 번째 클라이언트 프레임은 connect여야 합니다.
• 게이트웨이는 hello-ok 스냅샷(presence, health, stateVersion, uptimeMs, 제한/정책)을 반환합니다.
• 요청: req(method, params) → res(ok/payload|error).
• 일반적인 이벤트: connect.challenge, agent, chat, presence, tick, health, heartbeat, shutdown.

에이전트 실행은 2단계:

1. 즉시 수락 확인 (status:"accepted")
2. 최종 완료 응답 (status:"ok"|"error"), 중간에 스트리밍 agent 이벤트.

전체 프로토콜 문서: 게이트웨이 프로토콜.

운영 점검

활성 상태

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

준비 상태

openclaw gateway status
openclaw channels status --probe
openclaw health

갭 복구

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

일반적인 장애 서명

전체 진단 사다리는 게이트웨이 문제 해결을 사용하세요.

안전 보장

• 게이트웨이 프로토콜 클라이언트는 게이트웨이를 사용할 수 없는 경우 빠르게 실패합니다 (암시적 직접 채널 폴백 없음).
• 유효하지 않은/비연결 첫 프레임은 거부되고 닫힙니다.
• 정상 종료 시 소켓 닫기 전에 shutdown 이벤트를 발생시킵니다.

관련:

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