OpenClaw Setup

Choose Your Workflow

8-10 min
Beginner

Tailoring Strategy

This guide helps you choose the most suitable OpenClaw configuration based on your usage pattern. Different workflows suit different scenarios:

  • macOS 用户：Use the OpenClaw macOS app for a stable experience
  • 开发者/高级用户：Run Gateway in terminal for bleeding-edge features
  • Linux 用户：Use systemd daemon for persistent运行

Stable Workflow (macOS App)

Suitable for most macOS users, provides GUI and automatic updates.

# Install OpenClaw macOS app

brew install --cask openclaw

Credential Storage

  • • macOS Keychain: ~/Library/Keychains/login.keychain-db
  • • Config file: ~/.openclaw/openclaw.json

Advantages

  • ✓ Automatic background运行
  • ✓ GUI management
  • ✓ Automatic updates
  • ✓ System notification integration

Bleeding Edge Workflow (Terminal Gateway)

Suitable for developers and advanced users who want the latest features and full control.

# Install and run Gateway

# {isZh ? '使用 npm 安装' : 'Install with npm'}
npm install -g @openclaw/gateway

# {isZh ? '或使用 curl 快速安装' : 'Or quick install with curl'}
curl -fsSL https://get.openclaw.ai | sh

# {isZh ? '启动 Gateway' : 'Start Gateway'}
openclaw gateway start

Important Notes

  • • Manual restart required after system reboot
  • • Use tmux or screen for persistent sessions
  • • Config file location remains the same

Advantages

  • ✓ Access to latest features
  • ✓ Full control over configuration
  • ✓ Ideal for development and debugging
  • ✓ Access to detailed logs

Common Footguns

1. Credential Permission Issues

Ensure ~/.openclaw directory permissions are correct. Incorrect permissions prevent credential reading.

chmod 700 ~/.openclaw

2. Port Conflicts

Default Gateway port is 18789. If occupied, modify in configuration.

openclaw configure --section gateway --key port --value 18790

3. API Key Environment Variables

Ensure environment variables are set in shell config (~/.zshrc or ~/.bashrc).

export ANTHROPIC_API_KEY="sk-ant-..."

4. Node.js Version

OpenClaw requires Node.js 22 or higher. Use nvm for easy version management.

Credential Storage Map

macOS

Keychain: ~/Library/Keychains/login.keychain-db

Keychain auto-encrypted storage

Linux

Config: ~/.openclaw/openclaw.json

JSON file storage, proper permissions recommended

Windows

Config: %USERPROFILE%\.openclaw\openclaw.json

Use Linux paths in WSL2 environment

Updating Strategy

macOS App

Automatic updates, no manual action needed

brew upgrade --cask openclaw

Optional: manual update to latest version

Terminal Gateway

Update using npm or install script

npm update -g @openclaw/gateway

Or re-run the install script

Linux Systemd Setup

Use systemd for persistent运行 and auto-start of OpenClaw Gateway.

# Create systemd user service

# {isZh ? '服务文件位置' : 'Service file location'}
~/.config/systemd/user/openclaw.service

# {isZh ? '启用并启动服务' : 'Enable and start service'}
systemctl --user enable openclaw.service
systemctl --user start openclaw.service

# {isZh ? '启用 lingering 以保持登录后运行' : 'Enable lingering to run after logout'}
loginctl enable-linger $USER

Service File Example

[Unit]
Description=OpenClaw Gateway
After=network.target

[Service]
Type=simple
ExecStart=/usr/bin/openclaw gateway start
Restart=always
RestartSec=10

[Install]
WantedBy=default.target

Management Commands

  • systemctl --user status openclaw - Check status
  • systemctl --user stop openclaw - Stop service
  • systemctl --user restart openclaw - Restart service
  • journalctl --user -u openclaw -f - View logs

Next Steps

Configuration Wizard

Use the wizard for quick initial setup

Persistent Memory

Learn how OpenClaw remembers you and becomes a unique AI assistant