iamlukethedev/Claw3D

Claw3D is an open source 3D engine built on OpenClaw for creating games, simulations, and high-performance 3D applications.

GitHub에서 열기 ↗ 3d-engineclaw3dgame-enginegamedevgraphicsjavascriptopen-sourceopenclawrenderingthreejswebgl

2,087

GitHub 스타

536

포크

TypeScript

언어

MIT

라이선스

2026.05.30

최근 푸시

2026.04.01

별표한 날

AI 분석

설치 난이도: 보통

큐레이터 노트

AI 에이전트 워크플로를 시각화하고 모니터링하려는 개발자에게 적합합니다. 특히 OpenClaw나 Hermes를 사용 중이고 3D 인터페이스를 통해 에이전트 활동을 더 직관적으로 파악하고 싶다면 도입을 고려해볼 만합니다.

강점

AI 에이전트의 작업을 3D 공간에서 시각화하여 직관적인 모니터링과 상호작용이 가능합니다.
OpenClaw, Hermes, 커스텀 HTTP 런타임 등 다양한 백엔드를 지원하며, 데모 모드도 제공하여 설치 없이 테스트할 수 있습니다.
WebSocket 프록시 설계로 CORS 문제를 피하고 보안을 강화했습니다.

약점

README가 매우 길고 복잡하여 초보자가 빠르게 시작하기 어려울 수 있습니다.
실제 에이전트 워크플로를 사용하려면 OpenClaw나 Hermes 같은 외부 런타임을 별도로 설치해야 합니다.
3D 사무실 환경이 실제 생산성 향상에 얼마나 도움이 되는지에 대한 정량적 데이터가 부족합니다.

주의사항

비공식 프로젝트이므로 OpenClaw 팀의 공식 지원을 받지 않습니다.
보안 설정(예: STUDIO_ACCESS_TOKEN, UPSTREAM_ALLOWLIST)을 프로덕션에서 반드시 구성해야 합니다.
브라우저가 신뢰 경계의 일부로 간주되므로 민감한 토큰이 브라우저 메모리에 로드됩니다.

시작 가이드

README의 빠른 시작 가이드에 따라 로컬에서 데모 모드로 Claw3D를 실행해보세요.
실제 백엔드(OpenClaw 또는 Hermes)와 연결하여 에이전트 워크플로를 시각화해보세요.
보안 설정(STUDIO_ACCESS_TOKEN, UPSTREAM_ALLOWLIST)을 검토하고 프로덕션 환경에 맞게 구성하세요.

README 한국어 번역

이 번역은 AI가 원문 README를 옮긴 것입니다. 원문이 항상 우선합니다.

Claw3D — AI 에이전트를 위한 3D 작업 공간

AI 팀을 위한 사무실!

Claw3D는 사용자가 자신의 인프라에서 실행하는 AI 에이전트를 위한 3D 가상 사무실입니다. 대시보드와 로그를 통해 자동화를 지켜보는 대신, 에이전트가 협업하고, 코드를 검토하고, 스탠드업을 진행하고, 풀 리퀘스트를 배포하고, 작업을 나란히 실행하는 라이브 3D 사무실을 걸어다닐 수 있습니다. 게이트웨이는 단지 제어 평면일 뿐이며, 실제 제품은 사무실입니다.

AI 워크포스를 실제로 볼 수 있는 개인적이고 자체 호스팅된 작업 공간을 원한다면, 이것이 바로 그 도구입니다.

지원되는 런타임: OpenClaw Gateway, Hermes, 오케스트레이터 기반 스택을 위한 직접 HTTP custom 런타임 제공자, 그리고 실제 에이전트 프레임워크 없이 사무실을 탐험할 수 있는 내장 데모 게이트웨이.

웹사이트 · 비전 · 아키텍처 · 튜토리얼 · 시작하기 · 런타임 프로필 · 멀티 에이전트 베타 · 기여하기 · 보안 · Discord

비공식 프로젝트. Claw3D는 독립적인 커뮤니티 주도 프로젝트이며, OpenClaw 팀과 제휴, 보증 또는 유지 관리되지 않습니다. OpenClaw는 별도의 프로젝트이며, 이 저장소는 공식 OpenClaw 저장소가 아닙니다.

LukeTheDev가 구축하고 유지 관리합니다. X에서 팔로우: @iamlukethedev.

