OpenClaw 아키텍처

OpenClaw 아키텍처

수정자: 미미
수정일: 2026-04-19 00:13
상태: ✅ 활성 (v2026.4.15)

---

개요

OpenClaw는 분산 에이전트 시스템으로, 게이트웨이-노드 아키텍처를 사용한다.

---

현재 구성

게이트웨이 (맥미니)

항목	값
기기	PS-M4pro (맥미니)
역할	게이트웨이, 대시보드, Tailscale Serve
Tailscale IP	100.96.177.124
게이트웨이 URL	https://ps-m4pro.tail437af5.ts.net
로컬 대시보드	http://127.0.0.1:18789/
상태	✅ 활성

노드 (메인컴 + 보조컴)

노드	기기	ID	상태
mainpc-node	PS-I14700K (메인컴 WSL)	4448cee...9dc206	✅ paired · connected
MH-3900x	MH-3900X (보조컴 WSL)	c622d00...37c5c56d	✅ paired · connected

---

설정 파일

게이트웨이 설정 (~/.openclaw/openclaw.json)

{
  "gateway": {
    "mode": "remote",
    "tailscale": {
      "mode": "serve"
    },
    "bind": "loopback",
    "auth": {
      "mode": "token",
      "token": "<게이트웨이_토큰>"
    },
    "controlUi": {
      "allowedOrigins": [
        "http://localhost:18789",
        "http://127.0.0.1:18789",
        "https://ps-m4pro-1.tail437af5.ts.net"
      ]
    }
  }
}

노드 설정

{
  "gateway": {
    "mode": "remote",
    "auth": {
      "mode": "token",
      "token": "<게이트웨이_토큰>"
    },
    "remote": {
      "url": "wss://ps-m4pro.tail437af5.ts.net"
    }
  }
}

---

systemd 서비스 (노드)

서비스 파일 위치

~/.config/systemd/user/openclaw-node.service

ExecStart 설정 (중요!)

ExecStart=/usr/bin/node /usr/lib/node_modules/openclaw/dist/cli.js node run \
  --host ps-m4pro.tail437af5.ts.net \
  --port 443 \
  --tls

주의: --tls 옵션 필수 (원격 게이트웨이 연결 시)

서비스 제어

# 상태 확인
systemctl --user status openclaw-node.service

# 재시작
systemctl --user restart openclaw-node.service

# 로그 확인
journalctl --user -u openclaw-node.service -n 50 --no-pager

---

게이트웨이 제어 명령어

# 게이트웨이 상태 확인
openclaw gateway status

# 게이트웨이 재시작
openclaw gateway restart

# 노드 목록 확인
openclaw nodes list

# 노드 상태 확인
openclaw nodes status

# 노드 승인 (페어링)
openclaw nodes approve <request-id>

# 노드 제거
openclaw nodes remove <node-id>

---

페어링 워크플로우

1. 노드 설치 후 첫 연결

# 노드에서
openclaw node install
openclaw node run --tls

2. 게이트웨이에서 승인

# 게이트웨이에서
openclaw nodes list
# Pending 목록에서 request-id 확인

openclaw nodes approve <request-id>

3. 연결 확인

openclaw nodes status
# "paired · connected" 확인

---

문제 해결

노드가 연결되지 않을 때

1. 로그 확인:

   journalctl --user -u openclaw-node.service -n 50 --no-pager

2. TLS 옵션 확인:

   • 서비스 파일에 --tls 옵션 필수
   • 원격 게이트웨이 연결 시 wss:// 프로토콜 사용

3. 게이트웨이 주소 확인:

   • Tailscale 주소: ps-m4pro.tail437af5.ts.net
   • 포트: 443

4. 수동 연결 테스트:

   systemctl --user stop openclaw-node.service
   openclaw node run --tls

페어링 요청이 만료될 때

• 노드가 5 초마다 재시작하면 requestId 가 만료됨
• 서비스를 중지하고 수동으로 실행한 상태에서 빠르게 승인
• 또는 게이트웨이 재시작 후 다시 시도

---

관련 문서

• [[MiniCITY(v0.5_PARA_0502-)/04_ARCHIVE(보관함)/버전별/v0.2-백업/MiniCITY(v0.2_진행중_0419-)/98.history/MiniCITY(v0.1_예전자료_0410-0419)/01.접속정보/SSH_접속정보]]
• [[MiniCITY(v0.5_PARA_0502-)/04_ARCHIVE(보관함)/버전별/v0.2-백업/MiniCITY(v0.2_진행중_0419-)/98.history/MiniCITY(v0.1_예전자료_0410-0419)/01.접속정보/Tailscale_접속정보]]
• [[OpenClaw_설치]]
• [[MiniCITY(v0.5_PARA_0502-)/04_ARCHIVE(보관함)/버전별/v0.2-백업/MiniCITY(v0.2_진행중_0419-)/98.history/MiniCITY(v0.1_예전자료_0410-0419)/04.규칙및제약/보안규칙]]

---

변경이력

날짜	수정자	내용
2026-04-17	미미	Tailscale Serve 설정 (CORS 허용 추가)
2026-04-18	미미	메인컴/보조컴 노드 연결 완료
2026-04-19	미미	v0.1 정리 (MiniCITY 재구성)