Stop just chatting with AI! Step-by-step guide to deploying OpenClaw: Let AI take over your keyboard and mouse to work automatically.

As large language models evolve from simple text generation to autonomous agents, chat-based AI interactions no longer satisfy complex engineering demands. OpenClaw breaks this deadlock. No longer a passive chatbot, it acts as a "fully automated digital employee" capable of controlling your keyboard and mouse, executing terminal commands, and autonomously debugging code. As the official stable successor to Clawdbot, OpenClaw inherits powerful automation capabilities while achieving a significant leap in stability. It allows developers to fully delegate tedious tasks like environment setup, Git commits, and complex code refactoring. However, moving from theory to implementation often involves version confusion and dependency conflicts. This OpenClaw AI deployment tutorial skips redundant theory to focus directly on practical production implementation. We will analyze best practices for OpenClaw Docker deployment and provide a troubleshooting guide for OpenClaw local installation. We will demonstrate how to build low-cost local compute clusters via OpenClaw Ollama and OpenClaw DeepSeek integration, and how to embed the tool into team workflows using OpenClaw Feishu integration. Addressing frequent OpenClaw errors during deployment, this article provides verified fixes to help you master this productivity tool and reshape work efficiency while ensuring security isolation.

Must-Read Before Deployment: What is OpenClaw? (Includes Version Pitfall Guide)

Before starting any deployment commands, we need to clarify exactly what OpenClaw is, as well as its chaotic version history over the past few months. Many developers encounter command not found or dependency errors when following old tutorials, which is usually due to confusing project names or misunderstanding the capability boundaries of an "Agent."

🚨 Version Pitfalls: Clawdbot, Moltbot, or OpenClaw?

If you see the names Clawdbot or Moltbot while searching for tutorials, please note: they are both old names for OpenClaw.

The project underwent multiple renames within a short period, leading to severe fragmentation in community documentation. According to the Ollama v0.15.4 Changelog, the official team has formally upgraded and renamed Clawdbot to OpenClaw.

• Clawdbot / Moltbot: Deprecated. Although the ollama launch clawdbot command in old tutorials may still be compatible in some transition versions, it is recommended to stop using it immediately to avoid issues with unmaintained API interfaces.
• OpenClaw: The only currently officially maintained stable version.

Key Tip: In subsequent Docker image pulls or npm installations, please look for the openclaw namespace. Do not mix in old configuration files (such as .clawdbot/clawdbot.json), otherwise it will cause configuration loading failures or Token authentication errors.

Core Definition: More Than Just a Chatbot

OpenClaw is not another ChatGPT web version, nor is it a simple code completion plugin. From a technical architecture perspective, it is an Autonomous AI Agent.

To understand its core value, we can compare the differences between a standard LLM (Large Language Model) and OpenClaw:

Simply put, OpenClaw obtains "proxy rights" to your keyboard and mouse. When you ask it to "build and deploy this React project," it won't just give you a piece of code; instead, it will directly execute npm install inside the container. If it encounters an error, it will read the error log, automatically modify the code, and retry until the task is completed.

🛑 Reality Check: What It Can and Cannot Do

Although OpenClaw is called the "Open Source Devin" or "Fully Automated Programmer," we need to manage expectations before actual deployment. It is not magic, but an engineering tool that requires precise configuration.

1. It is not an out-of-the-box consumer product
   OpenClaw is a tool for developers. It requires you to have basic Docker operations skills and the ability to configure API Keys/local models (such as Ollama). If you are expecting a .exe program that you can "double-click to run," the current OpenClaw might disappoint you.
2. Security risks are real
   Since OpenClaw can execute Shell commands, it has the potential to execute wrong commands. Although the official recommendation is to run it in a Docker container for sandbox isolation, if configured improperly (e.g., mounting the host root directory into the container), AI errors could lead to data loss. Do not run OpenClaw directly on a bare-metal production host.
3. Token consumption may spiral out of control
   OpenClaw's working mode is "loop trial and error." Resolving a complex dependency conflict might require the AI to perform more than 10 "execute-error-correct" loops. If you are using commercial APIs billed by Token (such as GPT-4 or Claude 3.5 Sonnet), a simple task could consume several dollars' worth of quota. For high-frequency use, it is recommended to use local models (such as Qwen2.5-Coder or DeepSeek-V3) to reduce costs.
