cloud-claw - GitLite

KO | EN

gitlite — search

#javascript #python #hacktoberfest #typescript #go #machine-learning #docker #windows #kubernetes #vue #awesome-list #pytorch #mcp #open-source

cloud-claw

(★ 261)

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

파일 탐색기

최종 버전 다운로드 (.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

# 설치 가이드

1. 코드 내려받기

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

깃허브에서 프로젝트 코드 전체를 내 컴퓨터로 내려받습니다.

cd cloud-claw

방금 내려받은 프로젝트 폴더 안으로 이동합니다.

2. Docker

쉬움 추천

사전 준비물

Git GitHub에서 프로젝트 코드를 내려받으려면 필요합니다.
Docker Desktop 컨테이너를 빌드하고 실행하려면 필요합니다. 설치 후 실행해서 백그라운드에 켜두세요.

docker build -t cloud-claw .

Dockerfile을 기반으로 실행 가능한 이미지를 빌드합니다.

docker run -p 8080:80 cloud-claw

빌드된 이미지를 실제 컨테이너로 실행합니다.

✅ 터미널에 docker compose ps 를 입력해 컨테이너들이 Up 상태인지 확인하세요. README에 포트 번호가 적혀있다면 브라우저에서 http://localhost:포트번호 로 접속해보세요.

3. Node.js

쉬움

사전 준비물

Git GitHub에서 프로젝트 코드를 내려받으려면 필요합니다.
Node.js npm 명령어를 쓰려면 Node.js가 설치되어 있어야 합니다. LTS(장기지원) 버전을 추천합니다.

pnpm install

package.json에 명시된 라이브러리들을 내려받아 설치합니다.

pnpm dev

개발/실행 서버를 켭니다.

pnpm lint

이 명령어를 터미널에 그대로 입력해 실행하세요.

pnpm cf-typegen

이 명령어를 터미널에 그대로 입력해 실행하세요.

pnpm deploy

이 명령어를 터미널에 그대로 입력해 실행하세요.

✅ 명령어 실행 후 터미널에 나타나는 주소(보통 http://localhost:3000 형태)를 브라우저에서 열어보세요.

이 레포의 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).