Claw3D로 할 수 있는 일

AI 에이전트가 실시간으로 작업하는 모습을 공유 3D 사무실 내에서 지켜보세요.
GitHub 및 Jira에 연결된 에이전트와 스탠드업을 실행하세요.
사무실 내에서 풀 리퀘스트를 검토하세요.
작업 공간을 떠나지 않고 QA 파이프라인과 로그를 모니터링하세요.
체육관에서 에이전트를 훈련시켜 새로운 기술을 개발하세요.
청소부 시스템으로 세션을 재설정하고 컨텍스트를 정리하세요.

Claw3D가 무엇인가

Claw3D는 시각화 및 상호 작용 계층입니다.

현재 다음 위에 위치할 수 있습니다:

기존 게이트웨이 흐름을 통한 OpenClaw
번들된 WebSocket 어댑터를 통한 Hermes
오케스트레이터 기반 스택을 위한 직접 HTTP custom 런타임 제공자
실제 에이전트 프레임워크 없이 사무실 탐험을 위한 내장 데모 게이트웨이

실질적으로 이 앱은 다음을 제공합니다:

에이전트가 공유 3D 세계를 이동하는 작업자로 나타나는 라이브 /office 레트로 오피스 환경
사무실 레이아웃을 편집하고 게시하기 위한 /office/builder 표면
런타임 상태를 연결된 백엔드에 유지하고 Studio는 로컬 UI 기본 설정을 저장하는 게이트웨이 우선 아키텍처
전체 UI를 다시 작성하지 않고도 추가 제공자를 통합할 수 있도록 Studio 내부의 백엔드 중립 런타임 연결 지점

이 저장소는 업스트림 런타임 자체를 빌드하지 않습니다. 이는 프론트엔드, Studio, 그리고 Claw3D 게이트웨이 프로토콜을 사용하는 런타임에 연결되는 어댑터/프록시 계층입니다.

존재 이유

AI 시스템은 점점 더 강력해지고 있지만, 그 작업은 여전히 일반적으로 로그, 터미널 출력 및 대시보드 뒤에 숨겨져 있습니다.

Claw3D는 에이전트 시스템을 가시적으로 만들기 위해 존재합니다:

에이전트가 실시간으로 무엇을 하는지 검사
한 곳에서 실행, 승인, 기록 및 활동 모니터링
채팅 및 몰입형 UI 표면을 통해 에이전트와 상호 작용
AI 시스템이 공간, 움직임 및 존재를 통해 이해할 수 있는 세상으로 나아가기

프로젝트의 광범위한 방향에 대해서는 VISION.md를 참조하세요.

현재 존재하는 것

현재 앱에는 이미 상당한 Claw3D 표면이 포함되어 있습니다:

게이트웨이에서 스트리밍되는 런타임 업데이트를 통한 함대 관리 및 에이전트 채팅.
에이전트 생성, 설정, 세션 제어, 승인 및 게이트웨이 기반 구성 편집.
책상, 방, 탐색, 애니메이션 및 이벤트 기반 활동 신호가 있는 3D 레트로 오피스.
스탠드업, GitHub 리뷰 흐름, 분석 및 시스템 모니터링을 위한 몰입형 운영 공간.
게이트웨이 연결 세부 정보, 포커스된 에이전트 기본 설정, 책상 할당, 사무실 상태 및 관련 UI 설정을 위한 로컬 Studio 지속성.
브라우저가 Studio와 통신하고 Studio가 업스트림 OpenClaw Gateway와 통신하는 사용자 정의 동일 출처 WebSocket 프록시.

빠른 시작

요구 사항:

Node.js 20+ 권장.
npm 10+ 권장.
다음 중 하나:
연결 가능한 게이트웨이 URL과 토큰이 있는 작동하는 OpenClaw 설치
번들된 어댑터가 있는 Hermes
로컬 탐색을 위한 내장 데모 게이트웨이

전제 조건:

Claw3D는 OpenClaw 또는 Hermes를 설치하거나 빌드하지 않습니다.
실제 백엔드에 대해 Claw3D를 시작하기 전에 선택한 런타임이 이미 실행 중이고 Studio가 사용해야 하는 게이트웨이 URL과 토큰을 알고 있는지 확인하세요.
프레임워크 없는 로컬 사무실 데모를 보려면 번들된 데모 게이트웨이를 대신 실행하세요.
전체 크로스 머신 설정 가이드(OpenClaw + Tailscale + Claw3D)가 필요하면 TUTORIAL.md를 따르세요.