4. It requires "supervision"
   Current AI Agents have not yet reached 100% reliability. Before it executes high-risk operations like rm -rf or git push, OpenClaw has designed a "Human-in-the-loop" mechanism requiring your confirmation. Do not turn off this confirmation mechanism unless you completely trust it running in an isolated environment.

Deployment Selection and Environment Preparation: Which Method Suits You?

Before typing the first command, choosing the correct deployment architecture is crucial. As an AI Agent capable of executing local operations, OpenClaw's running environment directly determines its response speed, stability, and data security. Blindly following tutorials often leads to falling into "dependency hell" or facing unexpected cloud server bills.

To help you make the choice that best suits you, we have conducted an in-depth comparison of the three mainstream deployment methods from the dimensions of technical threshold, operational costs, and hardware requirements.

1. Deployment Strategy Decision Matrix

Suggestion: For the vast majority of users, Docker containerized deployment is the best balance point. It avoids cumbersome Node.js/Python environment configurations while maintaining local data privacy. If you are a developer and need to debug core logic, you can refer to APIYI's advice to adopt a hybrid deployment strategy.

2. Hardware and Environment "Hard Metrics" (Minimum Viable Specs)

Regardless of which deployment method you choose, OpenClaw has clear baseline requirements for the running environment. Not meeting these conditions is usually the main reason for installation failure (such as EBADENGINE error).

• Operating System:
• • Linux (Recommended): Ubuntu 20.04+, Debian 11+.
  • macOS: Supports Apple Silicon (M1/M2/M3) and Intel chips.
  • Windows: Must use WSL2 (Windows Subsystem for Linux). Running source code directly in PowerShell is extremely prone to C++ compilation errors (such as node-llama-cpp build failures).
• Runtime Environment:
• • Node.js: Must be ≥ v22.12.0. Old versions will cause core services to fail to start.
  • Package Manager: Recommend pnpm (for source deployment) or standard npm.
• Hardware Configuration:
• • Memory (RAM): Minimum 8GB, Recommended 16GB+. If you plan to run large models locally via Ollama (such as DeepSeek-R1), at least 16GB RAM or a dedicated graphics card with 8GB+ VRAM is required.
  • Storage: Reserve at least 10GB of available space (for Docker images and log caching).

3. The Overlooked "Hidden Costs"

Many tutorials claim "0 cost deployment", but this often ignores the actual overhead of long-term operation:

1. API Token Consumption: OpenClaw needs to "think" via LLMs (like Claude 3.5 Sonnet or GPT-4o). High-intensity automation tasks (like automatic coding, crawler analysis) will consume a large amount of Tokens.

• • Strategy: For non-critical tasks, configure OpenClaw to call local Ollama models or domestic high cost-performance models (like DeepSeek), and only fallback to expensive commercial models for complex logic.

1. Electricity and Equipment Wear: As an Agent, OpenClaw is best kept online 24/7 to respond to immediate commands.

• • Strategy: Use low-power devices (like Mac mini, NUC, or Raspberry Pi 5) as the host, rather than letting a high-power gaming PC run around the clock.

1. Network Connection: Docker image pulling and GitHub repository access are extremely unstable in domestic network environments.

• • Strategy: Configure Docker image accelerators or system-level proxies in advance, otherwise you may get stuck at the pulling layers stage for hours.

Core Practice: OpenClaw Docker Containerized Deployment (Recommended)

Compared to the common issues found in source code deployment, such as Node.js version incompatibility, missing pnpm dependencies, and compilation errors, Docker containerized deployment is currently the most stable and accessible way to run OpenClaw. It encapsulates the complex runtime environment (including browser sandboxes and system dependencies) within an image, ensuring an "out-of-the-box" experience.

The following plan is based on a Linux environment (Ubuntu/Debian recommended) or a local machine supporting Docker Desktop, aiming to resolve image pulling and API connection issues within domestic network environments.

1. Plan Directory Structure

To prevent data loss after container restarts (such as account login status and custom scripts), we need to create persistence directories on the host machine first. It is recommended to establish the following structure under /opt or the user directory:

mkdir -p openclaw/data
mkdir -p openclaw/conf
cd openclaw

2. Configure docker-compose.yml

