openclaw doctor --non-interactive와 openclaw config validate를 병합 게이트로 사용합니다. 모든 동작은 공식 문서(설정 참조, CLI doctor, 게이트웨이 doctor)를 기준으로 합니다.
목표: 루프백 전용 컨트롤 플레인으로 노출 표면 최소화
OpenClaw 게이트웨이는 기본적으로 18789 포트에서 WebSocket과 HTTP를 다중화합니다. 설정 참조에 따르면 gateway.bind: "loopback"은 리스너를 로컬 루프백 주소에 고정하며, 비루프백 바인딩은 게이트웨이 인증 활성화가 필요합니다(토큰, 패스워드 또는 엄격하게 설정된 신뢰 프록시). 공유 원격 Mac의 경우 최적 방안은 루프백 바인딩 + 토큰 모드로, 운영자와 자동화 도구가 암호화된 터널을 통해 해당 포트에 접근하며, 18789를 호스트의 공인 인터페이스에 노출하지 않는 것입니다.
본 시리즈의 다른 글과 함께 읽으세요: nozcloud 독일 노드의 OpenClaw: 데몬 온보딩 및 컴플라이언스 기준선. 구매 또는 설정 변경은 구매 페이지에서, 플랜 비교는 가격 페이지에서 확인하세요.
최소 재현 단계 (원격 Mac)
먼저 테스트 머신에서 아래 프로세스를 실행하고 검증이 완료된 후 동일한 plist, SSH 설정 및 CI 작업을 운영 환경에 배포하는 것을 권장합니다.
- SSH 기본 설정. OpenClaw를 위한 전용 macOS 사용자를 생성하세요. 승인된 OpenClaw 버전만 설치하고, 키 기반 인증으로 비대화형 SSH를 검증하세요(정책이 허용하는 경우 해당 계정에 대해
sshd_config에서 패스워드 인증을 비활성화). - JSON5에서 바인딩 및 인증 선언.
~/.openclaw/openclaw.json에서gateway.mode: "local"을 유지하고,gateway.bind: "loopback"을 설정하며,gateway.auth.mode: "token"과gateway.auth.token: "${OPENCLAW_GATEWAY_TOKEN}"을 설정하세요. token과 password 객체가 동시에 존재하는 경우 시작 시 모호성을 피하기 위해 반드시gateway.auth.mode를 명시적으로 지정하세요. - 시크릿 경로를 Git에 커밋하지 말고 토큰을 주입하세요. LaunchDaemon의
EnvironmentVariables딕셔너리나 엄격한 POSIX 권한을 가진 root 소유 환경 파일을 통해OPENCLAW_GATEWAY_TOKEN을 내보내세요. 첫 부팅 시 안전한 관리자 셸에서openclaw doctor --generate-gateway-token을 실행할 수 있습니다. - TTY 없는 상태 확인.
openclaw config validate와openclaw doctor --non-interactive를 순서대로 실행하세요.--non-interactive는 대화형 프롬프트를 건너뛰고 보안 마이그레이션을 적용하며 대화형 OAuth 새로고침을 방지합니다 — cron 및 CI 환경에 매우 적합합니다. - 게이트웨이 서비스 설치 또는 재시작. 벤더의 표준화된 절차(예: 고정된 매개변수를 사용하는
openclaw gateway install)를 사용하세요.openclaw gateway status가 리스너가 루프백 주소에서만 정상 상태임을 표시하는지 확인하세요. - 로컬 워크스테이션에서 SSH LocalForward 설정.
ssh -N -L 18789:127.0.0.1:18789 openclaw-svc@germany-host.example를 실행하세요(사용자명과 호스트명을 교체하세요). 로컬 도구에서ws://127.0.0.1:18789에 접근할 수 있으며, 트래픽은 SSH 암호화로 전송됩니다. - 토큰 경로 검증. 터널 설정 후 운영 매뉴얼의 Bearer Token 방식으로 노트북에서
127.0.0.1:18789에 연결하세요. 의도적으로 잘못된 토큰을 전송해 보세요: 자동 통과가 아닌 인증 실패가 표시되어야 합니다 — 이것이 종단 간 강제 검증의 증거입니다.
0.0.0.0에 개방하면 서비스 검색 및 무차별 대입 공격의 위험이 크게 증가합니다. 비SSH 접근이 필요한 경우 mTLS 또는 Tailscale Serve가 활성화된 강화된 리버스 프록시를 앞에 배치하고, 인증을 우회하는 대신 설정 참조의 신뢰 프록시 섹션을 다시 읽으세요.
컴플라이언스 지향 노출 표면 점검 체크리스트
아래 항목은 법적 조언이 아닙니다; '최소 권한' 원칙을 보안 감사자가 확인할 수 있는 구체적인 게이트 포인트로 변환한 것입니다.
- 셸 히스토리에 평문 토큰 저장 금지: LaunchDaemon이나 CI 시크릿 주입기를 통해 시크릿을 로드하고, 공유 화면 세션에서 인라인
export를 절대 하지 마세요. - 운영 SSH 계정과 서비스 계정 분리: 운영자는 각자의 UNIX 주체를 사용하고, OpenClaw 데몬 사용자는 개인 dotfiles를 소유하지 않아야 합니다.
- PR에서 게이트웨이 설정 변경 검토:
gateway.bind,gateway.auth,hooks또는gateway.http엔드포인트 관련 수정은 모두 2인 검토가 필요합니다. - doctor 수정 전 설정 백업: 업그레이드 전 타임스탬프가 있는
openclaw.json사본을 보관하세요; 마이그레이션으로 인증 메타데이터가 손실된 경우 아티팩트 저장소에서 복원하고 서비스를 재시작하세요. - 긴급 작업 절차 문서화: 인시던트 대응 중 누군가가 일시적으로 바인딩 모드를 완화한 경우 즉시 티켓을 제출하고 SLA 기간 내에 롤백하세요.
병합 게이트 방안 (GitHub Actions 의사코드 예시)
운영 설정의 읽기 전용 고정본 또는 익명화된 발췌본을 Git에 저장하세요 — 운영 토큰은 절대 커밋하지 마세요. CI 시크릿을 통해 일회용 OPENCLAW_GATEWAY_TOKEN을 주입하여 환경 변수 치환이 필요한 검증 경로가 올바르게 실행될 수 있도록 하세요. 이 작업에는 다음 단계가 포함되어야 합니다:
- 운영 환경과 동일한 OpenClaw 마이너 버전을 설치합니다.
- 커밋된 템플릿과 테스트 시크릿의 병합 결과에
openclaw config validate를 적용합니다. openclaw doctor --non-interactive를 실행하고 경고가 정책 임계값을 초과하면 실패 처리합니다(많은 팀이 '인증 누락' 항목을 하드 에러로 처리합니다).- 선택 사항: 매 PR이 아닌 야간에
openclaw doctor --deep을 실행 — 심층 스캔은 시간이 더 걸리고 권한 상승이 필요할 수 있습니다.
업그레이드 문제는 내부 운영 매뉴얼을 따르세요; 리소스 프로비저닝이나 SSH 접근에 어려움이 있는 경우 아래 도움말 센터 링크를 통해 티켓을 제출하세요.