{"id":49218342,"url":"https://github.com/iamlukethedev/claw3d","last_synced_at":"2026-04-24T01:09:05.369Z","repository":{"id":345212219,"uuid":"1182106379","full_name":"iamlukethedev/Claw3D","owner":"iamlukethedev","description":"Claw3D is an open source 3D engine built on OpenClaw for creating games, simulations, and high-performance 3D applications.","archived":false,"fork":false,"pushed_at":"2026-04-19T02:30:28.000Z","size":3891,"stargazers_count":1349,"open_issues_count":40,"forks_count":320,"subscribers_count":19,"default_branch":"main","last_synced_at":"2026-04-19T03:34:29.931Z","etag":null,"topics":["3d-engine","claw3d","game-engine","gamedev","graphics","javascript","open-source","openclaw","rendering","threejs","webgl"],"latest_commit_sha":null,"homepage":"https://claw3d.ai","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/iamlukethedev.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.MD","threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":".github/SECURITY.md","support":"SUPPORT.md","governance":null,"roadmap":"ROADMAP.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null},"funding":{"github":"iamlukethedev"}},"created_at":"2026-03-15T03:32:58.000Z","updated_at":"2026-04-19T02:53:18.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/iamlukethedev/Claw3D","commit_stats":null,"previous_names":["iamlukethedev/claw3d"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/iamlukethedev/Claw3D","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iamlukethedev%2FClaw3D","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iamlukethedev%2FClaw3D/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iamlukethedev%2FClaw3D/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iamlukethedev%2FClaw3D/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/iamlukethedev","download_url":"https://codeload.github.com/iamlukethedev/Claw3D/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iamlukethedev%2FClaw3D/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32204712,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-24T00:06:41.111Z","status":"ssl_error","status_checked_at":"2026-04-24T00:06:35.224Z","response_time":53,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["3d-engine","claw3d","game-engine","gamedev","graphics","javascript","open-source","openclaw","rendering","threejs","webgl"],"created_at":"2026-04-24T01:09:04.683Z","updated_at":"2026-04-24T01:09:05.346Z","avatar_url":"https://github.com/iamlukethedev.png","language":"TypeScript","readme":"# Claw3D — A 3D Workspace for AI Agents\n\n\u003cp align=\"center\"\u003e\n    \u003cimg src=\"assets/branding/claw3d-hero.png\" alt=\"Claw3D\" width=\"700\"\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cstrong\u003eAN OFFICE FOR YOUR AI TEAM!\u003c/strong\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://github.com/iamlukethedev/Claw3D/actions/workflows/docker-publish.yml?query=branch%3Amain\"\u003e\u003cimg src=\"https://img.shields.io/github/actions/workflow/status/iamlukethedev/Claw3D/docker-publish.yml?branch=main\u0026style=for-the-badge\" alt=\"CI status\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/iamlukethedev/Claw3D/releases\"\u003e\u003cimg src=\"https://img.shields.io/github/v/release/iamlukethedev/Claw3D?include_prereleases\u0026style=for-the-badge\" alt=\"GitHub release\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://discord.gg/UzwNn5Zkhr\"\u003e\u003cimg src=\"https://img.shields.io/discord/1456350064065904867?label=Discord\u0026logo=discord\u0026logoColor=white\u0026color=5865F2\u0026style=for-the-badge\" alt=\"Discord\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://x.com/iamlukethedev\"\u003e\u003cimg src=\"https://img.shields.io/badge/Follow-%40iamlukethedev-000000?style=for-the-badge\u0026logo=x\u0026logoColor=white\" alt=\"Follow on X\"\u003e\u003c/a\u003e\n  \u003ca href=\"LICENSE\"\u003e\u003cimg src=\"https://img.shields.io/badge/License-MIT-blue.svg?style=for-the-badge\" alt=\"MIT License\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n**Claw3D** is a _3D virtual office for AI agents_ you run on your own infrastructure.\nInstead of watching automation through dashboards and logs, you walk through a live 3D office where your agents collaborate, review code, run standups, ship pull requests, and execute tasks side by side. The Gateway is just the control plane — the product is the office.\n\nIf you want a personal, self-hosted workspace that turns your AI workforce into something you can actually _see_, this is it.\n\nSupported runtimes include: OpenClaw Gateway, Hermes, a direct HTTP `custom` runtime provider for orchestrator-backed stacks, and a built-in demo gateway for office exploration without a real agent framework.\n\n[Website](https://www.claw3d.ai/) · [Vision](VISION.md) · [Architecture](ARCHITECTURE.md) · [Tutorial](TUTORIAL.md) · [Getting Started](#quick-start) · [Runtime Profiles](docs/runtime-profiles.md) · [Multi-Agent Beta](docs/multi-agent-beta.md) · [Contributing](CONTRIBUTING.md) · [Security](SECURITY.md) · [Discord](https://discord.gg/UzwNn5Zkhr)\n\n\u003e **Unofficial project.** Claw3D is an independent, community-driven project and is not affiliated with, endorsed by, or maintained by the OpenClaw team. OpenClaw is a separate project, and this repository is not the official OpenClaw repository.\n\nBuilt and maintained by **LukeTheDev**. Follow on X: [@iamlukethedev](https://x.com/iamlukethedev).\n\n## What you can do with Claw3D\n\n- **Watch your AI agents work in real time** inside a shared 3D office.\n- **Run standups** with agents connected to GitHub and Jira.\n- **Review pull requests** from inside the office.\n- **Monitor QA pipelines** and logs without leaving the workspace.\n- **Train agents in the gym** to develop new skills.\n- **Reset sessions and clean context** with the janitor system.\n\n## What Claw3D Is\n\nClaw3D is the visualization and interaction layer.\n\nToday it can sit on top of:\n\n- OpenClaw through the existing gateway flow\n- Hermes through the bundled WebSocket adapter\n- a direct HTTP `custom` runtime provider for orchestrator-backed stacks\n- a built-in demo gateway for office exploration without a real agent framework\n\nIn practical terms, this app gives you:\n\n- a live `/office` retro-office environment where agents appear as workers moving through a shared 3D world\n- an `/office/builder` surface for editing and publishing office layouts\n- a gateway-first architecture that keeps runtime state in the connected backend while Studio stores local UI preferences\n- a backend-neutral runtime seam inside Studio so additional providers can be integrated without rewriting the whole UI\n\nThis repository does not build the upstream runtimes themselves. It is the frontend, Studio, and adapter/proxy layer that connects to a runtime speaking the Claw3D gateway protocol.\n\n## Why It Exists\n\nAI systems are becoming more capable, but their work is still usually hidden behind logs, terminal output, and dashboards.\n\nClaw3D exists to make agent systems visible:\n\n- inspect what agents are doing in real time\n- monitor runs, approvals, history, and activity from one place\n- interact with agents through chat and immersive UI surfaces\n- move toward a world where AI systems are understandable through space, motion, and presence\n\nFor the broader direction of the project, see [`VISION.md`](VISION.md).\n\n## What Exists Today\n\nThe current app already includes a substantial Claw3D surface:\n\n- Fleet management and agent chat with runtime updates streamed from the gateway.\n- Agent creation, settings, session controls, approvals, and gateway-backed configuration editing.\n- A 3D retro office with desks, rooms, navigation, animations, and event-driven activity cues.\n- Immersive operational spaces for standups, GitHub review flows, analytics, and system monitoring.\n- Local Studio persistence for gateway connection details, focused-agent preferences, desk assignments, office state, and related UI settings.\n- A custom same-origin WebSocket proxy so the browser talks to Studio, and Studio talks to the upstream OpenClaw Gateway.\n\n## Quick Start\n\nRequirements:\n\n- Node.js 20+ recommended.\n- npm 10+ recommended.\n- One of:\n  - a working OpenClaw installation with a reachable Gateway URL and token\n  - Hermes with the bundled adapter\n  - the built-in demo gateway for local exploration\n\nPrerequisite:\n\n- Claw3D does not install or build OpenClaw or Hermes for you.\n- Before starting Claw3D against a real backend, make sure your chosen runtime is already running and that you know the gateway URL and token Studio should use.\n- For a no-framework local office demo, run the bundled demo gateway instead.\n- If you need a full cross-machine setup guide (OpenClaw + Tailscale + Claw3D), follow [`TUTORIAL.md`](TUTORIAL.md).\n\nRun from source:\n\n```bash\ngit clone \u003cyour-public-repo-url\u003e claw3d\ncd claw3d\nnpm install\ncp .env.example .env\nnpm run dev\n```\n\nThen open `http://localhost:3000` and configure the gateway URL and token in Studio.\nStudio now also persists the selected backend mode (`OpenClaw`, `Hermes`, `Demo`, `Local`, `Claw3D`, or `Custom`) and\nshows the active backend reported by the connected gateway.\n\n### Runtime profiles\n\nIf you are integrating an orchestrator-backed runtime through the direct\nHTTP runtime seam, start your runtime first, then start Claw3D:\n\n```bash\nnpm run dev\n```\n\nThen open `http://localhost:3000`, choose `Local runtime`, `Claw3D runtime`,\nor `Custom backend`, and point the upstream URL at your runtime boundary.\nTypical examples:\n\n```text\nhttp://127.0.0.1:7770\n```\n\n```text\nhttp://localhost:3000/api/runtime/custom\n```\n\nCurrent direct-runtime expectations:\n\n- `GET /health`\n- `GET /state`\n- `GET /registry`\n- `POST /v1/chat/completions`\n\nThe browser does not call that runtime directly. Claw3D proxies the\n`custom` provider through its own same-origin route at\n`/api/runtime/custom`, which avoids browser-side CORS problems and keeps\nthe provider transport separate from the OpenClaw/Hermes gateway path.\n\n### Demo mode\n\nIf you only want to see the office and agent interactions without installing OpenClaw or Hermes:\n\n```bash\nnpm run demo-gateway\nnpm run dev\n```\n\nThen connect Studio to:\n\n```text\nws://localhost:18789\n```\n\nThis starts a mock local gateway with demo agents, streaming chat, session previews, and office presence.\nIn the connect screen, choose `Demo backend`, then connect.\n\n### Hermes adapter\n\nIf you want to use Hermes instead of OpenClaw:\n\n```bash\nnpm run hermes-adapter\nnpm run dev\n```\n\nSee [`docs/hermes-gateway.md`](docs/hermes-gateway.md) for setup details and current scope.\n\nFor a local gateway on the same machine, the usual upstream URL is:\n\n```text\nws://localhost:18789\n```\n\nIn the connect screen, choose `Hermes backend`, then connect.\n\n## How It Connects\n\nClaw3D uses two separate network hops:\n\n1. Browser -\u003e Studio over HTTP and a same-origin WebSocket at `/api/gateway/ws`.\n2. Studio -\u003e OpenClaw Gateway over a second WebSocket opened by the Studio server.\n\nThat means `ws://localhost:18789` always refers to the gateway reachable from the Studio host, not necessarily from the browser device.\n\nThis design keeps gateway settings persisted on the Studio host and lets Studio open the upstream connection server-side. The current UI still loads the configured upstream URL/token into browser memory at runtime, so treat the browser as part of the active trust boundary.\n\n## Common Setups\n\n### Gateway local, Studio local\n\n1. Start Studio with `npm run dev`.\n2. Open `http://localhost:3000`.\n3. Use `ws://localhost:18789` plus your OpenClaw gateway token.\n\n### Gateway remote, Studio local\n\nUse any gateway URL your machine can reach.\n\nRecommended with Tailscale:\n\n1. On the gateway host, run `tailscale serve --yes --bg --https 443 http://127.0.0.1:18789`.\n2. In Studio, use `wss://\u003cgateway-host\u003e.ts.net`.\n\nAlternative with SSH:\n\n1. Run `ssh -L 18789:127.0.0.1:18789 user@\u003cgateway-host\u003e`.\n2. In Studio, use `ws://localhost:18789`.\n\n### Studio remote, Gateway remote\n\n1. Run Studio on the remote host.\n2. Expose Studio on a private network or over Tailscale.\n3. Set `STUDIO_ACCESS_TOKEN` if Studio binds to a public host.\n4. Configure the gateway URL and token inside Studio.\n\n### Studio on LAN or Tailscale for other devices\n\n1. Start Studio with `HOST=0.0.0.0` (or a specific LAN/Tailscale host).\n2. Set `STUDIO_ACCESS_TOKEN` before exposing Studio beyond localhost.\n3. Open Claw3D from the LAN/Tailscale address instead of `localhost`.\n4. If you are connecting to a remote OpenClaw gateway, remember device approval is per browser/device. A new browser may still require:\n\n```bash\nopenclaw devices approve --latest\n```\n\n## Tech Stack\n\n- Next.js App Router, React, and TypeScript for the main web application.\n- A custom Node server for the Studio-side WebSocket proxy.\n- Three.js, React Three Fiber, and Drei for the 3D office experience.\n- Phaser for office/viewer-builder workflows and related interactive surfaces.\n- Vitest for unit tests and Playwright for end-to-end coverage.\n\n## Configuration\n\nImportant runtime paths:\n\n- OpenClaw config: `~/.openclaw/openclaw.json`\n- Studio settings: `~/.openclaw/claw3d/settings.json`\n\nCommon environment variables:\n\n- `HOST` and `PORT` control the Studio server bind address and port.\n- `STUDIO_ACCESS_TOKEN` protects Studio when binding to a public host.\n- `UPSTREAM_ALLOWLIST` restricts which upstream gateway hosts Studio may proxy to. Set this in production.\n- `CUSTOM_RUNTIME_ALLOWLIST` restricts which hosts `/api/runtime/custom` may fetch. If unset, it falls back to `UPSTREAM_ALLOWLIST`.\n- `NEXT_PUBLIC_GATEWAY_URL` provides the default upstream gateway URL when Studio settings are empty. **Note:** this is a build-time variable — changes require `npm run build` to take effect.\n- `CLAW3D_GATEWAY_URL` and `CLAW3D_GATEWAY_TOKEN` provide a runtime alternative to `NEXT_PUBLIC_GATEWAY_URL` that takes effect on server restart without a rebuild.\n- `CLAW3D_GATEWAY_ADAPTER_TYPE` can pair with `CLAW3D_GATEWAY_URL` to mark those runtime defaults as `openclaw`, `hermes`, `demo`, `local`, `claw3d`, or `custom`.\n- If `CLAW3D_GATEWAY_URL` is not set, Studio can still surface local Hermes or demo adapter defaults from `HERMES_ADAPTER_PORT` / `DEMO_ADAPTER_PORT`.\n- OpenClaw file defaults still come from `~/.openclaw/openclaw.json` when present.\n- `OPENCLAW_STATE_DIR` and `OPENCLAW_CONFIG_PATH` override the default OpenClaw paths.\n- `OPENCLAW_GATEWAY_SSH_TARGET`, `OPENCLAW_GATEWAY_SSH_USER`, `OPENCLAW_GATEWAY_SSH_PORT`, and `OPENCLAW_GATEWAY_SSH_STRICT_HOST_KEY_CHECKING` support advanced gateway-host operations over SSH when needed.\n- `ELEVENLABS_API_KEY`, `ELEVENLABS_VOICE_ID`, and `ELEVENLABS_MODEL_ID` enable voice reply integration.\n\nSee [`.env.example`](.env.example) for the full local development template.\n\n## Scripts\n\n- `npm run dev` starts the Studio dev server.\n- `npm run hermes-adapter` starts the Hermes WebSocket adapter.\n- `npm run demo-gateway` starts the built-in mock gateway for demo mode.\n- `npm run build` builds the production Next.js app.\n- `npm run start` starts the production server.\n- `npm run lint` runs ESLint.\n- `npm run typecheck` runs TypeScript without emitting output.\n- `npm run test` runs unit tests with Vitest.\n- `npm run e2e` runs Playwright tests.\n- `npm run studio:setup` prepares common local Studio prerequisites.\n- `npm run smoke:dev-server` runs a basic dev-server smoke check.\n\n## Documentation\n\n- [`VISION.md`](VISION.md): project direction and long-term guardrails.\n- [`ARCHITECTURE.md`](ARCHITECTURE.md): system boundaries, data flow, and major trade-offs.\n- [`TUTORIAL.md`](TUTORIAL.md): detailed step-by-step setup for OpenClaw + Tailscale + Claw3D.\n- [`docs/multi-agent-beta.md`](docs/multi-agent-beta.md): remote office beta setup, connection modes, and limitations.\n- [`docs/runtime-profiles.md`](docs/runtime-profiles.md): saved backend/runtime profiles and the current HTTP runtime seam.\n- [`CODE_DOCUMENTATION.md`](CODE_DOCUMENTATION.md): practical code map, extension points, and contributor onboarding order.\n- [`CONTRIBUTING.md`](CONTRIBUTING.md): local workflow, testing, and PR expectations.\n- [`SUPPORT.md`](SUPPORT.md): where to ask for help and how to route reports.\n- [`ROADMAP.md`](ROADMAP.md): near-term priorities and contributor-friendly work areas.\n- [`docs/pi-chat-streaming.md`](docs/pi-chat-streaming.md): gateway runtime streaming and transcript rendering.\n- [`docs/permissions-sandboxing.md`](docs/permissions-sandboxing.md): Studio permissions and OpenClaw behavior.\n- [`docs/hermes-gateway.md`](docs/hermes-gateway.md): Hermes adapter setup, capabilities, and current limitations.\n\n## Current Limitations\n\n- The immersive retro office (`/office`) and the Phaser builder (`/office/builder`) are related but still separate stacks.\n- The app keeps gateway secrets out of browser persistent storage, but the current connection flow still loads the upstream URL/token into browser memory at runtime.\n- Local Spotify auth for `SOUNDCLAW` currently stores an access token only. Refresh-token handling is not implemented yet, so local Spotify auth may need to be repeated after the token expires.\n\n## Troubleshooting\n\nIf the UI loads but Connect fails, the problem is usually on the Studio -\u003e Gateway side:\n\n- Confirm the upstream URL and token in Studio settings.\n- `EPROTO` or `wrong version number` usually means `wss://` was used against a non-TLS endpoint.\n- `INVALID_REQUEST` errors mentioning `minProtocol` or `maxProtocol` usually mean the gateway is too old for Claw3D protocol v3. Upgrade OpenClaw, use the Hermes adapter, or run `npm run demo-gateway`.\n- `401 Studio access token required` usually means `STUDIO_ACCESS_TOKEN` is enabled and the request is missing the expected `studio_access` cookie.\n- If `/api/runtime/custom` returns a blocked-host error in production, set `CUSTOM_RUNTIME_ALLOWLIST` or include the runtime host in `UPSTREAM_ALLOWLIST`.\n- Helpful proxy error codes include `studio.gateway_url_missing`, `studio.gateway_token_missing`, `studio.upstream_error`, and `studio.upstream_closed`.\n\nMarketplace skill installs now use a gateway-native workspace flow and do not require enabling SSH on the user machine.\n\n### Spotify auth on localhost\n\nIf you are testing the `SOUNDCLAW` jukebox locally and Spotify OAuth does not accept your `localhost` callback, use an `ngrok` callback bridge:\n\n1. Keep Claw3D running locally on `http://localhost:3000`.\n2. Start `ngrok` for the local Studio server, for example `ngrok http 3000`.\n3. In the jukebox setup UI, paste your public `ngrok` URL into the `ngrok Public URL` field.\n4. In the Spotify developer dashboard, register `https://\u003cyour-ngrok-host\u003e/spotify/callback` as the redirect URI.\n5. Complete Spotify sign-in from the jukebox panel.\n\nHow it works:\n\n- The main Claw3D app stays on `localhost`, so your normal local office state and agent state remain intact.\n- Spotify redirects to the `ngrok` callback URL.\n- The callback page passes the auth code back to the open local Claw3D window.\n\nCurrent local limitation:\n\n- Because only the Spotify access token is stored right now, you may need to repeat the `ngrok` auth flow when that token expires during local development.\n\nIf you use other advanced gateway-host operations over SSH:\n\n- macOS: enable `System Settings` -\u003e `General` -\u003e `Sharing` -\u003e `Remote Login`, and make sure the target user is allowed.\n- Windows: enable the `OpenSSH Server` optional feature, start the `sshd` service, and allow it through the firewall.\n- Linux: make sure `sshd` is installed, running, and reachable from the Studio machine.\n\nFor first-time SSH connections, Claw3D uses `StrictHostKeyChecking=accept-new` by default so a new host key can be trusted automatically. If you need stricter behavior, set `OPENCLAW_GATEWAY_SSH_STRICT_HOST_KEY_CHECKING=yes`, or set it to `no` only if you explicitly want to skip host key checks.\n\n## Contributing\n\nKeep pull requests focused, run `npm run lint`, `npm run typecheck`, and `npm run test` before opening a PR, and update docs when behavior or architecture changes.\n\n## AI Editing Guardrails\n\nIf you use Cursor or another AI-assisted workflow, review the committed project guardrails in [`.cursor/rules/claw3d-project-guardrails.mdc`](.cursor/rules/claw3d-project-guardrails.mdc).\n\nThat rule file captures the shared editing expectations for this repository, including the Claw3D-vs-OpenClaw boundary, code placement conventions, office-stack distinctions, and documentation/test update expectations.\n\nCommunity expectations live in [`CODE_OF_CONDUCT.md`](CODE_OF_CONDUCT.md). Security reporting instructions live in [`SECURITY.md`](SECURITY.md).\n","funding_links":["https://github.com/sponsors/iamlukethedev"],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fiamlukethedev%2Fclaw3d","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fiamlukethedev%2Fclaw3d","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fiamlukethedev%2Fclaw3d/lists"}