Create a new docker-compose.yml file in the openclaw directory. The following template has been optimized for production environments, including necessary port mappings and environment variable configurations:

version: '3.8'

services:
  openclaw:
    image: ghcr.io/openclaw/openclaw:latest # If pulling is difficult, please refer to the network configuration below
    containername: openclaw
    restart: always
    networkmode: "host" # Host mode is recommended to ensure control over local network devices, or use bridge mode to map ports
    # If not using host mode, please uncomment the following and map ports:
    # ports:
    #   - "18789:18789" # Web console port
    #   - "18790:18790" # Internal communication port
    volumes:
      - ./data:/app/data  # Core data persistence
      - ./conf:/app/conf  # Configuration file persistence
    environment:
      - TZ=Asia/Shanghai
      # If you need OpenClaw to connect to public LLMs (like OpenAI) and the server is in China, you need to configure a proxy:
      # - HTTPPROXY=http://host.docker.internal:7890
      # - HTTPSPROXY=http://host.docker.internal:7890
    deploy:
      resources:
        limits:
          memory: 4G # Limiting memory is recommended to prevent browser processes from consuming too many resources

3. Resolve Domestic Network Connection Issues

Deploying OpenClaw in China mainly faces two major network challenges: image pull failure and container inability to connect to LLM APIs.

• Image Acceleration: ghcr.io (GitHub Container Registry) is extremely unstable to access in China. If you encounter image pull failed, it is recommended to resolve this by configuring Registry Mirrors for the Docker daemon, or by using a proxy to pull the image and then retagging it.
• API Connectivity: OpenClaw needs to interact frequently with LLMs (such as Claude, OpenAI). If your host machine is located in China and you have not deployed a local model (such as Ollama), you must inject HTTP_PROXY and HTTPS_PROXY environment variables into the environment section of docker-compose.yml, pointing to your LAN proxy address.

4. Startup and Initial Configuration

Execute the following command in the terminal to start the container:

docker-compose up -d

After startup, check the logs to ensure the service is running normally:

docker-compose logs -f

Obtain Access Token (Critical Step):
When OpenClaw starts for the first time, it generates a security Token; you cannot access the Web interface directly. According to community practical experience, you need to check the configuration file in the mounted volume to obtain this Token:

1. Enter the configuration directory we created earlier: cat ./conf/openclaw.json (the path may be fine-tuned with versions; if empty, please check the ./data directory).
2. Find the token value under the gateway field, for example 9bfd07dd800a8c....
3. Assemble the access address:
   http://<ServerIP>:18789/?token=<YourToken>

After successful access, you will see the OpenClaw visual operation interface. At this point, you can start configuring LLM providers (such as local Ollama or remote APIs) and issue your first instruction.

Key Configuration Details: config.toml Settings

OpenClaw's config.toml is the "nerve center" of the entire agent. According to community feedback, over 80% of startup failures (such as containers exiting immediately upon startup) are attributed to syntax errors or missing parameters in the configuration file. This section will provide an in-depth analysis of core configuration items and offer a standard template that is ready for immediate reuse.

Core Field Analysis

The core of the configuration lies in accurately connecting with the LLM (Large Language Model) backend. Whether you are using cloud-based DeepSeek or local Ollama, you need to precisely define the following fields in the [llm] or [models] module:

1. API Base URL (base_url): This is the path where OpenClaw looks for the model's "brain".

• • DeepSeek Users: Usually set to https://api.deepseek.com. Please note that some older SDK versions may require the /v1 suffix; referring to the service provider's documentation is recommended.
  • Ollama Users: If running OpenClaw in a Docker container, you must use http://host.docker.internal:11434 instead of localhost; otherwise, the container cannot access the host's Ollama service.

1. API Key (api_key): Authentication credentials. For local Ollama, this can be any string (e.g., ollama), but it cannot be left empty.
2. Model Name (model): Must strictly match the model ID provided by the service provider (e.g., deepseek-chat or qwen2.5-coder:14b). Incorrect IDs will result in 400 Bad Request errors.

Standard Configuration Template (Copy-Paste Friendly)

Below is a verified config.toml structure covering model connection and basic environment settings. You can copy it directly and modify the api_key according to your actual situation.

# OpenClaw Core Configuration File (config.toml)

[general]
# Runtime log level, can be set to "debug" for debugging
loglevel = "info"
# Agent workspace, used to store generated code or downloaded files
workspace = "./data/workspace"

