Skip to content

Commit e35f983

Browse files
melvincarvalhomelvincarvalho
committed
Initial release: OpenClaw community documentation site
31-page Docusaurus docs site for OpenClaw (clawdocs.org) covering: - Getting Started: introduction, installation, quick start, core concepts - Architecture: gateway, brain/hands, memory system, heartbeat - Guides: basic usage, channels, skills, heartbeat, local models, ClawHub, 4 recipes - Security: overview, hardening, known vulnerabilities (CVE-2026-25253), skill verification - Reference: CLI, configuration, gateway API, env vars, troubleshooting, FAQ - Contributing: docs and OpenClaw upstream Includes GitHub Actions deploy workflow, custom domain CNAME, and crimson theme inspired by the lobster branding.
0 parents  commit e35f983

53 files changed

Lines changed: 23361 additions & 0 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.github/workflows/deploy.yml‎

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
1+
name: Deploy to GitHub Pages
2+
3+
on:
4+
push:
5+
branches: [gh-pages]
6+
workflow_dispatch:
7+
8+
permissions:
9+
contents: read
10+
pages: write
11+
id-token: write
12+
13+
concurrency:
14+
group: "pages"
15+
cancel-in-progress: true
16+
17+
jobs:
18+
build:
19+
runs-on: ubuntu-latest
20+
steps:
21+
- uses: actions/checkout@v4
22+
- uses: actions/setup-node@v4
23+
with:
24+
node-version: 22
25+
cache: npm
26+
- run: npm ci
27+
- run: npm run build
28+
- uses: actions/upload-pages-artifact@v3
29+
with:
30+
path: build
31+
32+
deploy:
33+
environment:
34+
name: github-pages
35+
url: ${{ steps.deployment.outputs.page_url }}
36+
runs-on: ubuntu-latest
37+
needs: build
38+
steps:
39+
- uses: actions/deploy-pages@v4
40+
id: deployment

‎.gitignore‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
# Dependencies
2+
/node_modules
3+
4+
# Production
5+
/build
6+
7+
# Generated files
8+
.docusaurus
9+
.cache-loader
10+
11+
# Misc
12+
.DS_Store
13+
.env.local
14+
.env.development.local
15+
.env.test.local
16+
.env.production.local
17+
18+
npm-debug.log*
19+
yarn-debug.log*
20+
yarn-error.log*

