moltworker AGENTS.md

Agent Instructions

Guidelines for AI agents working on this codebase.

Project Overview

This is a Cloudflare Worker that runs OpenClaw (formerly Moltbot/Clawdbot) in a Cloudflare Sandbox container. It provides:

• Proxying to the OpenClaw gateway (web UI + WebSocket)
• Admin UI at /_admin/ for device management
• API endpoints at /api/* for device pairing
• Debug endpoints at /debug/* for troubleshooting

Note: The CLI tool and npm package are now named openclaw. Config files use .openclaw/openclaw.json. Legacy .clawdbot paths are supported for backward compatibility during transition.

Project Structure

src/
├── index.ts          # Main Hono app, route mounting
├── types.ts          # TypeScript type definitions
├── config.ts         # Constants (ports, timeouts, paths)
├── auth/             # Cloudflare Access authentication
│   ├── jwt.ts        # JWT verification
│   ├── jwks.ts       # JWKS fetching and caching
│   └── middleware.ts # Hono middleware for auth
├── gateway/          # OpenClaw gateway management
│   ├── process.ts    # Process lifecycle (find, start)
│   ├── env.ts        # Environment variable building
│   ├── r2.ts         # R2 bucket mounting
│   ├── sync.ts       # R2 backup sync logic
│   └── utils.ts      # Shared utilities (waitForProcess)
├── routes/           # API route handlers
│   ├── api.ts        # /api/* endpoints (devices, gateway)
│   ├── admin.ts      # /_admin/* static file serving
│   └── debug.ts      # /debug/* endpoints
└── client/           # React admin UI (Vite)
    ├── App.tsx
    ├── api.ts        # API client
    └── pages/

Key Patterns

Environment Variables

• DEV_MODE - Skips CF Access auth AND bypasses device pairing (maps to OPENCLAW_DEV_MODE for container)
• DEBUG_ROUTES - Enables /debug/* routes (disabled by default)
• See src/types.ts for full MoltbotEnv interface

CLI Commands

When calling the OpenClaw CLI from the worker, always include --url ws://localhost:18789:

sandbox.startProcess('openclaw devices list --json --url ws://localhost:18789')