# --- LLM Core Configuration ---
[llm]
# Model provider identifier (openai, deepseek, ollama, etc.)
provider = "deepseek"
# Specific model name, must match strictly
model = "deepseek-chat"
# API base URL (Note: Ollama users need to change to http://host.docker.internal:11434)
baseurl = "https://api.deepseek.com"
# Your API key
apikey = "sk-xxxxxxxxxxxxxxxxxxxxxxxx"
# Maximum context length, prevents memory overflow from long conversations
contextwindow = 16384
# Output randomness, 0.0 is most rigorous, 1.0 is most divergent
temperature = 0.1

# --- Server Settings ---
[server]
# Allow external access
host = "0.0.0.0"
# Web interface port
port = 18789

Common Syntax Traps Causing "Crash on Startup"

When modifying the configuration, be sure to avoid the following common TOML format pitfalls. These errors usually cause the Docker container to silently exit 1-2 seconds after startup:

• Key-value pair format error: TOML uses the equals sign = for assignment; using colons : is strictly prohibited (this is JSON syntax).
• • ❌ Error: model: "deepseek-chat"
  • ✅ Correct: model = "deepseek-chat"
• Missing string quotes: All text values must be wrapped in double quotes "".
• • ❌ Error: provider = deepseek
  • ✅ Correct: provider = "deepseek"
• Boolean case sensitivity: In TOML specifications, boolean values must be all lowercase.
• • ❌ Error: headless = True
  • ✅ Correct: headless = true
• Indentation and hierarchy: Although TOML is less sensitive to indentation than Python, it is recommended to maintain a clear hierarchy. If [table] syntax is used, all key-value pairs under that header belong to that table until the next header appears.

If you encounter a situation where startup fails after configuration, it is recommended to use the docker logs openclaw command to view the logs. If terms like error decoding config or expected value appear in the logs, please immediately check the syntax details mentioned above.

Brain Integration: Connecting DeepSeek and Ollama

OpenClaw itself is an execution framework that requires connecting a Large Language Model (LLM) as a "brain" to understand tasks, plan steps, and generate tool calling instructions. In the current environment, we recommend two mainstream integration solutions: DeepSeek (Cloud API) and Ollama (Local Deployment). The former provides top-tier reasoning capabilities at an extremely low cost, while the latter ensures absolute data privacy and zero marginal cost.

Option 1: Cloud API Integration (DeepSeek Recommended)

For most users, especially those who want to get started quickly and have average hardware configurations, directly calling DeepSeek's API is the best choice. DeepSeek V3 (deepseek-chat) excels in context understanding and code generation, and the API pricing is highly competitive.

Configuration Steps:

1. Get Key: Visit the DeepSeek Open Platform, register an account, and create an API Key (usually starting with sk-).
2. Modify Configuration: In OpenClaw's config.toml or openclaw.json, locate the llm or models section.

The key is to point the baseUrl to DeepSeek's official endpoint and ensure the model name is accurate (DeepSeek officially mandates using deepseek-chat as the model identifier, rather than a specific version number).

[llm]
provider = "deepseek"
# Be sure to use the official OpenAI-compatible address
baseurl = "https://api.deepseek.com"
apikey = "sk-YourKey"
# Note: DeepSeek V3 and V2.5 both use this model name
model = "deepseek-chat"
temperature = 0.0

