Documentation

Choose how you want to lose time.

āš ļø Compatibility Matrix (What I Did NOT Test)

PlatformStatusNotes
Ubuntu 22.04 + NVIDIA GPUāœ“ TESTEDRTX 3070 Ti (8GB), DeepSeek R1 8B via Ollama
macOS (Apple Silicon)āœ“ TESTEDM1/M2, DeepSeek API via openai provider
Windows (WSL2)āœ— BROKENCUDA passthrough issues. Do NOT report bugs. (Symptom: nvidia-smi works, but Docker sees 0 GPUs)
Docker? UNTESTEDGPU pass-through is your problem.
Node.js < 22āœ— UNSUPPORTEDESM modules require Node 22+. Will crash on import.

If your setup is not listed here: Proceed at your own risk. Do NOT report bugs for untested configurations.

āš–ļø Reality Check

PATH A: CLOUD API

  • Setup time: 5 mins
  • Hardware: Any laptop
  • Cost: ~$1-5/mo (Usage based)
  • Stability: Operationally boring, until rate limits hit

PATH B: LOCAL HARDWARE

  • Setup time: 1-4 hours
  • Hardware: 16GB+ RAM / GPU
  • Cost: Electricity + Sanity
  • Stability: Experimental
RECOMMENDED

Path A: The "Just Work" Method

šŸ’” Why I switched: I tried Path B first and wasted a whole weekend fighting drivers. This costs billable hourly rates, which is cheaper than my hourly rate for debugging CUDA errors.

0. Install Node.js (NVM Required)

WARNING: If node -v returns < 22, STOP. You are wasting your time.(Expect: Error [ERR_REQUIRE_ESM] if you ignore this)

# Install NVM (Node Version Manager)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.0/install.sh | bash

# Reload your shell
source ~/.bashrc  # or: source ~/.zshrc

# Install Node.js 22 (LTS)
nvm install 22
nvm use 22

Do NOT use sudo apt install nodejs. That installs ancient versions.

1. Install OpenClaw

npm install -g openclaw@latest

2. Get DeepSeek Key

Sign up at platform.deepseek.com.

šŸ’” Pro Tip: DeepSeek R1 via API costs ~$1-5/mo for casual use. No VRAM drama.

3. Configure .env

Create .env in the root directory where you run openclaw start.

.env
# DeepSeek R1 via OpenAI-compatible API (RECOMMENDED)
# Get your key at: https://platform.deepseek.com
LLM_PROVIDER="openai"
LLM_BASE_URL="https://api.deepseek.com"
LLM_API_KEY="sk-your-key-here"
LLM_MODEL="deepseek-reasoner"

āš ļø Rate Limit Reality: Expect 429 errors or region latency during peak hours (9AM-11AM Beijing time). This is not a bug, it's the reality of DeepSeek.(Log: HTTP 429 "x-ratelimit-remaining: 0")

Hitting limits? Read the DeepSeek Configuration Guide.

4. Launch

openclaw start
HARDWARE REQUIRED

Path B: Local (Ollama)

āš ļø Warning: If you have less than 16GB RAM, turn back now. Your system will freeze.

Crashed already? Check the CUDA OOM Fix or JSON Parsing Fix.

The Reality of Path B:

I started here. I thought my RTX 3090 (24GB) was enough. It wasn't.

Here is the log from my first run:

[2026-02-01 14:24:43] ERROR: CUDA out of memory. Tried to allocate 128.00 MiB (GPU 0; 23.99 GiB total capacity; 23.10 GiB already allocated; 0 bytes free)

If you choose this path, you are choosing to debug physics.

Stuck on Path B? Read the Real OOM Crash Logs ā†’

VRAM Budget Table (Do The Math):

*Measured on: RTX 3070 Ti (8GB), Context=2048, Model=R1-Distill-8B*

ComponentVRAM Cost
DeepSeek R1 8B Model~4.7 GB
KV Cache (at 2k ctx)~1.5 GB
System overhead~1.0 GB
Total (Minimum)~7.2 GB
8GB GPU Reality: You have < 1GB left for reasoning tokens. Set OLLAMA_NUM_CTX=2048 or die.

Think 16GB means 16GB? Read the Hardware Reality Check ā†’

āš” Shortcut to Sanity

Wasted 4 hours and still OOM? The pro choice is Path A. Rent the metal and start shipping.

ā†’ Switch to Cloud API (DeepSeek)

šŸ›‘ Self-Destruct Checklist:

Step 1: Verify you actually have a GPU:

nvidia-smi # If this fails, you CANNOT use local LLMs. Use PATH A (Cloud API).

Step 2: Check VRAM budget:

# Look for: Memory-Total in nvidia-smi output # 8GB GPU  ā†’ Will OOM with anything beyond num_ctx:2048 # 12GB GPU ā†’ Might survive num_ctx:4096 # 16GB+    ā†’ You're probably fine

If you ignored this checklist: Don't report bugs when your system freezes. You were warned.

1. Install Ollama & Pull Model

# Install Ollama (Mac/Linux)
curl -fsSL https://ollama.com/install.sh | sh

# SAFE MODE: Pull with reduced context (prevents OOM)
OLLAMA_NUM_CTX=2048 ollama run deepseek-r1:8b

# If that works, try 4096:
OLLAMA_NUM_CTX=4096 ollama run deepseek-r1:8b

āš ļø 8GB Blood Oath: 8B model ā‰  8GB VRAM. With long context, you WILL OOM. Always use OLLAMA_NUM_CTX to limit context window.

2. Configure OpenClaw

Create .env in the current working directory (CWD) where you run openclaw start.

.env
LLM_PROVIDER="ollama"
LLM_BASE_URL="http://localhost:11434/v1"
LLM_MODEL="deepseek-r1:8b"

CWD Reality Check: The .env file MUST be where you run the command.

your-project/
ā”œā”€ā”€ .env              ā† PUT IT HERE (NOT in ~)
ā”œā”€ā”€ node_modules/
ā””ā”€ā”€ package.json

# Terminal:
cd your-project/
openclaw start        ā† .env is read from HERE

Fail-Fast Tip: If it freezes on first run, do NOT retry. Lower your context window immediately. Set num_ctx: 2048 and test again.

3. Launch

openclaw start

šŸ›‘ Survival Status Check:

  • [ ] Ran nvidia-smi and verified available VRAM?
  • [ ] .env file exists in current folder?
  • [ ] Using deepseek-reasoner for R1?
  • [ ] Checked OOM solutions?
  • [ ] Set OLLAMA_NUM_CTX=2048 before trying larger contexts?

If you survived all of these and still see crashes: THEN you can report a bug. Bring logs.

System Crashed?

Read the crash logs. Don't touch the settings if it works.

Debug Crash Logs ā†’