소스에서 실행:

git clone <your-public-repo-url> claw3d
cd claw3d
npm install
cp.env.example.env
npm run dev

그런 다음 http://localhost:3000을 열고 Studio에서 게이트웨이 URL과 토큰을 구성하세요. Studio는 이제 선택한 백엔드 모드(OpenClaw, Hermes, Demo, Local, Claw3D 또는 Custom)도 유지하며 연결된 게이트웨이가 보고하는 활성 백엔드를 표시합니다.

런타임 프로필

직접 HTTP 런타임 연결 지점을 통해 오케스트레이터 기반 런타임을 통합하는 경우, 먼저 런타임을 시작한 다음 Claw3D를 시작하세요:

npm run dev

그런 다음 http://localhost:3000을 열고 Local runtime, Claw3D runtime, 또는 Custom backend를 선택한 후 업스트림 URL을 런타임 경계로 지정하세요. 일반적인 예:

http://127.0.0.1:7770

http://localhost:3000/api/runtime/custom

현재 직접 런타임 기대 사항:

GET /health
GET /state
GET /registry
POST /v1/chat/completions

브라우저는 해당 런타임을 직접 호출하지 않습니다. Claw3D는 custom 제공자를 자체 동일 출처 경로인 /api/runtime/custom을 통해 프록시하여 브라우저 측 CORS 문제를 피하고 제공자 전송을 OpenClaw/Hermes 게이트웨이 경로와 분리합니다.

데모 모드

OpenClaw 또는 Hermes를 설치하지 않고 사무실과 에이전트 상호 작용만 보고 싶다면:

npm run demo-gateway
npm run dev

그런 다음 Studio를 다음에 연결하세요:

ws://localhost:18789

이것은 데모 에이전트, 스트리밍 채팅, 세션 미리보기 및 사무실 존재감을 갖춘 모의 로컬 게이트웨이를 시작합니다. 연결 화면에서 Demo backend를 선택한 다음 연결하세요.

Hermes 어댑터

OpenClaw 대신 Hermes를 사용하려면:

npm run hermes-adapter
npm run dev

설정 세부 사항 및 현재 범위는 docs/hermes-gateway.md를 참조하세요.

동일한 머신의 로컬 게이트웨이의 경우 일반적인 업스트림 URL은 다음과 같습니다:

ws://localhost:18789

연결 화면에서 Hermes backend를 선택한 다음 연결하세요.

연결 방식

Claw3D는 두 개의 별도 네트워크 홉을 사용합니다:

브라우저 -> Studio (HTTP 및 /api/gateway/ws의 동일 출처 WebSocket)
Studio -> OpenClaw Gateway (Studio 서버가 연 두 번째 WebSocket)

즉, ws://localhost:18789는 항상 Studio 호스트에서 연결할 수 있는 게이트웨이를 의미하며, 반드시 브라우저 장치에서 연결할 수 있는 것은 아닙니다.

이 설계는 게이트웨이 설정을 Studio 호스트에 유지하고 Studio가 서버 측에서 업스트림 연결을 열 수 있게 합니다. 현재 UI는 여전히 구성된 업스트림 URL/토큰을 런타임에 브라우저 메모리에 로드하므로 브라우저를 활성 신뢰 경계의 일부로 취급하세요.

일반적인 설정

게이트웨이 로컬, Studio 로컬

npm run dev로 Studio를 시작합니다.
http://localhost:3000을 엽니다.
OpenClaw 게이트웨이 토큰과 함께 ws://localhost:18789를 사용합니다.

게이트웨이 원격, Studio 로컬

머신이 연결할 수 있는 모든 게이트웨이 URL을 사용하세요.

Tailscale과 함께 권장:

게이트웨이 호스트에서 tailscale serve --yes --bg --https 443 http://127.0.0.1:18789를 실행합니다.
Studio에서 wss://<gateway-host>.ts.net을 사용합니다.

SSH를 사용한 대안:

ssh -L 18789:127.0.0.1:18789 user@<gateway-host>를 실행합니다.
Studio에서 ws://localhost:18789를 사용합니다.

Studio 원격, 게이트웨이 원격

