Openclaw 동기화 API (Openclaw Sync API)

개요

Openclaw 동기화 API는 로컬 Openclaw 인스턴스와 GIIP 플랫폼 간의 양방향 데이터(설정 및 문서) 동기화를 지원하는 엔드포인트입니다. giipAgentWin이나 다른 로컬 에이전트가 주기적으로 호출하여 최신 설정을 받아오고, 로컬의 변경사항을 중앙 서버에 보고합니다.

빠른 시작

이 API를 사용하려면, Agent Token (at)과 로컬 서버 식별자 (lssn)가 필요합니다. 동기화 프로세스는 두 단계로 이루어집니다.

1. GetOpenclawSync를 통해 최신 해시와 데이터를 검증/수신
2. PutOpenclawSync를 통해 로컬의 변경사항을 GIIP 서버로 업로드

---

상세 기능 및 API

1. 동기화 데이터 조회 (GetOpenclawSync)

로컬 인스턴스의 Hash 값을 전달하여 GIIP 서버의 데이터와 비교 후 필요한 경우 최신 동기화 데이터를 반환합니다.

• URL: https://api.netbako.com/api/GetOpenclawSync
• Method: POST
• Content-Type: application/json

요청 파라미터 (Request)

필드명	타입	필수	설명
at	String	Y	Agent Token (인증용)
lssn	Integer	Y	로컬 서버 식별자
configHash	String	N	현재 로컬 설정의 Hash 값
docHash	String	N	현재 로컬 문서의 Hash 값

응답 형식 (Response)

Hash 불일치로 업데이트가 필요한 경우, 새로운 Hash 값과 변경된 데이터를 반환합니다.

{
  "RstVal": 1,
  "RstMsg": "Update required",
  "Data": {
    "newConfigHash": "...",
    "newDocHash": "...",
    "configData": { ... },
    "docData": [ { "doc_path": "...", "doc_content": "..." } ]
  }
}

변경 사항이 없을 경우, HTTP 200 상태와 함께 RstVal: 304를 반환합니다.

2. 동기화 데이터 반영 (PutOpenclawSync)

로컬에서 변경된 설정이나 문서를 GIIP 서버로 업로드하여 동기화합니다.

• URL: https://api.netbako.com/api/PutOpenclawSync
• Method: PUT
• Content-Type: application/json

요청 파라미터 (Request)

필드명	타입	필수	설명
at	String	Y	Agent Token
lssn	Integer	Y	로컬 서버 식별자
changedConfigs	Object	N	변경된 설정 항목 (Key-Value)
changedDocs	Array	N	변경된 문서 목록 (doc_path, doc_content 포함)

응답 형식 (Response)

업데이트에 성공하면 새로 계산된 Hash 값을 반환합니다.

{
  "RstVal": 1,
  "RstMsg": "Successfully updated",
  "Data": {
    "newConfigHash": "...",
    "newDocHash": "..."
  }
}

---

문제 해결

API 호출 중 문제가 발생할 수 있는 주요 상황과 해결 방법입니다.

• RstVal: -1 (Unauthorized): at 토큰이 유효하지 않습니다. 토큰이 올바른지 확인하거나 재발급 받으세요.
• RstVal: 400 (Invalid Parameter): 필수 파라미터(at, lssn)가 누락되었습니다. 요청 JSON 형식을 확인하세요.
• RstVal: 500 (Internal Server Error): DB 통신 에러 또는 SP 실행 에러입니다. tErrorLogs를 확인하여 정확한 원인을 분석해야 합니다.