cloud-claw - GitLite

KO | EN

gitlite — search

#hacktoberfest #typescript #llm #golang #go #deep-learning #awesome #cli #kubernetes #awesome-list #mcp #ios #openai #open-source

cloud-claw

(★ 261)

Run OpenClaw with One Click on Cloudflare Containers to Create Your Personal Agent

File Explorer

Download Latest Version (.zip)

- settings.json
- cdp.ts
- container.ts
- index.ts
.dockerignore
.editorconfig
.env.example
.gitignore
.oxfmtrc.json
AGENTS.md
Dockerfile
LICENSE
package.json
pnpm-lock.yaml
pnpm-workspace.yaml
README.md
README.zh-CN.md
tsconfig.json
worker-configuration.d.ts
wrangler.jsonc

# Installation Guide

1. Get the code

git clone https://github.com/miantiao-me/cloud-claw

Downloads the entire project code from GitHub to your computer.

cd cloud-claw

Moves into the project folder you just downloaded.

2. Docker

Easy Recommended

Prerequisites

Git Needed to download the project code from GitHub.
Docker Desktop Needed to build and run containers. Install it and keep it running in the background.

docker build -t cloud-claw .

Builds a runnable image based on the Dockerfile.

docker run -p 8080:80 cloud-claw

Runs the built image as an actual container.

✅ Run docker compose ps to check the containers are Up. If the README mentions a port, open http://localhost:PORT in your browser.

3. Node.js

Easy

Prerequisites

Git Needed to download the project code from GitHub.
Node.js Node.js must be installed to use npm. The LTS version is recommended.

pnpm install

Downloads and installs the libraries listed in package.json.

pnpm dev

Starts the development/run server.

pnpm lint

Type this command into your terminal and run it.

pnpm cf-typegen

Type this command into your terminal and run it.

pnpm deploy

Type this command into your terminal and run it.