원격 호스트에서 Studio를 실행합니다.
Studio를 개인 네트워크 또는 Tailscale을 통해 노출합니다.
Studio가 공용 호스트에 바인딩되는 경우 STUDIOACCESSTOKEN을 설정합니다.
Studio 내에서 게이트웨이 URL과 토큰을 구성합니다.

LAN 또는 Tailscale의 Studio를 다른 장치용으로

HOST=0.0.0.0(또는 특정 LAN/Tailscale 호스트)로 Studio를 시작합니다.
Studio를 localhost 이상으로 노출하기 전에 STUDIOACCESSTOKEN을 설정합니다.
localhost 대신 LAN/Tailscale 주소에서 Claw3D를 엽니다.
원격 OpenClaw 게이트웨이에 연결하는 경우 장치 승인은 브라우저/장치별로 이루어짐을 기억하세요. 새 브라우저는 여전히 다음이 필요할 수 있습니다:

openclaw devices approve --latest

기술 스택

메인 웹 애플리케이션을 위한 Next.js App Router, React 및 TypeScript.
Studio 측 WebSocket 프록시를 위한 사용자 정의 Node 서버.
3D 사무실 경험을 위한 Three.js, React Three Fiber 및 Drei.
사무실/뷰어-빌더 워크플로 및 관련 대화형 표면을 위한 Phaser.
단위 테스트를 위한 Vitest 및 엔드 투 엔드 커버리지를 위한 Playwright.

구성

중요한 런타임 경로:

OpenClaw 구성: ~/.openclaw/openclaw.json
Studio 설정: ~/.openclaw/claw3d/settings.json

일반적인 환경 변수:

HOST 및 PORT는 Studio 서버 바인드 주소와 포트를 제어합니다.
STUDIOACCESSTOKEN은 공용 호스트에 바인딩할 때 Studio를 보호합니다.
UPSTREAM_ALLOWLIST는 Studio가 프록시할 수 있는 업스트림 게이트웨이 호스트를 제한합니다. 프로덕션에서 설정하세요.
CUSTOMRUNTIMEALLOWLIST는 /api/runtime/custom이 가져올 수 있는 호스트를 제한합니다. 설정되지 않은 경우 UPSTREAM_ALLOWLIST로 대체됩니다.
NEXTPUBLICGATEWAY_URL은 Studio 설정이 비어 있을 때 기본 업스트림 게이트웨이 URL을 제공합니다. 참고: 이는 빌드 타임 변수입니다. 변경 사항을 적용하려면 npm run build가 필요합니다.
CLAW3DGATEWAYURL 및 CLAW3DGATEWAYTOKEN은 재빌드 없이 서버 재시작 시 적용되는 NEXTPUBLICGATEWAY_URL의 런타임 대안을 제공합니다.
CLAW3DGATEWAYADAPTERTYPE은 CLAW3DGATEWAY_URL과 함께 사용되어 해당 런타임 기본값을 openclaw, hermes, demo, local, claw3d 또는 custom으로 표시할 수 있습니다.
CLAW3DGATEWAYURL이 설정되지 않은 경우 Studio는 HERMESADAPTERPORT / DEMOADAPTERPORT에서 로컬 Hermes 또는 데모 어댑터 기본값을 표시할 수 있습니다.
OpenClaw 파일 기본값은 여전히 존재하는 경우 ~/.openclaw/openclaw.json에서 가져옵니다.
OPENCLAWSTATEDIR 및 OPENCLAWCONFIGPATH는 기본 OpenClaw 경로를 재정의합니다.
OPENCLAWGATEWAYSSHTARGET, OPENCLAWGATEWAYSSHUSER, OPENCLAWGATEWAYSSHPORT 및 OPENCLAWGATEWAYSSHSTRICTHOSTKEY_CHECKING은 필요할 때 SSH를 통한 고급 게이트웨이 호스트 작업을 지원합니다.
ELEVENLABSAPIKEY, ELEVENLABSVOICEID 및 ELEVENLABSMODELID는 음성 응답 통합을 활성화합니다.

전체 로컬 개발 템플릿은 .env.example을 참조하세요.

스크립트

npm run dev는 Studio 개발 서버를 시작합니다.

원본 저장소: iamlukethedev/Claw3D

라이선스: MIT

게재 제외를 원하시면 삭제 요청을 보내주세요.