OpenClaw·루프백 게이트웨이가 있는 원격 Mac을 전제로 합니다. 개요는 홈, 설치·토큰은 고객센터 · OpenClaw 가이드, 전용 노드는 구매(로그인 불필요). IDE 브리지와 같이 읽기 전용 repo / 쓰기 scratch로 로그를 소스 밖에 두세요.
게이트웨이와 스킬 디렉터리
게이트웨이는 ~/.openclaw, 스킬은 ~/openclaw-skills/<name>/에 skill.yaml·schemas/·scripts/, 로그·임시 파일은 ~/openclaw-scratch/만 사용합니다.
- 스킬마다 매니페스트로 도구·정책·스키마 경로를 Git에 고정합니다.
- 토큰은
0600+OPENCLAW_TOKEN_FILE, 매니페스트에 시크릿 인라인 금지. - launchd
KeepAlive, 로그는~/openclaw-scratch/logs/gateway.log, plist는 매니페스트와 함께 버전 관리합니다.
변경 후 openclaw doctor --json > ~/openclaw-scratch/probe/doctor-last.json으로 기준선을 남깁니다.
스키마 검증 예시
모든 도구에 inputSchema(Draft-07 또는 2020-12, 빌드 검증기에 맞출 것). 검증은 실행 전에 끝내고, 실패 시 필드·타입·제약을 구조화해 모델이 수정하게 합니다.
임의 문자열·형식 남용을 막는 예:
{
"name": "linear.fetch_issue",
"description": "Linear 이슈를 안정 id로 조회",
"inputSchema": {
"type": "object",
"additionalProperties": false,
"required": ["issueId"],
"properties": {
"issueId": {
"type": "string",
"pattern": "^[A-Z]{2,10}-[0-9]+$",
"maxLength": 32
},
"includeComments": { "type": "boolean", "default": false }
}
}
}additionalProperties: false, maxLength/maxItems, 모드는 enum. 큰 스키마는 파일로 분리해 매니페스트에서 참조합니다. 실패 로그는 tool·correlationId·오류 경로만(페이로드 속 비밀 금지).
타임아웃·회로 차단 파라미터
타임아웃은 단일 호출 퓨즈, 회로 차단은 연속 실패·오류율로 하류 보호. 매니페스트 또는 policies.yaml에 기본값+도구별 오버라이드로 적습니다.
executionTimeoutMs: HTTP 8–30s, 저장소 스캔 60–120s 등부터 조정.queueWaitMs: 초과 시503 tool_backpressure로 병렬 폭주 완화.- 차단: 예) 연속 5회 실패 또는 60s 창 오류율 40% →
openDurationMs: 30000, 응답breaker_open. - 하프오픈으로 카나리 1회 허용해 자동 복구 시험.
SLO 변경 시 매니페스트 먼저, 그다음 게이트웨이 재배포. 숫자는 리뷰에서 도구 옆에 남깁니다.
재시도 백오프
부수 효과는 공통 템플릿 하나로: 지수 백오프+지터(읽기), 쓰기는 멱등 키·상한을 전제로만. API 호출 기본 예:
retry:
maxAttempts: 4
initialDelayMs: 200
multiplier: 2.0
maxDelayMs: 8000
jitterRatio: 0.2
retryOnHttpStatus: [408, 425, 429, 500, 502, 503, 504]
nonRetryOnHttpStatus: [401, 403, 404, 422]쓰기는 멱등 키, 서브프로세스는 idempotent: true+종료 코드 구분 없으면 자동 재시도 금지. 로그에 attempt·delayMs·errorClass·correlationId. 회로 오픈 시 재시도 생략하고 모델에 상태 전달.
로그로 살펴보는 FAQ
업그레이드 후 검증 폭주. unknown 키 로그 → 트래픽 정리 후 additionalProperties: false.
타임아웃인데 하류 정상. Mac에서 DNS/TLS, p95 대비 executionTimeoutMs, 콜드 스타트.
복구 후에도 차단. 하프오픈, 4xx/5xx 분리, 시계 동기, ECONNRESET 등 고착 오류.
재시도가 429 악화. Retry-After 준수, maxAttempts 하향.
성공 로그만 있고 효과 없음. 비동기 조기 반환 → 타임아웃 연장 또는 큐/폴링 도구 분리.
doctor 통과·런타임만 실패. 드라이런 카나리, 토큰 권한, launchd와 셸의 스킬 경로 일치.
요약: 경로 정규화 → 스키마 선검증 → 타임아웃·차단 → 공통 백오프 → correlation 로그. 원격 Mac에서도 같은 절차로 넘깁니다.
게이트웨이는 통제 가능한 전용 Mac에 두는 편이 안전합니다. 구매로 리전·사양을 보고, 고객센터에 런북을 두며, 준비되면 홈의 콘솔에서 프로비저닝하세요.