Note: Although DeepSeek is compatible with the OpenAI SDK, it is recommended to explicitly specify the provider as deepseek or openai in OpenClaw (depending on the specific version's configuration structure) and strictly check whether the base_url includes the /v1 suffix, as some clients may require manual completion.

Option 2: Local Private Deployment (Ollama)

If you possess strong local computing power (such as Mac M-series chips or NVIDIA graphics cards), or have extremely high requirements for data privacy, running local models via Ollama is the ideal solution.

Recommended Models:

• Qwen2.5-Coder (14B/32B): Performs excellently in Tool Calling and is currently one of the most suitable open-source models for Agents.
• DeepSeek-R1 Distill: Strong reasoning capabilities, suitable for complex task planning.

Key Network Pitfalls:
When OpenClaw runs in a Docker container and Ollama runs on the host machine, writing localhost or 127.0.0.1 directly in the configuration file will not work, as this points to the inside of the container.

• Mac/Windows Docker Desktop Users: Please use host.docker.internal.
• Linux Users: It is recommended to use the host's LAN IP (e.g., 192.168.1.5), or add the --network="host" parameter when starting Docker.

Configuration Example (Connecting to Host Ollama from Docker Environment):

{
  "llm": {
    "provider": "ollama",
    // Key point: Use host.docker.internal to penetrate the container and access the host
    "baseurl": "http://host.docker.internal:11434/v1",
    "model": "qwen2.5-coder:14b",
    // In local mode, the API Key can be anything, but leaving it empty is not recommended
    "apikey": "ollama"
  }
}

Comparison and Selection Advice

For users deploying OpenClaw for the first time, it is recommended to first use DeepSeek to run through the process and eliminate local environment interference; once familiar with the Agent operation mechanism, try switching to a local Ollama model to reduce long-term running costs.

Interactive Integration: Connecting OpenClaw to Feishu

Compared to the command-line interface, connecting OpenClaw to Feishu allows your AI Agent to truly integrate into your daily workflow. Through the Feishu mobile app, you can issue commands to the Agent anytime, anywhere, and receive real-time execution feedback. Below are detailed integration steps based on the Feishu Open Platform, focusing on resolving the "callback verification" step where users most often get stuck.

1. Create Application and Obtain Credentials

First, log in to the Feishu Open Platform and enter the "Developer Console".

1. Click "Create Custom App", fill in the application name (e.g., OpenClaw-Bot) and description, upload an icon, and save.
2. Click "Credentials & Basic Info" in the left navigation bar.
3. Key Action: Copy the App ID and App Secret. These values need to be filled into the corresponding fields in OpenClaw's config.toml file.

2. Enable Bot Capabilities and Configure Permissions

To let the Agent understand commands and reply, corresponding API permissions must be enabled.

1. Add Bot Capability: Select "Add App Capabilities" in the left navigation bar, and click the "Add" button behind the "Bot" card.
2. Configure Permission Scopes: Enter "Permission Management", search for and batch enable the following core permissions. Missing any of these will cause the Agent to "read but not reply" or fail to execute:

• • im:message:sendasbot (Send messages as an app): Required, used for the Agent to reply with execution results.
  • im:message.p2p_msg:readonly (Read private messages sent to the bot): Required, used for private chat interactions.
  • im:message.groupatmsg:readonly (Read messages @mentioning the bot in groups): Used for group collaboration.
  • contact:user.employee_id:readonly (Obtain user ID): Used for identity recognition.

Note: After enabling permissions, you must enter the "Version Management & Release" page, create and publish a new version for the permission changes to take effect.

3. Configure Event Subscription (Common Error Point)

This is the step most likely to fail in the entire deployment. Feishu requires real-time handshake verification when saving the "Request URL", so you must strictly follow the order of "Configure Bot first, then save Feishu settings".

1. Obtain Verification Parameters:
   Click "Events & Callbacks" -> "Encryption Strategy" in the Feishu backend left sidebar.

• • Copy the Encrypt Key (click reset to generate if empty).
  • Copy the Verification Token.
  • Remember: Do not rush to configure the "Request URL" at this moment, otherwise it will directly report "Challenge Failed".

1. Update OpenClaw Configuration:
   Return to your server or local configuration file config.toml, find the [feishu] section, and fill in the four parameters obtained just now: App ID, App Secret, Verification Token, Encrypt Key.
   Save the file and restart the OpenClaw container. Ensure container logs show the service has started without errors.
2. Complete Handshake Verification:
   Return to the Feishu "Events & Callbacks" page and click "Configure Subscription".

• • Request URL: Fill in http://<Your Server Public IP>:18789.
  • • Tip: If deploying via Docker, please ensure the security group/firewall has allowed TCP port 18789.
  • Click "Save".
    At this point, Feishu will send a POST request to this address. Upon receipt, OpenClaw will decrypt it using the Token in the configuration file and return the correct response. If configured correctly, the page will prompt "Saved Successfully".

1. Subscribe to Message Events:
   In the "Add Events" area of the "Events & Callbacks" page, search for and add im.message.receive_v1 (Receive messages). This is key to allowing the Agent to listen to user speech.

4. Common Error Troubleshooting

In actual deployment, if you encounter "Verification Token mismatch" or "Request URL verification failed", it is usually caused by the following reasons:

• Order Error: Clicking save on the Feishu side without filling in the Token on the OpenClaw side and starting the service.
• Network Unreachable: Port 18789 on the server is not open to the public. You can use curl http://<IP>:18789 in a local terminal to test connectivity.
• Decryption Failure: The Encrypt Key was copied incorrectly or contains extra spaces.

Once configuration is complete, you can search for the bot in the Feishu client, send "Help" or specific commands (e.g., "Help me check server disk usage"), and verify if the Agent can successfully take over tasks.

Common Errors and Troubleshooting

In the actual deployment process of OpenClaw, environmental differences are often the main reason for the failure of "one-click deployment". The vast majority of runtime errors can be located by viewing container logs. Before performing any fixes, please execute the following commands to obtain core error information:

docker logs -f openclaw
# Or view the last 100 lines of logs
docker logs --tail 100 openclaw

The following are the four most frequent blocking issues reported by the developer community and their solutions.

1. Dependency Installation Failure and Network Timeout

Phenomenon:
During source deployment (Source Install) or image building, npm ERR! fetch failed, Connection timed out, or git clone getting stuck occurs.

Analysis:
In domestic network environments, directly pulling GitHub source code or NPM official sources is very prone to timeouts. Additionally, the latest version of OpenClaw has strict requirements for the Node.js version (usually requires Node >= 22.12.0); version mismatches will lead to EBADENGINE errors.

Solution:

• Switch Mirror Source: If running npm install locally, be sure to configure a domestic mirror source:

    npm config set registry https://registry.npmmirror.com

• Force Docker Usage: To completely solve "Dependency Hell" and environment inconsistency issues, it is strongly recommended to abandon source code execution and directly use Docker images. The Docker image has pre-configured correct Node.js and Python environments, which can avoid 90% of runtime dependency errors.

2. Port Occupied

Phenomenon:
Container startup fails, and logs indicate Error: listen EADDRINUSE: address already in use :::3000 or similar port conflict information.

Analysis:
OpenClaw occupies host ports by default (e.g., 3000 for the Web panel, 18789 for callbacks). If other services (such as Grafana, Gitea, etc.) are already running on the host, it will cause port conflicts.

Solution:

• Check Port Usage:

    lsof -i :3000

• Modify Mapping: Modify the port mapping in docker-compose.yml, mapping another port on the host (e.g., 3001) to the container's port 3000:

    ports:
      - "3001:3000"

After modification, the access address becomes http://localhost:3001.

3. Feishu/DingTalk Callback Failures

Phenomenon:
When configuring the "Request URL" on the Feishu Open Platform, it prompts "URL validation failed", or the Bot cannot receive group messages.

Analysis:
This is the most common configuration error. Feishu and DingTalk webhooks must be accessed via the public internet, and the callback path must match precisely. Local deployments (Localhost/127.0.0.1) cannot be accessed by cloud platforms.

Solution:

• Public IP Verification: Ensure the server has a public IP, and the security group (firewall) has allowed the corresponding port (default 18789).
• Intranet Penetration: If deploying on a local home computer, you must use ngrok, frp, or Cloudflare Tunnel to expose the local port to the public internet.
• Address Format: Strictly check the callback address format. According to troubleshooting experience from the Alibaba Cloud Developer Community, the address should usually be http://<Public-IP>:18789/api/v1/feishu/callback (please refer to the latest OpenClaw documentation for the specific path), and ensure that the correct events (such as im.message.receive_v1) are subscribed to in the Feishu backend.

4. Model Invocation Error "Invalid Beta Flag"

Phenomenon:
When using AWS Bedrock or Google Vertex AI to call Claude models, the log reports invalid beta flag.

Analysis:
OpenClaw's SDK may default to sending request headers containing beta features to the Anthropic API, but managed services like AWS Bedrock do not support these specific beta flags, thus directly rejecting the request.

Solution:
You need to explicitly disable beta features in the configuration file openclaw.json, or switch to the direct connection API.

• Modify Configuration: Add "beta_features": [] in agents.defaults.model.options.
• Reference Fix: For specific configuration paths and cache clearing steps, please refer to the detailed explanation in the relevant technical documentation. Be sure to restart the container after modifying the configuration for it to take effect.