Update OpenClaw documentation with deployment details
Update CONTEXT with npm installation model, Homebrew wrapper setup, systemd service config, and MiniMax integration. Expand troubleshooting with gateway, Docker, and Homebrew error scenarios. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
Cal Corum
parent
d0dbe86fba
commit
425bb1abd8
@ -5,11 +5,19 @@
|
||||
OpenClaw is an open-source personal AI assistant that runs locally with autonomous agent capabilities. Originally created as "Clawdbot" by Peter Steinberger, now community-maintained as OpenClaw.
|
||||
|
||||
**Deployment:** LXC 224 (10.10.0.224)
|
||||
**Status:** Deployment in progress
|
||||
**Installation Method:** npm global installation (not Docker)
|
||||
**Status:** Active
|
||||
**Primary Use:** Personal automation, task management, Discord integration
|
||||
|
||||
## Architecture
|
||||
|
||||
### Deployment Model
|
||||
**Installation:** OpenClaw installed globally via npm on LXC host (not containerized)
|
||||
- Installed to: `/usr/lib/node_modules/openclaw/`
|
||||
- Binary symlink: `/usr/bin/openclaw -> ../lib/node_modules/openclaw/openclaw.mjs`
|
||||
- Service management: systemd user service (`openclaw-gateway.service`)
|
||||
- Running as: `root` user (PID varies, check with `ps aux | grep openclaw-gateway`)
|
||||
|
||||
### Gateway-Centric Design
|
||||
- **Gateway Daemon:** Single control plane for all operations
|
||||
- **Messaging:** Handles chat platform integrations (Discord, Telegram, etc.)
|
||||
@ -18,9 +26,68 @@ OpenClaw is an open-source personal AI assistant that runs locally with autonomo
|
||||
|
||||
### Key Components
|
||||
1. **OpenClaw Gateway** - Node.js application, port 18789
|
||||
2. **Docker-in-Docker Sandbox** - Isolated execution environment
|
||||
3. **Persistent Workspace** - `/workspace` for file operations and memory
|
||||
4. **Configuration Layer** - `openclaw.json` + environment variables
|
||||
2. **Docker-in-Docker Sandbox** - Isolated execution environment for skill code execution
|
||||
3. **Persistent Workspace** - `~/.openclaw/` for configuration, agents, and memory
|
||||
4. **Configuration Layer** - `~/.openclaw/openclaw.json` + environment variables
|
||||
|
||||
## System Users and Package Management
|
||||
|
||||
### User Accounts
|
||||
- **root:** System administration, Docker operations, service management
|
||||
- **openclaw:** Non-root user for Homebrew package management (UID 1000)
|
||||
- Member of `sudo` and `docker` groups
|
||||
- Password: `openclaw`
|
||||
- Home directory: `/home/openclaw`
|
||||
|
||||
### Homebrew Installation
|
||||
OpenClaw skills often depend on system binaries distributed via Homebrew. Following OpenClaw's official recommendations, Homebrew is installed for the `openclaw` user.
|
||||
|
||||
**Location:** `/home/linuxbrew/.linuxbrew/`
|
||||
**User:** `openclaw` (non-root, as required by Homebrew)
|
||||
|
||||
**Critical: Homebrew Wrapper for Root Access**
|
||||
|
||||
Since OpenClaw gateway runs as root but Homebrew refuses to run as root, we use a transparent wrapper:
|
||||
|
||||
- **Real brew binary:** `/home/linuxbrew/.linuxbrew/bin/brew.real`
|
||||
- **Wrapper script:** `/home/linuxbrew/.linuxbrew/bin/brew`
|
||||
- **Behavior:** When root runs `brew`, wrapper automatically delegates to `openclaw` user
|
||||
- **Result:** OpenClaw can auto-install skill dependencies without "running as root" errors
|
||||
|
||||
**Usage Patterns:**
|
||||
|
||||
```bash
|
||||
# OpenClaw auto-installs skill dependencies (uses wrapper automatically)
|
||||
# No manual intervention needed when installing skills from web UI
|
||||
|
||||
# Manual installation as root (uses wrapper)
|
||||
brew install <package>
|
||||
brew list
|
||||
|
||||
# Manual installation as openclaw user (direct)
|
||||
su - openclaw
|
||||
brew install <package>
|
||||
brew list
|
||||
|
||||
# Legacy helper script (still available)
|
||||
brew-as-openclaw install <package>
|
||||
```
|
||||
|
||||
**Helper Script:** `/usr/local/bin/brew-as-openclaw`
|
||||
- Legacy wrapper script for explicit `openclaw` user delegation
|
||||
- Still available but unnecessary due to transparent wrapper at brew binary location
|
||||
- Usage: `brew-as-openclaw <command> [args]`
|
||||
|
||||
**PATH Configuration:**
|
||||
- System-wide: `/etc/profile.d/homebrew.sh` adds Homebrew to PATH
|
||||
- User-specific: `openclaw` user's `~/.bashrc` includes Homebrew shellenv
|
||||
- Binaries available at `/home/linuxbrew/.linuxbrew/bin/`
|
||||
- All users can access Homebrew-installed binaries
|
||||
|
||||
### Package Management Strategy
|
||||
1. **System packages:** Install via `apt` as root (Docker, git, curl, etc.)
|
||||
2. **Skill dependencies:** Install via Homebrew as `openclaw` user
|
||||
3. **Node packages:** Install via `npm` within OpenClaw workspace
|
||||
|
||||
## AI Provider Integration
|
||||
|
||||
@ -57,74 +124,176 @@ OpenClaw is an open-source personal AI assistant that runs locally with autonomo
|
||||
|
||||
## Security Model
|
||||
|
||||
### Sandboxing
|
||||
- **Docker-in-Docker:** Code execution isolated in nested containers
|
||||
- **AppArmor:** Unconfined profile required for container nesting
|
||||
- **UID:** Runs as non-root `node` user (UID 1000) inside container
|
||||
### Process Isolation
|
||||
- **Gateway Process:** Runs as root user on LXC host (systemd service)
|
||||
- **Skill Execution:** Code sandboxed in Docker containers spawned by gateway
|
||||
- **Docker Access:** Gateway has access to Docker socket for skill sandboxing
|
||||
- **Container Isolation:** Skills run in isolated containers, not on host
|
||||
|
||||
### Secrets Management
|
||||
- **Storage:** Environment variables via `.env` file
|
||||
- **Interpolation:** `${VAR_NAME}` syntax in openclaw.json
|
||||
- **Scope:** Secrets only accessible to gateway process
|
||||
- **Storage:** `~/.openclaw/openclaw.json` (JSON5 format)
|
||||
- **Environment Variables:** Can be referenced via `${VAR_NAME}` syntax
|
||||
- **Credentials Directory:** `~/.openclaw/credentials/` for sensitive data
|
||||
- **Permissions:** Files owned by root (gateway user)
|
||||
|
||||
### Network Isolation
|
||||
- **Bridge Network:** `openclaw-net` isolates from other services
|
||||
- **Exposed Ports:** Only 18789 (gateway) accessible on host network
|
||||
- **Outbound:** Requires internet access for AI API calls
|
||||
### Network Security
|
||||
- **Exposed Ports:** 18789 (gateway web UI) accessible on LXC network
|
||||
- **Outbound:** Requires internet access for AI API calls (MiniMax, etc.)
|
||||
- **LXC Network:** 10.10.0.224 on internal homelab network
|
||||
- **Discord:** WebSocket connection to Discord API for bot integration
|
||||
|
||||
## Operational Patterns
|
||||
|
||||
### Standard Operations
|
||||
```bash
|
||||
# Start OpenClaw
|
||||
docker compose up -d
|
||||
# Start OpenClaw gateway
|
||||
openclaw gateway start
|
||||
|
||||
# View logs
|
||||
docker compose logs -f openclaw-gateway
|
||||
# Stop OpenClaw gateway
|
||||
openclaw gateway stop
|
||||
|
||||
# Restart after config changes
|
||||
docker compose restart openclaw-gateway
|
||||
# Restart gateway (picks up config changes)
|
||||
openclaw gateway restart
|
||||
|
||||
# Stop service
|
||||
docker compose down
|
||||
# Check service status
|
||||
systemctl --user status openclaw-gateway.service
|
||||
ps aux | grep openclaw-gateway
|
||||
```
|
||||
|
||||
### Viewing Logs
|
||||
```bash
|
||||
# Follow gateway logs
|
||||
journalctl --user -u openclaw-gateway.service -f
|
||||
|
||||
# View recent logs
|
||||
journalctl --user -u openclaw-gateway.service -n 100
|
||||
|
||||
# Check startup logs
|
||||
journalctl --user -u openclaw-gateway.service --since "10 minutes ago"
|
||||
```
|
||||
|
||||
### Pairing Management
|
||||
```bash
|
||||
# List pending pairing requests
|
||||
docker compose exec openclaw-gateway openclaw pairing list discord
|
||||
openclaw pairing list discord
|
||||
|
||||
# Approve pairing
|
||||
docker compose exec openclaw-gateway openclaw pairing approve discord <code>
|
||||
openclaw pairing approve discord <code>
|
||||
|
||||
# Revoke access
|
||||
docker compose exec openclaw-gateway openclaw pairing revoke discord <user_id>
|
||||
openclaw pairing revoke discord <user_id>
|
||||
```
|
||||
|
||||
### Diagnostics
|
||||
```bash
|
||||
# Health check
|
||||
docker compose exec openclaw-gateway openclaw doctor
|
||||
# Full system health check
|
||||
openclaw doctor
|
||||
|
||||
# Channel status
|
||||
docker compose exec openclaw-gateway openclaw channels status --probe
|
||||
# Channel status (Discord, etc.)
|
||||
openclaw channels status --probe
|
||||
|
||||
# Model configuration
|
||||
docker compose exec openclaw-gateway openclaw models list
|
||||
openclaw models list
|
||||
openclaw models get minimax/MiniMax-M2.1
|
||||
|
||||
# Check which user is running gateway
|
||||
ps aux | grep openclaw-gateway | grep -v grep
|
||||
```
|
||||
|
||||
### Configuration Updates
|
||||
```bash
|
||||
# Edit configuration
|
||||
nano openclaw.json
|
||||
nano ~/.openclaw/openclaw.json
|
||||
|
||||
# Restart to apply changes
|
||||
docker compose restart openclaw-gateway
|
||||
openclaw gateway restart
|
||||
|
||||
# Verify changes
|
||||
docker compose logs openclaw-gateway | grep "Configuration loaded"
|
||||
# Verify changes via logs
|
||||
journalctl --user -u openclaw-gateway.service -n 50 | grep -i "config\|error"
|
||||
|
||||
# Check if gateway is running
|
||||
ps aux | grep openclaw-gateway | grep -v grep
|
||||
```
|
||||
|
||||
### Skills Management
|
||||
|
||||
OpenClaw skills extend the assistant's capabilities with specialized tools and integrations.
|
||||
|
||||
**Skill Installation Methods:**
|
||||
|
||||
1. **ClawHub Registry** (recommended):
|
||||
```bash
|
||||
# SSH to LXC as openclaw user
|
||||
ssh openclaw@10.10.0.224
|
||||
cd /opt/openclaw/workspace
|
||||
|
||||
# Install specific skill
|
||||
clawhub install <skill-slug>
|
||||
|
||||
# Sync all configured skills
|
||||
clawhub sync --all
|
||||
|
||||
# Update existing skills
|
||||
clawhub update --all
|
||||
```
|
||||
|
||||
2. **Manual Installation:**
|
||||
```bash
|
||||
# Create skill directory
|
||||
mkdir -p /opt/openclaw/workspace/skills/<skill-name>
|
||||
|
||||
# Create SKILL.md file
|
||||
nano /opt/openclaw/workspace/skills/<skill-name>/SKILL.md
|
||||
```
|
||||
|
||||
**Skill Locations (priority order):**
|
||||
1. `/opt/openclaw/workspace/skills/` (workspace skills, highest priority)
|
||||
2. `~/.openclaw/skills/` (user skills, shared across agents)
|
||||
3. Bundled skills (shipped with OpenClaw)
|
||||
|
||||
**Installing Skill Dependencies:**
|
||||
|
||||
Many skills require system binaries. Install dependencies using Homebrew:
|
||||
|
||||
```bash
|
||||
# From root shell on LXC
|
||||
brew-as-openclaw install jq # JSON processing
|
||||
brew-as-openclaw install ffmpeg # Media processing
|
||||
brew-as-openclaw install imagemagick # Image manipulation
|
||||
|
||||
# Or as openclaw user
|
||||
su - openclaw
|
||||
brew install <package-name>
|
||||
```
|
||||
|
||||
**Enabling Skills:**
|
||||
|
||||
Configure in `openclaw.json`:
|
||||
```json5
|
||||
{
|
||||
"skills": {
|
||||
"entries": {
|
||||
"skill-name": {
|
||||
"enabled": true,
|
||||
"apiKey": "${SKILL_API_KEY}", // If needed
|
||||
"env": {
|
||||
"CUSTOM_VAR": "value"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Security Note:** Always review third-party skill code before enabling. Skills run with full OpenClaw privileges.
|
||||
|
||||
**Common Skills:**
|
||||
- `browser` - Web automation via Playwright
|
||||
- `shell` - Execute shell commands in sandbox
|
||||
- `file-manager` - Advanced file operations
|
||||
- `code-editor` - Code editing and refactoring
|
||||
- `git` - Git repository operations
|
||||
|
||||
## Resource Usage Patterns
|
||||
|
||||
**Expected Baseline:**
|
||||
|
||||
@ -6,9 +6,15 @@ Personal AI assistant running on LXC 224 with MiniMax M2.1 integration and Disco
|
||||
|
||||
- **Gateway Web UI:** http://10.10.0.224:18789
|
||||
- **LXC IP:** 10.10.0.224
|
||||
- **SSH:** `ssh root@10.10.0.224`
|
||||
- **SSH (root):** `ssh root@10.10.0.224`
|
||||
- **SSH (openclaw):** `ssh openclaw@10.10.0.224` (password: `openclaw`)
|
||||
- **Config Location:** `/opt/openclaw/`
|
||||
|
||||
## System Users
|
||||
|
||||
- **root:** System administration, Docker operations
|
||||
- **openclaw:** Homebrew package management, skill dependencies (UID 1000)
|
||||
|
||||
## Quick Commands
|
||||
|
||||
```bash
|
||||
@ -25,6 +31,12 @@ ssh root@10.10.0.224 'cd /opt/openclaw && docker compose exec openclaw-gateway o
|
||||
|
||||
# Health check
|
||||
ssh root@10.10.0.224 'cd /opt/openclaw && docker compose exec openclaw-gateway openclaw doctor'
|
||||
|
||||
# Install skill dependencies via Homebrew
|
||||
ssh root@10.10.0.224 "brew-as-openclaw install jq ffmpeg imagemagick"
|
||||
|
||||
# Install skills (as openclaw user)
|
||||
ssh openclaw@10.10.0.224 'cd /opt/openclaw/workspace && clawhub install <skill-name>'
|
||||
```
|
||||
|
||||
## Current Configuration
|
||||
|
||||
@ -311,6 +311,173 @@ docker compose exec openclaw-gateway env | grep -E "(MINIMAX|DISCORD)"
|
||||
- Don't quote values in .env: `KEY=value` not `KEY="value"`
|
||||
- OpenClaw handles interpolation, Docker doesn't need quotes
|
||||
|
||||
## Skill and Package Management Issues
|
||||
|
||||
### Skill Installation Fails - Missing Binary Dependencies
|
||||
**Symptoms:** Skill reports "command not found" or "binary not available on PATH"
|
||||
|
||||
**Diagnosis:**
|
||||
```bash
|
||||
# Check if binary is installed
|
||||
which <binary-name>
|
||||
|
||||
# List Homebrew packages
|
||||
ssh root@10.10.0.224 "brew-as-openclaw list"
|
||||
```
|
||||
|
||||
**Solutions:**
|
||||
|
||||
1. **Install via Homebrew (recommended for skills):**
|
||||
```bash
|
||||
# From root shell
|
||||
ssh root@10.10.0.224
|
||||
brew-as-openclaw install <package>
|
||||
|
||||
# Or as openclaw user
|
||||
ssh openclaw@10.10.0.224
|
||||
brew install <package>
|
||||
```
|
||||
|
||||
2. **Install via apt (for system tools):**
|
||||
```bash
|
||||
ssh root@10.10.0.224
|
||||
apt-get update
|
||||
apt-get install <package>
|
||||
```
|
||||
|
||||
**Common Skill Dependencies:**
|
||||
- `jq` - JSON processing → `brew-as-openclaw install jq`
|
||||
- `ffmpeg` - Media processing → `brew-as-openclaw install ffmpeg`
|
||||
- `imagemagick` - Image manipulation → `brew-as-openclaw install imagemagick`
|
||||
- `git` - Already installed via apt
|
||||
- `curl` - Already installed via apt
|
||||
|
||||
### Homebrew Command Not Found
|
||||
**Symptoms:** `brew: command not found` when running as openclaw user
|
||||
|
||||
**Diagnosis:**
|
||||
```bash
|
||||
# Check if Homebrew is installed
|
||||
ssh root@10.10.0.224 "ls -la /home/linuxbrew/.linuxbrew/bin/brew"
|
||||
|
||||
# Check PATH configuration
|
||||
ssh openclaw@10.10.0.224 "cat ~/.bashrc | grep brew"
|
||||
```
|
||||
|
||||
**Solutions:**
|
||||
|
||||
1. **Use helper script from root:**
|
||||
```bash
|
||||
ssh root@10.10.0.224 "brew-as-openclaw --version"
|
||||
```
|
||||
|
||||
2. **Fix PATH for openclaw user:**
|
||||
```bash
|
||||
ssh openclaw@10.10.0.224
|
||||
echo 'eval "$(/home/linuxbrew/.linuxbrew/bin/brew shellenv bash)"' >> ~/.bashrc
|
||||
source ~/.bashrc
|
||||
brew --version
|
||||
```
|
||||
|
||||
3. **Manual shellenv in commands:**
|
||||
```bash
|
||||
ssh openclaw@10.10.0.224 'eval "$(/home/linuxbrew/.linuxbrew/bin/brew shellenv bash)" && brew list'
|
||||
```
|
||||
|
||||
### ClawHub CLI Not Found
|
||||
**Symptoms:** `clawhub: command not found` when trying to install skills
|
||||
|
||||
**Diagnosis:**
|
||||
```bash
|
||||
# Check if ClawHub CLI is installed
|
||||
ssh openclaw@10.10.0.224 "which clawhub"
|
||||
|
||||
# Check npm global packages
|
||||
ssh openclaw@10.10.0.224 "npm list -g --depth=0"
|
||||
```
|
||||
|
||||
**Solutions:**
|
||||
|
||||
1. **Install ClawHub CLI:**
|
||||
```bash
|
||||
ssh openclaw@10.10.0.224
|
||||
npm install -g clawhub
|
||||
|
||||
# Or install locally in OpenClaw workspace
|
||||
cd /opt/openclaw/workspace
|
||||
npm install clawhub
|
||||
npx clawhub --version
|
||||
```
|
||||
|
||||
2. **Use alternative skill installation:**
|
||||
```bash
|
||||
# Manual skill installation
|
||||
cd /opt/openclaw/workspace
|
||||
mkdir -p skills/<skill-name>
|
||||
nano skills/<skill-name>/SKILL.md
|
||||
```
|
||||
|
||||
### Skill Permission Errors
|
||||
**Symptoms:** "Permission denied" when installing or running skills
|
||||
|
||||
**Diagnosis:**
|
||||
```bash
|
||||
# Check workspace ownership
|
||||
ssh root@10.10.0.224 "ls -la /opt/openclaw/workspace"
|
||||
|
||||
# Check skill directory permissions
|
||||
ssh root@10.10.0.224 "ls -la /opt/openclaw/workspace/skills"
|
||||
```
|
||||
|
||||
**Solutions:**
|
||||
|
||||
1. **Fix ownership (workspace should be accessible to Docker node user, UID 1000):**
|
||||
```bash
|
||||
ssh root@10.10.0.224
|
||||
chown -R 1000:1000 /opt/openclaw/workspace
|
||||
```
|
||||
|
||||
2. **Install skills as openclaw user (UID 1000):**
|
||||
```bash
|
||||
ssh openclaw@10.10.0.224
|
||||
cd /opt/openclaw/workspace
|
||||
clawhub install <skill>
|
||||
```
|
||||
|
||||
### Homebrew Installation Issues
|
||||
**Symptoms:** Homebrew won't install or shows permission errors
|
||||
|
||||
**Diagnosis:**
|
||||
```bash
|
||||
# Check Homebrew directory ownership
|
||||
ssh root@10.10.0.224 "ls -la /home/linuxbrew/.linuxbrew"
|
||||
|
||||
# Check openclaw user exists
|
||||
ssh root@10.10.0.224 "id openclaw"
|
||||
```
|
||||
|
||||
**Solutions:**
|
||||
|
||||
1. **Fix directory ownership:**
|
||||
```bash
|
||||
ssh root@10.10.0.224
|
||||
chown -R openclaw:openclaw /home/linuxbrew
|
||||
```
|
||||
|
||||
2. **Reinstall Homebrew:**
|
||||
```bash
|
||||
ssh root@10.10.0.224
|
||||
rm -rf /home/linuxbrew/.linuxbrew
|
||||
su - openclaw -c 'NONINTERACTIVE=1 /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"'
|
||||
```
|
||||
|
||||
3. **Install system dependencies:**
|
||||
```bash
|
||||
ssh root@10.10.0.224
|
||||
apt-get update
|
||||
apt-get install -y build-essential procps curl file git
|
||||
```
|
||||
|
||||
## Emergency Recovery
|
||||
|
||||
### Complete Service Reset
|
||||
|
||||
Loading…
Reference in New Issue
Block a user