✅ After running the command, open the address shown in the terminal (usually something like http://localhost:3000) in your browser.

Pulled directly from this repo's README.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# Cloud Claw (Cloudflare + OpenClaw)

**Cloud Claw** is a containerized AI assistant that runs [OpenClaw](https://github.com/openclaw/openclaw) on Cloudflare Workers + Containers.

A Worker handles routing and auth, forwards requests to a singleton container running an OpenClaw gateway instance, and proxies Chrome DevTools Protocol (CDP) sessions via Cloudflare Browser Rendering.

English | [简体中文](README.zh-CN.md)

---

## Tech Stack

- **Runtime**: Cloudflare Workers + Containers
- **Language**: TypeScript (ES2024)
- **Package Manager**: pnpm
- **Container Specs**: 1 vCPU, 4GB RAM, 8GB disk
- **Browser**: Cloudflare Browser Rendering (remote CDP)
- **Core Libraries**:
  - `cloudflare:workers`: Workers standard library
  - `@cloudflare/containers`: Container management
- **Container Base**: `nikolaik/python-nodejs:python3.12-nodejs22-bookworm`
- **Storage**: TigrisFS for S3/R2 mounting

## Quick Start

[![Deploy to Cloudflare](https://deploy.workers.cloudflare.com/button)](https://deploy.workers.cloudflare.com/?url=https://github.com/miantiao-me/cloud-claw)

### Prerequisites

- Node.js (v22+)
- pnpm (v10.28.2+)
- Wrangler CLI (`npm i -g wrangler`)

### Install Dependencies

```bash
pnpm install
```

### Local Development

Start the local development server:

```bash
pnpm dev
```

### Linting

Run formatter (oxfmt) and linter (oxlint):

```bash
pnpm lint
```

### Generate Type Definitions

If you modify bindings in `wrangler.jsonc`, regenerate the type file:

```bash
pnpm cf-typegen
```

## Deployment

Deploy code to Cloudflare's global network:

```bash
pnpm deploy
```

## Project Structure

```
.
├── src/
│   ├── index.ts        # Workers entry point, routing, basic auth
│   ├── container.ts    # AgentContainer class (extends Container), WebSocket gateway
│   └── cdp.ts          # Chrome DevTools Protocol proxy (chunked binary WebSocket framing)
├── Dockerfile          # Container image: OpenClaw gateway + TigrisFS S3 mount
├── worker-configuration.d.ts # Auto-generated Cloudflare binding types (DO NOT EDIT)
├── wrangler.jsonc      # Wrangler configuration (containers, bindings, placement)
├── tsconfig.json       # TypeScript configuration
└── package.json
```

## Data Persistence (S3/R2)

The container has built-in support for S3-compatible storage (such as Cloudflare R2, AWS S3). It uses `TigrisFS` to mount object storage as a local filesystem for persistent data storage.

### Environment Variables

To enable data persistence, configure the following environment variables in the container runtime environment:

| Variable                 | Description                                      | Required | Default |
| ------------------------ | ------------------------------------------------ | -------- | ------- |
| `S3_ENDPOINT`            | S3 API endpoint address                          | Yes      | -       |
| `S3_BUCKET`              | Bucket name                                      | Yes      | -       |
| `S3_ACCESS_KEY_ID`       | Access Key ID                                    | Yes      | -       |
| `S3_SECRET_ACCESS_KEY`   | Access Key Secret                                | Yes      | -       |
| `S3_REGION`              | Storage region                                   | No       | `auto`  |
| `S3_PATH_STYLE`          | Whether to use Path Style access                 | No       | `false` |
| `S3_PREFIX`              | Path prefix within the bucket (subdirectory)     | No       | (root)  |
| `TIGRISFS_ARGS`          | Additional mount arguments for TigrisFS          | No       | -       |
| `OPENCLAW_GATEWAY_TOKEN` | Gateway access token (for Web UI authentication) | Yes      | -       |
| `WORKER_URL`             | Worker's public URL (for CDP proxy config)       | Yes      | -       |

### How It Works

1. **Mount Point**: On container startup, the S3 bucket is mounted to `/data`.
2. **Workspace**: The actual workspace is located at `/data/workspace`.
3. **OpenClaw Config**: OpenClaw configuration files are stored in `/data/.openclaw` to ensure state persistence.
4. **Initialization**:
   - If the S3 bucket (or specified prefix path) is empty, the container automatically initializes the preset directory structure.
   - If S3 configuration is missing, the container falls back to non-persistent local directory mode.

### Web UI Initialization

After the first startup, OpenClaw needs to be initialized via the Web UI.
Visit the deployed URL (e.g., `https://your-worker.workers.dev`) and follow the on-screen instructions to complete setup.

## Browser Rendering (CDP Proxy)

Cloud Claw integrates [Cloudflare Browser Rendering](https://developers.cloudflare.com/browser-rendering/) to provide headless browser capabilities to the AI assistant via the Chrome DevTools Protocol (CDP).

### How It Works

1. **OpenClaw** connects to the Worker's CDP proxy endpoint (`/cloudflare.browser/{token}`) using WebSocket.
2. **The Worker** acquires a browser session from Cloudflare's Browser Rendering API and proxies CDP messages between OpenClaw and the remote browser.
3. **Binary framing**: CDP messages are chunked with a 4-byte length header to handle large payloads over Cloudflare's WebSocket infrastructure.

### Configuration

The CDP proxy is automatically configured when `WORKER_URL` and `OPENCLAW_GATEWAY_TOKEN` are set. The OpenClaw container generates a browser profile pointing to:

```
{WORKER_URL}/cloudflare.browser/{OPENCLAW_GATEWAY_TOKEN}
```

Authentication is handled via the token in the URL path — no additional setup required.

## Container Lifecycle

By default, the container automatically sleeps after 10 minutes of inactivity to save resources. You can customize this behavior:

### Keep Container Always Running

To prevent the container from sleeping, modify `src/container.ts`:

```typescript
export class AgentContainer extends Container {
  sleepAfter = 'never' // Never sleep (default: '10m')
  // ...
}
```

### Activity-Based Keep-Alive (Default)

The current implementation uses smart keep-alive: the container stays active during AI conversations and sleeps during idle periods. This is achieved by calling `renewActivityTimeout()` when chat events are received:

```typescript
// In watchContainer() - resets the sleep timer on each chat completion
if (frame.event === 'chat' && frame.payload?.state === 'final') {
  this.renewActivityTimeout()
}
```

### Available Options

| `sleepAfter` Value | Behavior                                       |
| ------------------ | ---------------------------------------------- |
| `'never'`          | Container runs indefinitely                    |
| `'10m'`            | Sleep after 10 minutes of inactivity (default) |
| `'1h'`             | Sleep after 1 hour of inactivity               |
| `'30s'`            | Sleep after 30 seconds of inactivity           |

> **Note**: When sleeping, the container state is preserved. It will automatically wake up on the next request, but cold start may take a few seconds.

## Development Guidelines

For detailed development guidelines, code style, and AI agent behavior standards, please refer to [AGENTS.md](./AGENTS.md).