‎README.md‎

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
# Website
2+
3+
This website is built using [Docusaurus](https://docusaurus.io/), a modern static website generator.
4+
5+
## Installation
6+
7+
```bash
8+
yarn
9+
```
10+
11+
## Local Development
12+
13+
```bash
14+
yarn start
15+
```
16+
17+
This command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server.
18+
19+
## Build
20+
21+
```bash
22+
yarn build
23+
```
24+
25+
This command generates static content into the `build` directory and can be served using any static contents hosting service.
26+
27+
## Deployment
28+
29+
Using SSH:
30+
31+
```bash
32+
USE_SSH=true yarn deploy
33+
```
34+
35+
Not using SSH:
36+
37+
```bash
38+
GIT_USER=<Your GitHub username> yarn deploy
39+
```
40+
41+
If you are using GitHub pages for hosting, this command is a convenient way to build the website and push to the `gh-pages` branch.

‎agent.did.json‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
{
2+
"@context": [
3+
"https://w3id.org/did",
4+
"https://w3id.org/nostr/context"
5+
],
6+
"id": "did:nostr:b7a12e7d26af373b3181e844a688107505144feae5a99643a0f417c15dbe7c53",
7+
"type": "DIDNostr",
8+
"verificationMethod": [
9+
{
10+
"id": "did:nostr:b7a12e7d26af373b3181e844a688107505144feae5a99643a0f417c15dbe7c53#key1",
11+
"type": "Multikey",
12+
"controller": "did:nostr:b7a12e7d26af373b3181e844a688107505144feae5a99643a0f417c15dbe7c53",
13+
"publicKeyMultibase": "fe70102b7a12e7d26af373b3181e844a688107505144feae5a99643a0f417c15dbe7c53"
14+
}
15+
],
16+
"authentication": [
17+
"#key1"
18+
],
19+
"assertionMethod": [
20+
"#key1"
21+
],
22+
"service": []
23+
}

‎docs/architecture/brain-and-hands.md‎

Lines changed: 155 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,155 @@
1+
---
2+
sidebar_position: 3
3+
title: Brain & Hands
4+
description: How OpenClaw separates reasoning (LLM) from execution (shell, files, browser)
5+
---
6+
7+
# Brain & Hands
8+
9+
OpenClaw separates AI reasoning from system execution into two distinct layers.
10+
11+
## The Brain (Reasoning Engine)
12+
13+
The Brain is the LLM that interprets requests and decides what to do.
14+
15+
### Supported Providers
16+
17+
| Provider | Models | Config Key |
18+
|----------|--------|------------|
19+
| **Anthropic** | Claude Opus 4.6, Sonnet 4.5, Haiku 4.5 | `anthropic` |
20+
| **OpenAI** | GPT-5.3-Codex, GPT-4o | `openai` |
21+
| **xAI** | Grok | `xai` |
22+
| **Local** | Any model via Ollama or vLLM | `local` |
23+
24+
### Configuration
25+
26+
```yaml title="~/.openclaw/config.yml"
27+
brain:
28+
provider: "anthropic"
29+
model: "claude-opus-4-6"
30+
api_key: "${ANTHROPIC_API_KEY}" # Or set env var
31+
temperature: 0.7
32+
max_tokens: 4096
33+
34+
# Fallback if primary provider is down
35+
fallback:
36+
provider: "openai"
37+
model: "gpt-4o"
38+
```
39+
40+
### How the Brain Works
41+
42+
1. Receives a message (from user, channel, or heartbeat)
43+
2. Loads relevant memory context
44+
3. Applies active skill instructions
45+
4. Generates a plan (internal chain-of-thought)
46+
5. Outputs either a response, a tool call, or both
47+
48+
The Brain never directly touches the filesystem or network — it requests actions from the Hands.
49+
50+
## The Hands (Execution Environment)
51+
52+
The Hands execute what the Brain decides to do.
53+
54+
### Capabilities
55+
56+
| Hand | Description | Examples |
57+
|------|-------------|---------|
58+
| **Shell** | Execute terminal commands | `ls`, `git`, `python`, `curl` |
59+
| **Filesystem** | Read/write/modify files | Create configs, edit code, manage logs |
60+
| **Browser** | Chromium automation | Fill forms, scrape pages, take screenshots |
61+
| **HTTP** | Make API requests | REST calls, webhook delivery |
62+
63+
### Shell Execution
64+
65+
By default, commands run with the same permissions as the user who started OpenClaw:
66+
67+
```yaml title="~/.openclaw/config.yml"
68+
hands:
69+
shell:
70+
enabled: true
71+
timeout: 30000 # ms, per command
72+
allowed_commands: [] # Empty = all allowed
73+
blocked_commands:
74+
- "rm -rf /"
75+
- "shutdown"
76+
- "reboot"
77+
```
78+
79+
### Browser Automation
80+
81+
OpenClaw includes a headless Chromium instance for web tasks:
82+
83+
```yaml title="~/.openclaw/config.yml"
84+
hands:
85+
browser:
86+
enabled: true
87+
headless: true
88+
timeout: 60000
89+
allowed_domains: [] # Empty = all allowed
90+
```
91+
92+
:::tip
93+
Set `headless: false` during development to watch the browser in action.
94+
:::
95+
96+
### Sandboxing
97+
98+
For production deployments, you can isolate the Hands:
99+
100+
```yaml title="~/.openclaw/config.yml"
101+
hands:
102+
sandbox:
103+
enabled: true
104+
type: "docker" # or "firejail" on Linux
105+
image: "openclaw/sandbox:latest"
106+
network: false # Disable network in sandbox
107+
writable_paths:
108+
- "~/.openclaw/memory"
109+
- "/tmp/openclaw"
110+
```
111+
112+
## Brain-Hands Communication
113+
114+
The Brain and Hands communicate through a structured tool-call protocol:
115+
116+
```json
117+
// Brain requests action
118+
{
119+
"type": "tool_call",
120+
"tool": "shell",
121+
"args": {
122+
"command": "git status",
123+
"cwd": "/home/user/project"
124+
}
125+
}
126+
127+
// Hands return result
128+
{
129+
"type": "tool_result",
130+
"tool": "shell",
131+
"output": "On branch main\nnothing to commit, working tree clean",
132+
"exit_code": 0
133+
}
134+
```
135+
136+
The Brain can chain multiple tool calls in sequence, analyzing each result before deciding the next step.
137+
138+
## Cost Considerations
139+
140+
OpenClaw's token consumption is a commonly cited concern:
141+
142+
- **Average daily cost**: $5–50 depending on usage and model
143+
- **Heartbeat alone**: ~$1–5/day (varies by interval and task count)
144+
- **Heavy automation**: Can spike significantly with complex skills
145+
146+
To manage costs:
147+
- Use cheaper models for simple tasks (`haiku` for heartbeat, `opus` for complex work)
148+
- Increase heartbeat interval
149+
- Use [local models](/guides/local-models) to eliminate API costs entirely
150+
151+
## See Also
152+
153+
- [Local Models Guide](/guides/local-models) — Run without API costs
154+
- [Configuration Reference](/reference/configuration) — All brain/hands settings
155+
- [Security Hardening](/security/hardening) — Restricting execution capabilities

‎docs/architecture/gateway.md‎

Lines changed: 112 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,112 @@
1+
---
2+
sidebar_position: 2
3+
title: The Gateway
4+
description: The central long-running process that manages channels, orchestration, and the WebSocket control plane
5+
---
6+
7+
# The Gateway
8+
9+
The Gateway is OpenClaw's core — a single long-running Node.js process that manages all communication, orchestration, and execution.
10+
11+
## Starting the Gateway
12+
13+
```bash
14+
# Foreground (for development)
15+
openclaw gateway
16+
17+
# As a daemon (for production)
18+
openclaw gateway --daemon
19+
20+
# With custom port
21+
openclaw gateway --port 19000
22+
```
23+
24+
## WebSocket Control Plane
25+
26+
The Gateway exposes a WebSocket server (default: `ws://localhost:18789`) that serves as the control plane for:
27+
28+
- **CLI communication** — `openclaw chat` and other commands connect here
29+
- **Channel bridges** — Messaging platforms send/receive through WebSocket
30+
- **Health monitoring** — Status checks and metrics
31+
- **Skill execution** — Skills communicate results back through the control plane
32+
33+
### Connecting to the Control Plane
34+
35+
```typescript
36+
const ws = new WebSocket('ws://localhost:18789');
37+
38+
ws.on('message', (data) => {
39+
const msg = JSON.parse(data);
40+
console.log(msg.type, msg.payload);
41+
});
42+
43+
ws.send(JSON.stringify({
44+
type: 'chat',
45+
payload: { text: 'Hello from my custom client' }
46+
}));
47+
```
48+
49+
## Daemon Mode
50+
51+
When installed as a daemon (`openclaw onboard --install-daemon`), the Gateway:
52+
53+
- Starts on system boot
54+
- Restarts on crash
55+
- Logs to `~/.openclaw/logs/gateway.log`
56+
- Manages PID file at `~/.openclaw/gateway.pid`
57+
58+
### Daemon Management
59+
60+
```bash
61+
# Check status
62+
openclaw status
63+
64+
# View logs
65+
openclaw logs
66+
67+
# Restart
68+
openclaw gateway restart
69+
70+
# Stop
71+
openclaw gateway stop
72+
```
73+
74+
## Process Lifecycle
75+
76+
```
77+
Boot → Load Config → Initialize Memory
78+
→ Start WebSocket Server
79+
→ Connect Channels
80+
→ Register Skills
81+
→ Start Heartbeat Timer
82+
→ Ready (accepting connections)
83+
```
84+
85+
On shutdown, the Gateway:
86+
1. Sends disconnect to all channels
87+
2. Saves pending memory updates
88+
3. Closes WebSocket connections
89+
4. Writes final log entry
90+
91+
## Configuration
92+
93+
Gateway settings in `~/.openclaw/config.yml`:
94+
95+
```yaml
96+
gateway:
97+
port: 18789
98+
host: "127.0.0.1" # Bind to localhost only
99+
max_connections: 10
100+
log_level: "info" # debug, info, warn, error
101+
pid_file: "~/.openclaw/gateway.pid"
102+
```
103+
104+
:::danger
105+
**Never bind the Gateway to `0.0.0.0` or a public interface.** This exposes the control plane to the network. Security researchers found [40,000+ exposed instances](/security/known-vulnerabilities) doing exactly this.
106+
:::
107+
108+
## See Also
109+
110+
- [Configuration Reference](/reference/configuration) — Full gateway config options
111+
- [Gateway API](/reference/gateway-api) — WebSocket message protocol
112+
- [Security Hardening](/security/hardening) — Securing the gateway

0 commit comments

Comments
 (0)