INTRODUCTION TO OPENCLAW AND ITS EVOLUTION
OpenClaw represents a significant advancement in the realm of self-hosted AI assistants, offering developers and power users a robust platform for building intelligent code assistants that run entirely on their own infrastructure. This open-source framework provides unprecedented control over AI-powered automation while maintaining complete data privacy and sovereignty.
The project has a fascinating recent history that reflects the rapid evolution of AI agent technology. It was initially launched in November 2025 by Austrian developer Peter Steinberger under the name "Clawdbot." This name was derived from "Clawd" (now renamed to "Molty"), an AI-based virtual assistant that Steinberger had previously developed. The name "Clawdbot" was a playful reference to Anthropic's Claude AI platform, reflecting the software's origins and inspiration.
On January 27, 2026, Anthropic issued a trademark complaint due to the phonetic and visual similarity between "Clawd" and "Claude." To avoid legal issues and respect Anthropic's intellectual property, Steinberger renamed the project to "Moltbot" on the same day. The name "Moltbot" was chosen to continue the lobster theme that had become associated with the project, symbolizing a lobster shedding its shell to grow and evolve. This rebranding, however, led to some chaos in the community, with scammers quickly snatching up the old GitHub and Twitter handles to promote fraudulent cryptocurrency tokens.
Just three days later, on January 30, 2026, the project underwent its final renaming to "OpenClaw," which remains its current identity. Steinberger explained that "Moltbot" never "quite rolled off the tongue" and felt the name didn't adequately represent the project's vision. The name "OpenClaw" was chosen to emphasize the project's open-source nature while retaining the "claw" heritage from its lobster-themed origins. This final renaming was a more deliberate and careful process, including advance trademark research and securing social media handles and domain names to ensure the name would be permanent and stable.
It's worth noting that "MoltBook" is a separate but related platform that emerged during the same timeframe. MoltBook is an online forum designed exclusively for AI agents to interact with each other, similar in concept to Reddit but for artificial intelligence. The platform was launched in January 2026 by entrepreneur Matt Schlicht. While humans can observe the interactions on MoltBook, they are not intended to participate directly. MoltBook was created specifically for AI agents, particularly those running on OpenClaw software, and Schlicht reportedly used an OpenClaw agent to help build the platform itself. Many AI agents on MoltBook were created using the OpenClaw framework, and OpenClaw gained significant popularity in late January 2026, partly due to the viral success of the MoltBook project. However, MoltBook and OpenClaw are distinct projects serving different purposes, with MoltBook being a social platform for agents and OpenClaw being the underlying agent framework.
Unlike traditional cloud-based AI assistants that process your code and data on remote servers controlled by third parties, OpenClaw operates as a local gateway between your development environment and various AI models. This architecture allows you to choose between running models entirely on your own hardware using tools like Ollama, or connecting to remote API providers such as Anthropic's Claude or OpenAI's GPT models when you need access to more powerful capabilities. This flexibility gives you complete control over the privacy-performance tradeoff based on your specific needs and constraints.
THE ARCHITECTURE OF OPENCLAW
Understanding OpenClaw's architecture is essential before diving into implementation details. The system consists of several interconnected components that work together to create a seamless AI assistant experience.
At the heart of OpenClaw lies the Gateway daemon, which serves as the central coordination point for all messaging connections and AI interactions. This daemon runs persistently in the background, monitoring configured communication channels and routing requests to the appropriate AI models. The gateway can be configured with authentication tokens to prevent unauthorized access, and should always be bound to localhost rather than all interfaces for security reasons. Binding to all interfaces would expose your gateway to network access, creating potential security vulnerabilities. The Control UI runs on port 18789 and provides a web interface for managing your OpenClaw instance.
The Brain component represents the intelligence layer of OpenClaw. This is where the actual AI model integration occurs, whether you're connecting to local models running through Ollama or remote APIs from providers like Anthropic, OpenAI, or Google Gemini. The Brain handles prompt construction, context management, and response processing. It manages the conversation history and ensures that the AI model has appropriate context for each request.
Perhaps the most powerful aspect of OpenClaw's architecture is its Skills system, which follows the AgentSkills standard. The AgentSkills standard is an open specification originally developed by Anthropic and adopted by several AI coding assistants including OpenClaw, Claude Code, Cursor, VS Code extensions, OpenAI Codex, Gemini CLI, and GitHub Copilot, making skills potentially portable across different platforms. Skills are modular extensions that teach your AI agent how to perform specific tasks. Each skill is defined using a SKILL.md file within a dedicated directory, containing both metadata in YAML frontmatter format and detailed instructions in Markdown format.
The Tools layer provides the fundamental capabilities that skills can leverage. These tools include file system operations for reading and writing code files, shell execution for running commands and scripts, web browsing capabilities for accessing documentation and online resources, and network operations for interacting with APIs. It's critically important to understand that installing a skill does not grant new permissions to your AI agent. Permissions are determined solely by which Tools you have enabled in your configuration, providing a security boundary between skill installation and actual system access.
INSTALLATION AND SETUP COMMANDS
Before you can build a code assistant with OpenClaw, you need to properly install and configure the framework. Here are the complete step-by-step installation commands and procedures.
Prerequisites
First, verify that you have the necessary prerequisites installed on your system.
Check Node.js Version:
node --version
You need Node.js version 22 or higher. If you don't have Node.js installed or need to upgrade, the recommended approach is to use nvm (Node Version Manager).
Install nvm (if not already installed):
# For macOS and Linux
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
# Reload your shell configuration
source ~/.bashrc # or ~/.zshrc for Zsh users
Install Node.js 22 using nvm:
nvm install 22
nvm use 22
nvm alias default 22
Verify Installation:
node --version
npm --version
Installation Methods
OpenClaw offers several installation methods. Choose the one that best fits your needs.
Method 1: Scripted Installer (Recommended for Most Users)
This is the fastest and easiest method, automatically detecting your OS and launching the onboarding wizard:
# Install OpenClaw using the automated script
curl -fsSL https://openclaw.ai/install.sh | bash
If you prefer to review the script before executing it:
# Download the script first
curl -O https://openclaw.ai/install.sh
# Review the script
cat install.sh
# Execute it
bash install.sh
Method 2: NPM Global Install (Better for Multiple Node.js Applications)
# Install OpenClaw globally via npm
npm install -g openclaw@latest
# Run the onboarding wizard and install the daemon
openclaw onboard --install-daemon
Alternatively, if you use pnpm:
# Install using pnpm
pnpm add -g openclaw@latest
# Run onboarding
openclaw onboard --install-daemon
Method 3: Docker Deployment (For Isolation and Security)
Create a docker-compose.yml file:
version: '3.8'
services:
openclaw:
image: openclaw/openclaw:latest
container_name: openclaw
volumes:
- ./openclaw-config:/home/openclaw/.openclaw
ports:
- "127.0.0.1:18789:18789"
restart: unless-stopped
environment:
- NODE_ENV=production
Then run:
# Start OpenClaw in Docker
docker-compose up -d
# View logs
docker-compose logs -f
# Access the container
docker-compose exec openclaw bash
Initial Configuration with Onboarding Wizard
After installation, run the onboarding wizard to configure OpenClaw:
# Start the onboarding wizard
openclaw onboard
The wizard will guide you through several configuration steps:
- Security Warning: Read and accept the security warning about the bot working on your local machine
- Setup Mode: Choose between "Quick Start" (easier with sensible defaults) or "Advanced" (full control)
- Model Selection: Select your AI provider (Anthropic, OpenAI, Google Gemini, Ollama, etc.)
- API Keys: Provide API keys for your chosen providers
- Messaging Platform: Optionally connect Telegram, WhatsApp, Discord, or Slack
- Skills Installation: Choose whether to install bundled skills
For Telegram Integration:
# During onboarding, you'll need:
# 1. Create a bot via @BotFather on Telegram
# 2. Get the API token
# 3. Find your user ID via @userinfobot
# 4. Paste the token when prompted
Post-Installation Setup
After onboarding completes, perform these essential setup steps:
1. Create Environment File for Credentials:
# Create the .env file
touch ~/.openclaw/.env
# Set restrictive permissions
chmod 600 ~/.openclaw/.env
Edit the file with your credentials:
# Edit the .env file
nano ~/.openclaw/.env
Add your API keys:
# ~/.openclaw/.env
# Anthropic API Key for Claude models
ANTHROPIC_API_KEY=sk-ant-api03-your-actual-key-here
# OpenAI API Key for GPT models
OPENAI_API_KEY=sk-proj-your-actual-key-here
# Gateway Authentication Token
GATEWAY_AUTH_TOKEN=your-secure-random-token-here
# Optional: Ollama base URL if running on non-default port
OLLAMA_BASE_URL=http://127.0.0.1:11434/v1
2. Generate Secure Tokens:
# Generate a secure authentication token
openssl rand -hex 32
Copy the output and use it as your GATEWAY_AUTH_TOKEN.
3. Set File Permissions:
# Set permissions for the OpenClaw directory
chmod 700 ~/.openclaw
# Set permissions for the configuration file
chmod 600 ~/.openclaw/openclaw.json
# Set permissions for the environment file
chmod 600 ~/.openclaw/.env
# Set permissions for credentials directory
chmod 700 ~/.openclaw/credentials
4. Run Security Audit:
# Run a comprehensive security audit
openclaw security audit --deep
Address any security issues identified by the audit.
Gateway Management Commands
Once installed, use these commands to manage the OpenClaw gateway:
# Start the gateway
openclaw gateway start
# Stop the gateway
openclaw gateway stop
# Restart the gateway
openclaw gateway restart
# Check gateway status
openclaw gateway status
# View gateway logs
openclaw logs --follow
# Run health check
openclaw doctor
Skill Management Commands
# List installed skills
openclaw skills list
# Install a skill from ClawHub
openclaw skills install <skill-name>
# Remove a skill
openclaw skills remove <skill-name>
# Update all skills
openclaw skills update
# Search for skills
openclaw skills search <query>
Configuration File Location
OpenClaw stores its configuration at:
~/.openclaw/openclaw.json
You can edit this file directly or use the configuration commands:
# View current configuration
openclaw config show
# Set a configuration value
openclaw config set <key> <value>
# Get a specific configuration value
openclaw config get <key>
Troubleshooting Commands
# Check if port 18789 is available
sudo lsof -i :18789
# Kill process using port 18789 if needed
sudo kill -9 <PID>
# Check Node.js and npm versions
node --version
npm --version
# Check OpenClaw version
openclaw --version
# Reinstall OpenClaw
npm uninstall -g openclaw
npm install -g openclaw@latest
# Clear cache and reinstall
npm cache clean --force
npm install -g openclaw@latest
# View detailed logs with timestamps
openclaw logs --follow --verbose
# Export configuration for backup
openclaw config export > openclaw-backup.json
# Import configuration from backup
openclaw config import < openclaw-backup.json
Pairing and Access Control
# Approve a pairing request
openclaw pairing approve <code>
# List paired devices/users
openclaw pairing list
# Revoke a pairing
openclaw pairing revoke <id>
SETTING UP OPENCLAW FOR CODE ASSISTANT DEVELOPMENT
After installation, you need to configure OpenClaw specifically for code assistant work. The configuration process involves creating and editing the openclaw.json file and setting up appropriate security boundaries.
Creating the Base Configuration
OpenClaw stores its configuration in ~/.openclaw/openclaw.json. This JSON-formatted file controls everything from which AI models your assistant uses to what permissions it has for file system access and command execution.
CRITICAL SECURITY NOTE: By default, OpenClaw stores sensitive information like API keys and authentication tokens in plain text within configuration files. This means that if your system is compromised by an attacker, these credentials could be exposed and used to access your AI services or control your agent. You should run the security audit command with the deep flag after any configuration changes to check for security issues and address them immediately.
Here's a foundational configuration that sets up OpenClaw for code assistant work:
{
"agents": {
"defaults": {
"model": {
"primary": "anthropic/claude-sonnet-4-5"
}
}
},
"gateway": {
"auth": {
"mode": "token",
"token": "${GATEWAY_AUTH_TOKEN}"
},
"bind": "loopback",
"port": 18789
},
"workspace": "~/.openclaw/workspace",
"channels": {
"telegram": {
"enabled": true,
"allowlist": ["@yourusername"]
}
},
"logging": {
"redactSensitive": "tools"
},
"concurrency": {
"maxConcurrent": 4,
"subagents": {
"maxConcurrent": 8
}
}
}
This configuration establishes the basic structure for your code assistant. The workspace directory serves as a sandboxed environment where your assistant can safely create temporary files, store analysis results, and maintain working copies of code it's reviewing or modifying. This isolation helps protect your main project files from accidental modifications.
The primary model specification points to Anthropic's Claude Sonnet 4.5, which offers excellent code understanding and generation capabilities. Claude models are particularly strong at understanding complex code structures, explaining technical concepts, and generating production-quality code across diverse programming languages and frameworks.
The gateway section includes an authentication mode set to "token" and an authentication token that references the environment variable GATEWAY_AUTH_TOKEN. The bind parameter is set to "loopback" which ensures the gateway only accepts connections from localhost (127.0.0.1), preventing network exposure. The port parameter specifies that the Control UI runs on port 18789.
The logging section sets redactSensitive to "tools" which is recommended to redact sensitive data like API keys from tool output in logs.
The concurrency section limits the number of concurrent tasks to prevent resource exhaustion. Setting maxConcurrent to 4-8 prevents a single problematic task from consuming all resources or burning through your API quota.
SECURE CREDENTIAL MANAGEMENT
Rather than storing API keys directly in your openclaw.json configuration file, you should use environment variables stored in the file within your .openclaw directory named .env. This approach keeps sensitive credentials out of your configuration files and version control systems, reducing the risk of accidental exposure.
Here's how to structure your environment file:
# ~/.openclaw/.env
# Anthropic API Key for Claude models
ANTHROPIC_API_KEY=sk-ant-api03-your-actual-key-here
# OpenAI API Key for GPT models
OPENAI_API_KEY=sk-proj-your-actual-key-here
# Gateway Authentication Token
GATEWAY_AUTH_TOKEN=your-secure-random-token-here
# Optional: Ollama base URL if running on non-default port
OLLAMA_BASE_URL=http://127.0.0.1:11434/v1
# Optional: Brave Search API Key for web search
BRAVE_SEARCH_API_KEY=your-brave-search-key-here
# Optional: OpenRouter API Key
OPENROUTER_API_KEY=sk-or-your-openrouter-key-here
After creating this .env file, you must set restrictive permissions to prevent other users on your system from reading your credentials:
chmod 600 ~/.openclaw/.env
With your credentials securely stored, you can reference them in your OpenClaw configuration using environment variable syntax with the dollar sign, curly braces, and variable name format:
{
"env": {
"ANTHROPIC_API_KEY": "${ANTHROPIC_API_KEY}",
"OPENAI_API_KEY": "${OPENAI_API_KEY}",
"GATEWAY_AUTH_TOKEN": "${GATEWAY_AUTH_TOKEN}"
},
"agents": {
"defaults": {
"model": {
"primary": "anthropic/claude-sonnet-4-5"
}
}
},
"gateway": {
"auth": {
"mode": "token",
"token": "${GATEWAY_AUTH_TOKEN}"
},
"bind": "loopback",
"port": 18789
},
"models": {
"providers": {
"anthropic": {
"apiKey": "${ANTHROPIC_API_KEY}"
},
"openai": {
"apiKey": "${OPENAI_API_KEY}"
}
}
},
"workspace": "~/.openclaw/workspace"
}
This configuration demonstrates proper credential management by referencing environment variables instead of hardcoding sensitive values. OpenClaw will automatically read the .env file and substitute the variable references with the actual values at runtime.
INTEGRATING LOCAL LLMS WITH GPU ACCELERATION
One of OpenClaw's most compelling features for code assistant development is its robust support for local language models through Ollama integration. Running models locally offers several significant advantages for developers and organizations with privacy or cost concerns.
First, running models locally provides complete data privacy since your code never leaves your machine. This is particularly important when working with proprietary code, sensitive business logic, or data subject to regulatory compliance requirements. Second, local models eliminate per-token costs after the initial setup investment in hardware. While cloud API providers charge based on usage, local models only require the upfront cost of compatible hardware. Third, local models allow you to work offline or in restricted network environments where internet access is limited or prohibited.
However, local model performance depends heavily on hardware acceleration, which is where GPU support becomes critical. Modern GPUs from NVIDIA, AMD, and Apple provide the parallel processing capabilities necessary to run large language models at acceptable speeds. Without GPU acceleration, model inference on CPU alone can be prohibitively slow for interactive use.
Ollama supports multiple GPU acceleration frameworks across different hardware platforms.
NVIDIA CUDA Support:
NVIDIA GPUs are widely supported through CUDA, which stands for Compute Unified Device Architecture. To use NVIDIA GPU acceleration with Ollama, you need an NVIDIA GPU with compute capability 5.0 or higher, though 7.0 or higher is recommended for optimal performance. This includes RTX 20, 30, 40, and 50 series cards, GTX 16 series and above, and NVIDIA Tesla Series professional GPUs. You can check your GPU's compute capability on the NVIDIA developer website by looking up your specific GPU model. The NVIDIA driver version must be 545 or newer to ensure compatibility with recent CUDA features. You should install CUDA Toolkit version 12.3 or newer for optimal performance, as this provides optimized libraries and support for advanced precision formats.
For larger models such as Llama 70B, GPUs with 48GB or more VRAM are recommended. Suitable options include the NVIDIA A6000 with 96GB VRAM or the NVIDIA H100 with 80GB VRAM. For smaller models in the 7B to 13B parameter range, consumer GPUs like the RTX 4090 with 24GB VRAM or RTX 4080 with 16GB VRAM provide good performance. For small models around 7B parameters, at least 16GB of VRAM is recommended, while a general recommendation is 6GB or more for basic functionality.
Multi-GPU setups are supported through the CUDA_VISIBLE_DEVICES environment variable. For example, to use only the first two GPUs in a four-GPU system, you would set this variable to specify GPUs zero and one before starting Ollama. Proper installation of NVIDIA drivers and the CUDA toolkit is crucial for GPU acceleration to function correctly.
Apple Silicon Metal Support:
Apple Silicon Macs with M1, M2, and M3 chips support GPU acceleration via the Metal API, which is Apple's graphics and compute framework. Ollama is built on llama.cpp with the Metal backend and runs natively on Apple Silicon, providing excellent performance without requiring additional configuration. Metal is built directly into the Ollama binary for Apple Silicon, requiring no additional installation steps.
Apple's unified memory architecture, where CPU and GPU share the same memory pool, allows larger models than traditional discrete GPU VRAM limits would suggest. For example, an M3 Max with 128GB of unified memory can run a 70B parameter model using GPU acceleration without aggressive quantization, benefiting from the high memory bandwidth of Apple's architecture. For Apple M-series Macs, 32GB or more of RAM is recommended for running larger models effectively.
The Metal backend is automatically detected and used by Ollama on Apple Silicon Macs, requiring no manual configuration. Performance is generally excellent for models sized appropriately for the available unified memory.
AMD GPU Support via ROCm and Vulkan:
AMD GPU support is available through ROCm, which stands for Radeon Open Compute, on Linux systems. ROCm version 6.0 or newer is required for AMD GPU acceleration with Ollama, with some configurations requiring ROCm 7.2 or later for specific GPU architectures. Installation and configuration of ROCm can be more complex than NVIDIA CUDA, and compatibility varies depending on the specific AMD GPU model and Linux distribution. Officially supported cards include AMD Radeon RX 9000, RX 7000, and RX 6000 Series, as well as AMD Instinct MI200 and MI300 series GPUs. The AMD Instinct series offers high VRAM capacity, with up to 192GB for the MI300X model.
For AMD GPUs, at least 16GB of VRAM is recommended for small models, with 48GB or more for large models. The latest AMD drivers version 6.0 or newer must be installed. As of late 2025, ROCm was noted to be unstable and challenging to configure on some systems.
Vulkan support is available as an experimental feature for additional GPU acceleration on Windows and Linux systems. To enable Vulkan acceleration, you need to set the environment variable OLLAMA_VULKAN to 1 for the Ollama server before starting it. On some Linux distributions, you might need to add the ollama user to the render group to grant proper permissions for GPU access. Vulkan can serve as a more reliable alternative for some AMD systems where ROCm might be problematic.
It's important to note that performance with AMD GPUs may not match NVIDIA CUDA for all model architectures, and Vulkan support is still experimental and may have stability or performance issues.
When configuring OpenClaw to use local models with GPU acceleration, you need to ensure that Ollama is properly installed and configured to utilize your available hardware. Ollama will automatically detect and use CUDA, Metal, or ROCm if the necessary drivers and libraries are properly configured on your system.
OpenClaw requires models with a minimum 64k token context length to complete multi-step tasks effectively. This large context window allows the agent to maintain awareness of extensive code files, previous conversation history, and complex task requirements throughout a coding session.
Here's a configuration example that sets up OpenClaw to use a local Ollama model optimized for coding tasks:
{
"agents": {
"defaults": {
"model": {
"primary": "ollama/qwen3-coder-next"
}
}
},
"models": {
"providers": {
"ollama": {
"baseUrl": "http://127.0.0.1:11434/v1",
"apiKey": "ollama-local",
"api": "openai-completions"
}
}
},
"workspace": "~/.openclaw/workspace"
}
This configuration demonstrates several important concepts for local model integration. The baseUrl parameter points to Ollama's local API endpoint, which by default runs on port 11434. The path "/v1" indicates the API version. The apiKey field contains a placeholder value since local Ollama instances don't require authentication, but the field must be present for compatibility with OpenClaw's provider system.
The api field specifies "openai-completions" because Ollama implements an OpenAI-compatible API, allowing OpenClaw to communicate with it using the same protocol it would use for OpenAI's remote services. This compatibility layer simplifies integration and allows OpenClaw to treat local and remote providers uniformly.
The model "qwen3-coder-next" is specifically designed for coding agents and local development environments. It's optimized for agentic coding workflows and is noted for its strong performance in coding agent tasks and tool-calling capabilities. It utilizes a Mixture-of-Experts architecture, activating 3 billion parameters at a time from a total of 80 billion, making powerful AI coding accessible without relying on expensive cloud APIs. For developers in 2026, starting with Qwen3-Coder via Ollama is recommended for a free and capable primary coding assistant.
Alternative models worth considering include Qwen2.5-72B for general tasks when using Ollama, DeepSeek-Coder-V2 which is an open-source Mixture-of-Experts code language model that performs comparably to GPT-4 Turbo in code-specific tasks, and DeepSeek-R1 which is optimized for reasoning, problem-solving, and factual retrieval. The Qwen3-235B-A22B model is the flagship of the Qwen3 family and achieves competitive results in benchmarks for coding, math, and general capabilities.
CONFIGURING REMOTE LLM PROVIDERS WITH FALLBACK SUPPORT
While local models offer privacy and cost advantages, remote API providers like Anthropic and OpenAI deliver state-of-the-art performance that can significantly enhance your code assistant's capabilities. These models excel at complex reasoning tasks, understanding nuanced requirements, and generating high-quality code across diverse programming languages and frameworks. They benefit from massive training datasets and computational resources that exceed what's practical for local deployment.
OpenClaw's flexible provider system allows you to configure multiple remote providers simultaneously with intelligent fallback behavior. This ensures your code assistant remains operational even during API outages, rate limiting, or service degradation from any single provider.
Here's a complete multi-provider configuration with fallback support:
{
"agents": {
"defaults": {
"model": {
"primary": "anthropic/claude-sonnet-4-5",
"fallbacks": [
"openai/gpt-4-turbo",
"ollama/qwen3-coder-next"
]
}
}
},
"models": {
"providers": {
"anthropic": {
"apiKey": "${ANTHROPIC_API_KEY}",
"baseUrl": "https://api.anthropic.com"
},
"openai": {
"apiKey": "${OPENAI_API_KEY}",
"baseUrl": "https://api.openai.com/v1"
},
"ollama": {
"baseUrl": "http://127.0.0.1:11434/v1",
"apiKey": "ollama-local",
"api": "openai-completions"
}
},
"heartbeat": {
"model": "openai/gpt-3.5-turbo"
}
},
"gateway": {
"auth": {
"mode": "token",
"token": "${GATEWAY_AUTH_TOKEN}"
},
"bind": "loopback",
"port": 18789
},
"workspace": "~/.openclaw/workspace",
"logging": {
"redactSensitive": "tools"
},
"concurrency": {
"maxConcurrent": 4,
"subagents": {
"maxConcurrent": 8
}
}
}
This configuration establishes a robust three-tier fallback system that maximizes reliability and availability. Under normal circumstances, your code assistant will use Claude Sonnet 4.5, which offers excellent code understanding and generation capabilities with strong reasoning abilities. If Anthropic's API becomes unavailable due to outages, rate-limited due to high usage, or experiences degraded performance, OpenClaw automatically switches to GPT-4 Turbo from OpenAI. If both remote providers fail or become unavailable, the system falls back to your local Ollama model running Qwen3-Coder-Next, ensuring your code assistant remains operational even during network outages or widespread API disruptions.
The baseUrl parameters explicitly specify the API endpoints for each provider. While these are the default values and could be omitted, including them makes the configuration more explicit and allows for easy modification if you're using alternative endpoints or proxy services.
The heartbeat section specifies a cheaper model for simple, frequent health checks to save costs. Using GPT-3.5 Turbo for heartbeat tasks is recommended instead of expensive models.
BUILDING A CODE GENERATION ASSISTANT: FROM AUTOCOMPLETE TO AGENTIC CODING
Modern AI-powered code editors like GitHub Copilot, Cursor, Windsurf, and Claude Code have revolutionized software development by providing intelligent code completion, generation, and refactoring capabilities directly within the development environment. While these tools typically operate as IDE extensions with tightly integrated user interfaces, OpenClaw can be configured to provide similar code generation capabilities through a different architectural approach that emphasizes flexibility, privacy, and control.
Understanding the Code Generation Landscape
Understanding the different paradigms of AI-assisted coding helps clarify what OpenClaw can accomplish and how it differs from commercial alternatives.
GitHub Copilot pioneered inline code completion, suggesting code as you type based on context from the current file and nearby files. By 2026, Copilot has advanced significantly to include an "Agent Mode" that supports multi-step agentic tasks capable of generating or modifying code across an entire repository. It can handle tasks like scaffolding entire features, implementing multi-file plans, and automated workflows. Copilot offers code review features, can generate commit messages and pull request summaries, and includes Autofix for security vulnerabilities. It boasts deep integration with GitHub workflows and is widely adopted by enterprises. Users can choose from multiple AI models optimized for different workflows, including quick edits, debugging, and agentic tasks. Users report up to 51% faster coding and 88% code retention.
Cursor is an AI-first integrated development environment, a fork of VS Code, designed for deep AI integration. It provides deep, context-aware AI assistance with whole codebase understanding. By 2026, Cursor has become a standard for "Agentic Coding," allowing developers to describe high-level tasks (e.g., "create a login page") which the AI then plans, generates, and edits across multiple files autonomously. A standout feature is its ability to apply edits across dozens of files in a single iteration while maintaining code consistency. Cursor's "Cursor Tab" predicts entire blocks of changes and cursor positions, offering ultra-low latency. Cursor supports various LLMs, including GPT-4, Claude Opus 4.5/Sonnet, Google's Gemini 3 Pro, and its own Composer model, allowing users to switch models based on the task. Cursor supports Agent Skills, defined in SKILL.md files, which allow agents to discover and apply domain-specific knowledge and workflows. It also utilizes subagents to handle discrete parts of a parent agent's task in parallel. Cursor offers a privacy mode for enterprise clients, ensuring code is not stored or used for model training.
Windsurf aims for speed and an intuitive AI code generation and completion experience, offering a lightweight editor interface. It's known for having a generous free tier. Its "Cascade" feature is designed for deep multi-file edits, understanding project-wide context to modify complex architectures simultaneously. The "Flow" feature uses a "deep-context" engine to understand the entire repository, terminal output, and documentation. "Supercomplete" offers advanced code prediction by anticipating developer needs. Windsurf is an AI-first IDE with a "Cascade agent" that integrates smoothly into typical workflows. It focuses on real-time collaboration and rapid code generation, making it effective for team settings. Windsurf can analyze terminal output, such as build failures and stack traces, and suggest fixes.
Claude Code is a repo-aware command-line interface assistant that excels at understanding complex problems, debugging, refactoring, and architectural decisions. It's not designed for real-time inline code completion like Copilot. It leverages Claude's advanced reasoning capabilities and large context windows (up to 200K tokens) to understand entire codebases and perform multi-file changes. Claude Code can reason over a codebase, plan multi-file changes, implement them, and help verify results through natural language. It can also create subagents to solve specific problems and manage its context window. Claude Code supports "Skills," which are markdown files with precise instructions that teach Claude Code how to perform tasks it can't do natively, such as generating images or optimizing UI design. It's particularly strong for Python development, understanding existing codebases, performing safe refactors, and generating tests. Enterprises are integrating Claude Code across their development lifecycle to accelerate delivery while maintaining quality standards.
OpenClaw's Approach to Code Generation
OpenClaw approaches code generation differently from these IDE-integrated tools. Rather than providing inline autocomplete as you type, OpenClaw operates as a conversational agent that you interact with through messaging platforms or its Control UI. This architectural difference means OpenClaw excels at deliberate, request-based code generation rather than predictive autocomplete. You explicitly ask for code to be generated, reviewed, or modified, and the assistant responds with complete, well-formed code blocks rather than line-by-line suggestions.
This approach offers several distinct advantages:
- Complete Control: You maintain complete control over when and how AI assistance is invoked, preventing unexpected or unwanted suggestions from interrupting your flow
- Conversational Refinement: The conversational interface allows for iterative refinement through natural dialogue, making it easy to clarify requirements and adjust generated code
- Deep Integration: OpenClaw's architecture supports deep integration with your local development environment through shell access, file system operations, and custom skills
- Privacy-First: Privacy-conscious developers can run entirely local models, ensuring code never leaves their machine
- Editor-Agnostic: The platform is editor-agnostic, working with any text editor or IDE rather than requiring specific extensions or integrations
- Agentic Workflows: OpenClaw can autonomously write code, debug, manage files, and execute commands, similar to Cursor's Composer mode and Windsurf's Cascade feature
While OpenClaw doesn't provide real-time inline autocomplete like Copilot, it excels at agentic coding workflows where you describe what you want and the AI autonomously plans, generates, and implements multi-file changes. For developers who want the best of both worlds, OpenClaw can be used alongside tools like Cursor or Copilot, with OpenClaw handling complex multi-file tasks and architectural decisions while the IDE extension provides inline suggestions.
CONFIGURING OPENCLAW FOR CODE GENERATION WORKFLOWS
To build an effective code generation assistant with OpenClaw, you need to optimize your configuration for this specific use case. Code generation requires models with strong programming knowledge, large context windows to understand substantial code files, and the ability to follow detailed specifications accurately.
Here's a comprehensive configuration optimized for code generation:
{
"agents": {
"coder": {
"name": "CodeGenerator",
"model": {
"primary": "anthropic/claude-sonnet-4-5",
"fallbacks": [
"ollama/qwen3-coder-next",
"ollama/deepseek-coder-v2"
]
},
"systemPrompt": "You are an expert software engineer specializing in generating high-quality, production-ready code. You write clean, well-documented code following best practices and language-specific conventions. You consider edge cases, error handling, and maintainability. You explain your design decisions and suggest improvements to requirements when appropriate. When generating code, you provide complete, runnable implementations with all necessary imports, error handling, and documentation.",
"maxTokens": 8192,
"temperature": 0.3
},
"defaults": {
"model": {
"primary": "ollama/qwen3-coder-next",
"fallbacks": [
"anthropic/claude-haiku-4",
"anthropic/claude-sonnet-4-5"
]
}
}
},
"models": {
"providers": {
"anthropic": {
"apiKey": "${ANTHROPIC_API_KEY}",
"baseUrl": "https://api.anthropic.com"
},
"ollama": {
"baseUrl": "http://127.0.0.1:11434/v1",
"apiKey": "ollama-local",
"api": "openai-completions"
}
}
},
"tools": {
"read": {
"enabled": true,
"allowlist": [
"~/projects",
"~/workspace",
"~/.openclaw/workspace"
],
"denylist": [
"~/.ssh",
"~/.openclaw/.env",
"~/.openclaw/credentials",
"~/Documents/Personal",
"~/.aws",
"~/.config"
]
},
"write": {
"enabled": true,
"approvalRequired": false,
"allowlist": [
"~/projects",
"~/.openclaw/workspace"
],
"denylist": [
"~/.ssh",
"~/.openclaw/.env",
"~/.openclaw/credentials",
"~/projects/.git",
"~/projects/node_modules",
"/etc",
"/usr",
"/bin"
]
},
"exec": {
"enabled": true,
"approvalRequired": true,
"allowlist": [
"git",
"npm",
"node",
"python",
"python3",
"cargo",
"go",
"jest",
"pytest",
"mvn",
"gradle",
"make",
"rustc",
"javac",
"gcc",
"g++"
],
"denylist": [
"rm",
"sudo",
"chmod",
"chown",
"dd",
"mkfs"
],
"timeout": 30000
},
"web_search": {
"enabled": true,
"maxResults": 10
},
"web_fetch": {
"enabled": true
},
"browser": {
"enabled": false
}
},
"gateway": {
"auth": {
"mode": "token",
"token": "${GATEWAY_AUTH_TOKEN}"
},
"bind": "loopback",
"port": 18789
},
"workspace": "~/.openclaw/workspace",
"logging": {
"redactSensitive": "tools"
},
"concurrency": {
"maxConcurrent": 6,
"subagents": {
"maxConcurrent": 12
}
}
}
This configuration creates a specialized "coder" agent optimized for code generation with several key features:
Specialized Agent Configuration: The "coder" agent uses Claude Sonnet 4.5 as the primary model for its superior code generation capabilities, with local Ollama models as fallbacks. The system prompt is carefully crafted to emphasize production-ready code with proper error handling, documentation, and best practices.
Temperature Setting: The temperature is set to 0.3, which is lower than the default. This makes the code generation more deterministic and focused, reducing creative variations that might introduce bugs or inconsistencies while still allowing some flexibility for elegant solutions.
Increased Token Limit: The maxTokens is set to 8192, allowing the agent to generate substantial code files or multiple related files in a single response. This is essential for complex features that require significant implementation.
Tool Permissions for Code Generation: The read tool has access to your projects directory for understanding existing code context. The write tool can create and modify files in your projects directory, but with explicit denylists to protect critical areas like .git directories and node_modules. The exec tool is configured with approval required, ensuring you review commands before execution, but includes an allowlist of common development tools like compilers, build tools, and test runners.
Higher Concurrency: The concurrency limits are increased to 6 for main tasks and 12 for subagents, allowing the code generation agent to work on multiple files or subtasks in parallel, significantly speeding up complex multi-file implementations.
CREATING CUSTOM SKILLS FOR CODE GENERATION
The true power of OpenClaw for code generation emerges when you create custom skills tailored to your specific development workflows and tech stack. Skills in OpenClaw follow the AgentSkills standard, which uses SKILL.md files to define capabilities.
Skill: Advanced Code Generator
Let's create a comprehensive code generation skill:
---
name: code-generator
description: Generates complete, production-ready code from specifications with proper error handling, documentation, and tests
metadata:
openclaw:
emoji: "⚡"
bins:
- node
- python3
install:
os:
- darwin
- linux
- windows
---
# Code Generator Skill
This skill generates complete, production-ready code from natural language specifications or requirements. It creates well-structured, documented code following best practices for the target language and framework.
## Usage
Request code generation by describing what you need. You can specify the programming language, framework, and any specific requirements. Examples include asking to create a REST API endpoint in Node.js with Express, generate a React component for user authentication, write a Python function to process CSV files, or create a database migration for a new feature.
## Supported Languages and Frameworks
The skill supports multiple programming languages and their popular frameworks. For JavaScript and TypeScript, it supports Node.js with Express, Fastify, or NestJS for backend development, React, Vue, or Angular for frontend development, and Next.js or Nuxt for full-stack applications. For Python, it supports Flask or FastAPI for web APIs, Django for full-stack web applications, and data processing with pandas and numpy. For Java, it supports Spring Boot for enterprise applications and Maven or Gradle for build configuration. For Go, it supports standard library HTTP servers, Gin or Echo frameworks, and gRPC services. For Rust, it supports Actix-web or Rocket for web services, and Tokio for async runtime. For Ruby, it supports Rails for full-stack applications and Sinatra for lightweight APIs.
## Code Generation Process
The skill follows a systematic process to generate high-quality code. First, it analyzes the requirements by understanding the functional requirements, identifying technical constraints, determining the appropriate language and framework, and considering scalability and performance needs. Next, it designs the solution by planning the code structure and architecture, identifying necessary dependencies and imports, designing data models and interfaces, and planning error handling and edge cases. Then it generates the implementation by writing complete, runnable code with all necessary imports and dependencies, proper error handling and validation, comprehensive inline documentation and comments, following language-specific best practices and idioms, and implementing security best practices. After generation, it includes tests by generating unit tests for core functionality, providing integration test examples, and including test data and fixtures when appropriate. Finally, it provides documentation by creating README files with usage instructions, documenting API endpoints or public interfaces, providing setup and installation instructions, and including example usage and code snippets.
## Code Quality Standards
All generated code must meet high quality standards. For structure and organization, code must use clear, descriptive names for variables, functions, and classes, organize code into logical modules or files, follow the principle of single responsibility, and maintain consistent formatting and style. For error handling, code must validate all inputs and parameters, handle edge cases and boundary conditions, provide meaningful error messages, and implement proper exception handling. For documentation, code must include docstrings or JSDoc for all public functions and classes, explain complex logic with inline comments, document assumptions and limitations, and provide usage examples. For security, code must sanitize and validate user inputs, avoid hardcoded secrets or credentials, implement proper authentication and authorization where needed, and follow OWASP guidelines for web applications. For testing, code must be structured to facilitate unit testing, include comprehensive test coverage, provide test fixtures and mock data, and include both positive and negative test cases.
## Output Format
The skill generates code with a specific structure. It starts with a summary explaining what was generated, the approach taken, and any important design decisions. Next comes the implementation section with complete code files, proper file structure and organization, all necessary imports and dependencies, and inline documentation. Then it provides tests with unit test files, integration test examples, and test data and fixtures. After that comes the setup instructions with installation steps, configuration requirements, and environment setup. Finally, it includes usage examples showing how to use the generated code, example API calls or function invocations, and expected outputs.
## Example Interaction
When a user requests a REST API endpoint for user registration with email validation and password hashing, the assistant will analyze requirements to understand it needs user registration functionality, email validation, secure password storage, and error handling for duplicate users. It will design the solution by choosing Express.js for the framework, planning to use bcrypt for password hashing, implementing email validation with regex or a library, and designing the user data model. Next, it will generate the implementation including the Express route handler, password hashing with bcrypt, email validation logic, error handling for duplicates and validation failures, and proper HTTP status codes. It will generate tests including unit tests for email validation, password hashing verification, tests for duplicate user handling, and integration tests for the complete endpoint. Finally, it will provide documentation with setup instructions, API endpoint documentation, example request and response, and security considerations.
## Best Practices
The skill follows several best practices to ensure quality. It generates complete, runnable code that can be executed immediately without requiring manual fixes or additions. It follows language-specific conventions and idioms to ensure the code feels natural to developers familiar with that language. It includes comprehensive error handling to make the code robust and production-ready. It provides thorough documentation so developers can understand and maintain the code. It considers security implications and implements appropriate safeguards. It generates tests alongside implementation to ensure code quality and facilitate future changes.
Skill: Multi-File Project Generator
For more complex scenarios, create a skill that can generate entire project structures:
---
name: project-scaffolder
description: Generates complete project structures with multiple files, configuration, and boilerplate code
metadata:
openclaw:
emoji: "🏗️"
bins:
- node
- git
install:
os:
- darwin
- linux
- windows
---
# Project Scaffolder Skill
This skill generates complete project structures from high-level descriptions, including all necessary files, configuration, dependencies, and boilerplate code.
## Usage
Request project scaffolding by describing the type of project you want to create. Examples include creating a new React application with TypeScript and Tailwind CSS, scaffolding a Python FastAPI microservice with Docker, generating a full-stack Next.js app with authentication, or creating a Rust CLI application with argument parsing.
## Project Types
The skill can scaffold various types of projects. For web applications, it creates frontend projects with React, Vue, or Angular, backend APIs with Node.js, Python, or Go, and full-stack applications with Next.js, Nuxt, or similar frameworks. For microservices, it generates service templates with Docker and docker-compose, API gateway configuration, and database integration. For CLI applications, it creates command-line tools in Python, Rust, or Go with argument parsing and configuration management. For libraries and packages, it scaffolds npm packages, Python packages with setuptools or poetry, and Rust crates with proper project structure.
## Generated Project Structure
The skill generates a complete project structure with several components. The source code includes properly organized directories, entry points and main files, configuration files for the framework, and example components or modules. The configuration section includes package manager configuration like package.json or Cargo.toml, build tool configuration such as webpack, vite, or tsconfig, linter and formatter configuration like ESLint and Prettier, and environment variable templates. The development tools include Docker and docker-compose files, development scripts in package.json, hot reload configuration, and debugging configuration. The testing infrastructure includes test framework setup, example test files, test configuration, and CI/CD pipeline templates. The documentation includes README with project overview and setup instructions, API documentation or code examples, contribution guidelines, and license file.
## Scaffolding Process
The skill follows a systematic scaffolding process. First, it analyzes the requirements to understand the project type and purpose, identify required technologies and frameworks, determine deployment target and environment, and consider scalability and performance needs. Next, it plans the structure by designing the directory organization, identifying all necessary files and configurations, planning the dependency tree, and determining development workflow. Then it generates the files by creating all source code files with proper structure, generating configuration files with sensible defaults, setting up build and development scripts, and creating Docker files and deployment configuration. After that, it initializes the project by running package manager initialization if needed, installing dependencies, setting up git repository with proper gitignore, and creating initial commit. Finally, it provides setup instructions with step-by-step setup guide, environment variable configuration, development server startup instructions, and deployment guidelines.
## Configuration Best Practices
All generated projects follow configuration best practices. For dependencies, they include only necessary dependencies to minimize bloat, use specific version ranges to ensure reproducibility, separate dev dependencies from production dependencies, and document why each major dependency is needed. For environment configuration, they use environment variables for sensitive data, provide .env.example templates, document all required environment variables, and use different configs for development, staging, and production. For build configuration, they optimize for development experience with fast rebuilds, configure production builds for performance, enable source maps for debugging, and set up code splitting and lazy loading where appropriate. For code quality, they configure linters with sensible rules, set up formatters for consistent style, enable TypeScript strict mode when applicable, and configure pre-commit hooks for quality checks.
## Output
After scaffolding, the skill provides several outputs. It creates the complete project structure with all files and directories in the workspace or specified location. It provides a detailed README explaining the project structure, how to get started, available scripts and commands, and how to deploy. It generates a setup checklist with required tools and versions, environment variables to configure, and first steps to verify the setup works. It offers next steps with suggested features to implement, areas that need customization, and resources for learning the stack.
## Example
When a user requests a new microservice for user authentication with JWT tokens, the assistant will analyze requirements to understand it needs a REST API for authentication, JWT token generation and validation, user registration and login endpoints, and password hashing and security. It will plan the structure by choosing FastAPI for Python or Express for Node.js, designing the project directory structure, planning database models for users, and identifying necessary dependencies. Next, it will generate the project including the main application file with API routes, authentication middleware for JWT validation, user model and database schema, password hashing utilities, configuration files for the framework and database, Docker files for containerization, and test files for authentication flows. It will initialize the project by creating package.json or requirements.txt, generating .env.example with required variables, initializing git repository, and creating initial commit. Finally, it will provide documentation with README explaining the project, API documentation for endpoints, setup instructions with database migration, and deployment guide for Docker.
Skill: Code Refactoring Assistant
Create a skill specifically for refactoring existing code:
---
name: code-refactorer
description: Refactors existing code to improve quality, performance, and maintainability while preserving functionality
metadata:
openclaw:
emoji: "♻️"
bins:
- node
- git
install:
os:
- darwin
- linux
- windows
---
# Code Refactoring Skill
This skill analyzes existing code and refactors it to improve quality, performance, and maintainability while ensuring functionality is preserved.
## Usage
Request refactoring by specifying the file or code section you want to improve. You can request general refactoring or focus on specific aspects like performance, readability, or security. Examples include refactoring a file to improve readability, optimizing a function for better performance, extracting reusable components from a large file, or modernizing legacy code to use current best practices.
## Refactoring Capabilities
The skill can perform various types of refactoring. For code structure improvements, it extracts functions to reduce complexity, breaks large files into smaller modules, applies design patterns where appropriate, and improves naming for clarity. For performance optimization, it identifies and eliminates performance bottlenecks, optimizes algorithms and data structures, reduces unnecessary computations, and implements caching where beneficial. For maintainability enhancements, it reduces code duplication through abstraction, improves error handling and validation, adds comprehensive documentation, and increases test coverage. For modernization, it updates deprecated APIs and syntax, adopts modern language features, migrates to current framework versions, and improves type safety with TypeScript or type hints.
## Refactoring Process
The skill follows a careful refactoring process. First, it analyzes the current code by reading and understanding the existing implementation, identifying code smells and anti-patterns, assessing performance characteristics, and evaluating test coverage. Next, it plans the refactoring by identifying specific improvements to make, ensuring changes preserve functionality, planning incremental refactoring steps, and considering backward compatibility. Then it implements the changes by refactoring code incrementally, maintaining or improving test coverage, preserving the public API when possible, and adding documentation for changes. After implementation, it validates the refactoring by ensuring all existing tests still pass, verifying performance improvements if applicable, checking for unintended side effects, and confirming the code is more maintainable. Finally, it documents the changes by explaining what was refactored and why, documenting any breaking changes, providing migration guide if needed, and suggesting further improvements.
## Safety Measures
The skill includes several safety measures to prevent breaking changes. Before refactoring, it checks if tests exist for the code being refactored. If tests don't exist, it generates them first to establish a baseline. It performs refactoring incrementally in small, verifiable steps rather than large rewrites. It preserves the public API and behavior unless explicitly asked to change it. It creates a backup or git branch before major refactoring. It validates that all tests pass after each refactoring step. It documents any changes to behavior or API.
## Refactoring Patterns
The skill applies common refactoring patterns. For extract method, it identifies code blocks that can be extracted into separate functions, creates well-named functions with clear purposes, and reduces function complexity and length. For extract class, it identifies cohesive groups of data and methods, creates new classes with single responsibilities, and improves code organization. For replace conditional with polymorphism, it identifies complex conditional logic, creates class hierarchies or strategy patterns, and improves extensibility. For introduce parameter object, it identifies functions with many parameters, creates objects to group related parameters, and improves function signatures. For replace magic numbers with constants, it identifies hardcoded values, creates named constants with clear meaning, and improves code readability.
## Output Format
The skill provides refactoring output in a specific format. It starts with a refactoring summary explaining what was refactored, why the changes improve the code, and any potential impacts or breaking changes. Next comes the refactored code with the complete refactored implementation, inline comments explaining significant changes, and preserved or improved tests. Then it provides a comparison showing before and after code snippets, highlighting key improvements, and quantifying improvements where possible. After that comes validation results confirming all tests pass, showing performance improvements if measured, and noting any new warnings or issues. Finally, it includes recommendations for further improvements, areas that still need attention, and suggested next steps.
## Example
When a user requests refactoring of a large function with multiple responsibilities, the assistant will analyze the code to understand what the function does, identify distinct responsibilities within it, assess complexity metrics, and review test coverage. It will plan the refactoring by identifying logical sections to extract, designing new function signatures, planning how to maintain backward compatibility, and ensuring tests will still pass. Next, it will implement the refactoring by extracting logical sections into separate functions, creating helper functions for common operations, improving variable and function names, adding documentation for each new function, and updating or adding tests for extracted functions. It will validate the changes by running all existing tests, verifying performance is not degraded, checking code complexity metrics improved, and ensuring the public API remains the same. Finally, it will document the refactoring by explaining the structure improvements, listing the new functions created, showing before and after complexity metrics, and suggesting further improvements like additional test coverage or performance optimization.
OPTIMIZING OLLAMA FOR CODE GENERATION WORKLOADS
When running local models through Ollama for code generation, you can optimize performance through careful model selection and configuration. Code-specific models like Qwen3-Coder-Next, Qwen2.5-Coder, DeepSeek-Coder-V2, or DeepSeek-R1 offer better performance for programming tasks than general-purpose models because they've been specifically trained on large corpora of source code and technical documentation.
You can create a customized model with Ollama using a Modelfile, which allows you to adjust parameters and set a custom system prompt optimized for code generation:
# Modelfile for optimized code generation assistant
# Author: Your Development Team
# Version: 1.0.0
# Last Updated: 2026-02-10
# Specify the base model - Qwen3-Coder-Next is optimized for coding agents
FROM qwen3-coder-next
# Set system prompt optimized for code generation
SYSTEM """
You are an expert software engineer specializing in generating high-quality,
production-ready code. You excel at understanding requirements and translating
them into clean, well-documented, and maintainable code.
When generating code, you:
- Write complete, runnable implementations with all necessary imports
- Follow language-specific best practices and idiomatic conventions
- Include comprehensive error handling and input validation
- Add clear comments explaining complex logic
- Consider edge cases and boundary conditions
- Ensure code is testable and maintainable
- Implement security best practices
- Provide usage examples and documentation
When refactoring code, you:
- Preserve functionality while improving quality
- Identify and eliminate code smells
- Apply appropriate design patterns
- Improve naming and code organization
- Enhance performance where beneficial
- Increase test coverage
You explain your design decisions and suggest improvements to requirements
when you identify potential issues or better approaches.
"""
# Set temperature for more deterministic code generation
# Lower temperature (0.2) reduces randomness for consistent, reliable code
PARAMETER temperature 0.2
# Increase context window for large code files
# 65536 tokens allows working with substantial codebases
PARAMETER num_ctx 65536
# Top-p sampling for balanced creativity
# 0.9 allows some creativity while maintaining quality
PARAMETER top_p 0.9
# Adjust GPU layers based on your VRAM
# For Qwen3-Coder-Next (MoE with 3B active params), adjust based on your GPU
# 8GB VRAM: num_gpu 25-30
# 12GB VRAM: num_gpu 35-40
# 16GB+ VRAM: num_gpu 40-50
PARAMETER num_gpu 40
# Set repetition penalty to avoid repetitive code
PARAMETER repeat_penalty 1.1
# Increase prediction length for generating substantial code blocks
PARAMETER num_predict 4096
# Stop sequences to prevent over-generation
PARAMETER stop "\n\n\n"
PARAMETER stop "```\n\n\n"
Creating and Using the Optimized Model:
# Save the Modelfile above to a file named 'Modelfile.coder'
# Create the customized model
ollama create code-assistant -f ./Modelfile.coder
# Test the model
ollama run code-assistant "Generate a Python function to validate email addresses with comprehensive error handling"
# List all models to confirm creation
ollama list
# Use it in OpenClaw by updating your configuration
Update your OpenClaw configuration to use the optimized model:
{
"agents": {
"coder": {
"model": {
"primary": "ollama/code-assistant"
}
}
},
"models": {
"providers": {
"ollama": {
"baseUrl": "http://127.0.0.1:11434/v1",
"apiKey": "ollama-local",
"api": "openai-completions"
}
}
}
}
GPU Memory Optimization
The num_gpu parameter controls how many model layers are loaded into GPU memory. Higher values improve performance but require more VRAM.
For Traditional Transformer Models (32B parameters):
- 8GB VRAM:
num_gpu 15-20- Mixed GPU/CPU, slower but functional - 12GB VRAM:
num_gpu 25-30- Reasonable performance for most tasks - 16GB VRAM:
num_gpu 35-40- Good performance with most layers on GPU - 24GB VRAM:
num_gpu 40-50- Excellent performance, nearly full GPU offload - 48GB+ VRAM:
num_gpu 60+- Complete GPU offload, maximum performance
For Smaller Models (7B parameters):
- 8GB VRAM:
num_gpu 30-35- Full or near-full GPU offload - 12GB+ VRAM:
num_gpu 35-40- Complete GPU offload
For Mixture-of-Experts Models (like Qwen3-Coder-Next):
MoE models activate only a subset of parameters at a time (e.g., 3B active from 80B total), making them more VRAM-efficient:
- 8GB VRAM:
num_gpu 25-30- Good performance with active parameters on GPU - 12GB VRAM:
num_gpu 35-40- Excellent performance - 16GB+ VRAM:
num_gpu 40-50- Maximum performance
Monitoring GPU Utilization:
# For NVIDIA GPUs
nvidia-smi
# Watch GPU utilization in real-time
watch -n 1 nvidia-smi
# For AMD GPUs
radeontop
# or
rocm-smi
# For Apple Silicon
# Use Activity Monitor > Window > GPU History
Optimal utilization shows:
- High GPU usage (80-100%) during inference
- Memory usage below maximum
- Minimal CPU fallback
- No memory swapping
If you see low GPU utilization, increase num_gpu. If you see out-of-memory errors, decrease num_gpu.
CREATING CUSTOM SKILLS USING THE AGENTSKILLS STANDARD
The true power of OpenClaw emerges when you create custom skills tailored to your specific development workflows. Skills in OpenClaw follow the AgentSkills standard, which uses SKILL.md files to define capabilities. This is an open standard originally developed by Anthropic and adopted by several AI coding assistants including OpenClaw, Claude Code, Cursor, VS Code extensions, OpenAI Codex, Gemini CLI, and GitHub Copilot, making skills potentially portable across different platforms that support the same standard.
Each skill resides in its own directory within your skills folder. The directory contains a SKILL.md file with YAML frontmatter for metadata and Markdown for detailed instructions. You can also include supporting files in optional subdirectories. The scripts subdirectory can contain executable scripts or code that the skill uses. The references subdirectory can hold additional documentation that provides context. The assets subdirectory can store static resources like templates or diagrams that support the skill's functionality.
The SKILL.md file uses YAML frontmatter enclosed by triple dashes to define metadata, followed by Markdown instructions that teach the AI how to use the skill effectively.
The YAML frontmatter contains several important fields. The name field is required and must be a unique identifier for the skill using one to sixty-four characters. It must use lowercase letters, numbers, and hyphens only, and cannot start or end with a hyphen or contain consecutive hyphens. It must also match the parent directory name. The description field is required and provides a concise explanation with a maximum of 1024 characters of what the skill does and when it should be used, helping the agent determine its relevance. The license field is optional and specifies the license name or a reference to a bundled license file. The compatibility field is optional and specifies environment requirements such as intended product, system packages, or network access, with a maximum of 500 characters. The metadata field is optional and provides an arbitrary key-value mapping for additional metadata. The allowed-tools field is optional and experimental, providing a space-delimited list of pre-approved tools the skill may use. The auto-invoke field is optional and defaults to true, but when set to false means the skill is only included when explicitly invoked rather than automatically by the agent based on context. The install field is optional and specifies package managers and packages required for the skill. The bins field is optional and lists binaries that must be present for the skill to load.
Let's create a practical code review skill:
---
name: code-reviewer
description: Analyzes code files for quality issues, potential bugs, security vulnerabilities, and suggests improvements
metadata:
openclaw:
emoji: "🔍"
bins:
- node
install:
os:
- darwin
- linux
- windows
---
# Code Review Skill
This skill performs comprehensive code reviews covering multiple quality dimensions including code quality, potential bugs, security vulnerabilities, performance issues, and testing considerations.
## Usage
Ask the assistant to review a code file by providing the file path. Examples of valid requests include asking to review the code in a specific file path, analyzing a file for security issues, or checking the quality of a script at a particular location.
## Review Process
The skill will analyze the code for several quality dimensions. Code quality examination includes readability, maintainability, adherence to best practices, proper naming conventions, appropriate code organization, and consistency with language idioms. Potential bug detection covers logic errors, edge cases that aren't handled, potential runtime errors, null pointer dereferences, off-by-one errors, and race conditions in concurrent code. Security analysis examines vulnerabilities such as SQL injection risks, cross-site scripting vulnerabilities, insecure authentication or authorization, exposed secrets or credentials, and improper input validation. Performance review identifies inefficiencies such as unnecessary loops, inefficient algorithms, memory leaks, excessive object creation, and opportunities for optimization. Testing assessment evaluates testability of the code, identifies areas that need test coverage, evaluates whether the code is structured to facilitate unit testing, and considers integration testing requirements.
## Steps
The skill follows a systematic process to perform a comprehensive code review. First, it reads the specified code file using the read tool to access the file contents. Next, it identifies the programming language from the file extension and adjusts the review criteria to match language-specific best practices. Then it analyzes the code against the review criteria, examining each function, class, and code block systematically. After analysis, it provides specific, actionable feedback with line references so developers can easily locate and address issues. The skill then saves the review to the workspace as a markdown file with a timestamp for future reference. Finally, it returns the review to the user through the messaging channel with a summary and the most critical findings highlighted.
## Language Support
This skill supports multiple programming languages. JavaScript files use the .js extension. TypeScript files use .ts or .tsx extensions. Python files use the .py extension. Java files use the .java extension. C++ files use .cpp or .cc extensions. C files use the .c extension. Go files use the .go extension. Rust files use the .rs extension. Ruby files use the .rb extension. PHP files use the .php extension. Swift files use the .swift extension. Kotlin files use the .kt extension.
## Output Format
The review should be structured with several key sections. The summary section provides an overall assessment of code quality with a rating that can be Excellent, Good, Fair, Needs Improvement, or Poor. The critical issues section highlights issues that must be addressed immediately, such as security vulnerabilities or severe bugs. The high priority issues section covers important problems that should be fixed soon, such as performance bottlenecks or significant code quality issues. The medium priority issues section addresses issues that should be handled when convenient, such as minor code quality improvements or missing documentation. The low priority issues section mentions nice-to-have improvements such as style inconsistencies or minor optimizations. The positive observations section recognizes well-written code sections, good practices, or clever solutions that deserve acknowledgment. The recommendations section provides specific, actionable suggestions for improvement with examples where appropriate.
Each issue should include the line number or range where the problem occurs, a description of the problem explaining what's wrong, an explanation of why it's problematic and what consequences it might have, and a suggested fix with code examples when applicable showing how to resolve the issue.
## Example
When a user requests a review of a specific authentication file, the assistant will read the file using the read tool to understand its contents. It will then analyze the JavaScript code according to the review criteria, examining all aspects of code quality, security, performance, and testability. Next, it will generate a comprehensive review identifying issues across all quality dimensions with specific line numbers and detailed explanations. The skill will save the review to the workspace with a timestamped filename for future reference. Finally, it will present findings to the user with specific recommendations, line numbers, and code examples showing how to fix identified issues.
This skill demonstrates the proper SKILL.md format with YAML frontmatter defining the skill's name, description, and metadata. The emoji field provides visual identification in the OpenClaw interface, making it easy to recognize the skill at a glance. The bins field specifies that Node.js must be installed for this skill to work, though in this case it's more of a general requirement for OpenClaw itself. The install section specifies which operating systems the skill supports, including darwin for macOS, linux for Linux distributions, and windows for Windows systems.
The Markdown body provides detailed instructions that teach the AI how to perform code reviews effectively. It includes usage examples showing how users should request code reviews, the review process explaining what the skill examines, supported languages to set appropriate expectations, and expected output format to ensure consistent results. This level of detail helps the AI understand when and how to invoke the skill, and what quality of output is expected.
Let's create another skill for generating unit tests:
---
name: test-generator
description: Generates comprehensive unit tests for code files following framework conventions
metadata:
openclaw:
emoji: "🧪"
bins:
- node
install:
os:
- darwin
- linux
- windows
---
# Test Generation Skill
This skill generates comprehensive unit tests for existing code files, following the conventions of popular testing frameworks and ensuring thorough coverage of functionality, edge cases, and error conditions.
## Usage
Request test generation by specifying the file to test. You can provide just the file path for automatic framework detection, or you can optionally specify a testing framework if you want to override the default selection.
## Supported Testing Frameworks
The skill automatically selects appropriate frameworks based on file type and project context. For JavaScript and TypeScript files, Jest is the default framework, but Mocha and Vitest are also supported. The skill will detect which framework your project uses by examining package.json if available. For Python files, pytest is the default framework due to its simplicity and power, but the built-in unittest framework is also supported for projects that prefer standard library tools. For Java files, JUnit 5 is the default framework for its modern features and wide adoption, but JUnit 4 is supported for legacy projects. For Go files, the built-in testing package is used as it's the standard approach for Go projects. For Rust files, the built-in test framework is used as it's integrated into the Rust toolchain. For Ruby files, RSpec is the default framework for its expressive syntax, but Minitest is supported for projects that prefer a simpler approach.
## Test Generation Process
The skill follows a systematic process to generate comprehensive tests. First, it reads the source code file using the read tool to analyze its structure and functionality. Next, it analyzes the code structure, identifying all functions, classes, methods, and their parameters, return types, and dependencies. Then it identifies edge cases and error conditions by examining conditional logic, loops, error handling, and boundary conditions. After analysis, it generates comprehensive test cases covering multiple scenarios. Happy path scenarios test valid inputs and expected behavior. Edge cases and boundary conditions test empty inputs, maximum values, minimum values, and special characters. Error handling and exceptions ensure the code fails gracefully. Input validation verifies that invalid inputs are properly rejected. Integration points test where the code interacts with external systems or dependencies. The skill follows framework-specific conventions and best practices including proper test organization, descriptive test names, appropriate assertions, and setup and teardown procedures. Finally, it saves the generated test file with appropriate naming conventions in the correct location relative to the source file.
## Naming Conventions
The skill follows standard naming conventions for each language. For JavaScript and TypeScript, test files are named with either a .test.js extension or a .spec.ts extension depending on project conventions. The skill will check existing test files to determine which convention your project uses. For Python, test files are named with a test_ prefix followed by the filename and .py extension following the pytest convention, and are typically placed in a tests directory or alongside the source file. For Java, test files are named with the class name followed by Test and the .java extension, and are placed in the corresponding test source directory typically at src/test/java/ mirroring the package structure. For Go, test files are named with the filename followed by _test and the .go extension, and are placed in the same directory as the source file. For Rust, tests are either placed in a tests module within the same file or in separate files in a tests directory for integration tests.
## Safety Features
The skill includes several safety features to prevent data loss and ensure quality. Before creating a test file, the skill checks if a test file already exists at the target location. If a test file exists, the skill saves the generated tests to the workspace directory for review instead of overwriting existing work, preventing accidental loss of hand-written tests. The skill generates complete, runnable test code that can be executed immediately without manual modifications. All necessary imports, dependencies, and setup and teardown code are included in the generated tests. The skill validates that the generated tests follow the syntax and conventions of the target testing framework.
## Output
The skill will perform several actions after generating tests. It generates complete test code covering all identified test cases with proper assertions and error handling. It saves the test file to the appropriate location with correct naming conventions, or to the workspace if a test file already exists. It informs the user of the test file location and whether it was saved to the project or workspace. It provides a summary of test coverage including the number of test cases generated, what functionality is covered, and any areas that may need additional manual testing.
## Example
When a user requests test generation for a specific validator file, the assistant will read the file to understand its functionality. It will analyze the validation functions, identifying all exported functions, their parameters, expected return values, and error conditions. Next, it will generate tests using the appropriate framework covering all functions and edge cases including valid inputs, invalid inputs, boundary conditions, and error scenarios. The skill will check if a test file already exists at the expected location. If the file doesn't exist, it saves the tests with the appropriate naming convention. If it does exist, it saves to the workspace with a timestamped filename for review. Finally, it reports completion with the file location, a summary of test coverage indicating how many test cases were generated and what percentage of the code is covered, and any recommendations for additional testing.
This test generation skill showcases more advanced patterns in skill development. It automatically detects the appropriate testing framework based on the file extension and project context, but also allows users to override this choice when they have specific requirements. The skill follows language-specific naming conventions for test files, ensuring that generated tests integrate seamlessly with existing project structures and build systems.
The skill includes safety features that check whether a test file already exists at the target location. If it does, the new tests are saved to the workspace directory instead of overwriting existing work, preventing accidental data loss of hand-written tests that developers may have carefully crafted.
CONFIGURING TOOLS AND PERMISSIONS
Skills leverage Tools to perform actions, but skills themselves do not grant permissions. Tools are the fundamental capabilities like file access, shell execution, and web browsing. Installing a skill does NOT grant new permissions to your AI agent. Permissions are controlled solely by which Tools you enable in your configuration, providing a security boundary between skill installation and actual system access.
Here's a configuration that enables necessary tools with appropriate security boundaries:
{
"tools": {
"read": {
"enabled": true,
"allowlist": [
"~/projects",
"~/workspace",
"~/.openclaw/workspace"
],
"denylist": [
"~/.ssh",
"~/.openclaw/.env",
"~/.openclaw/credentials",
"~/Documents/Personal",
"~/.aws",
"~/.config"
]
},
"write": {
"enabled": true,
"approvalRequired": false,
"allowlist": [
"~/projects",
"~/.openclaw/workspace"
],
"denylist": [
"~/.ssh",
"~/.openclaw/.env",
"~/.openclaw/credentials",
"~/projects/.git",
"~/projects/node_modules",
"/etc",
"/usr",
"/bin"
]
},
"exec": {
"enabled": true,
"approvalRequired": true,
"allowlist": [
"git",
"npm",
"node",
"python",
"python3",
"cargo",
"go",
"jest",
"pytest",
"mvn",
"gradle"
],
"denylist": [
"rm",
"sudo",
"chmod",
"chown",
"dd",
"mkfs"
],
"timeout": 30000
},
"web_search": {
"enabled": true,
"maxResults": 10
},
"browser": {
"enabled": false
}
}
}
This configuration demonstrates defense-in-depth security through multiple layers of protection. The read tool is restricted to specific directories where your projects and workspace are located, and explicitly denies access to sensitive locations like SSH keys, credential files, AWS configuration, and personal documents. This prevents the AI from accidentally or maliciously accessing sensitive information.
The write tool has even stricter limitations than the read tool, preventing modification of critical areas like the .git directory which contains your version control history, node_modules which contains dependencies, and system directories. This ensures the AI cannot corrupt your project structure or modify system files. The approvalRequired is set to false for write operations to allow the code generation assistant to work autonomously, but you can set this to true if you want to review every file modification.
The exec tool uses an allowlist approach, only permitting specific commands commonly needed for development tasks such as version control operations, package management, running tests, and building projects. It also includes a denylist of dangerous commands like rm for removing files, sudo for executing with elevated privileges, chmod for changing permissions, and dd for low-level disk operations. The approvalRequired parameter is set to true which enables explicit consent mode, requiring approval before executing commands. The timeout parameter is set to 30000 milliseconds, which equals 30 seconds, to prevent runaway processes from consuming resources indefinitely.
Web search is enabled with a maximum results limit to allow the AI to look up documentation and technical information, but the browser tool is disabled to prevent potential security risks from automated web interactions, which could be exploited for prompt injection attacks or unintended data exfiltration. The browser tool can control web browsers, enabling form filling, web scraping, page navigation, and screenshot capture, but this capability is built on direct code execution via the Chrome DevTools Protocol, which presents security risks.
INSTALLING AND MANAGING SKILLS
To install a custom skill in OpenClaw, you place the skill directory in your skills folder. The default skills location is typically ~/.openclaw/skills, but you can configure custom skill paths in your configuration file if you want to organize skills differently.
Installing Custom Skills:
# Create the skills directory if it doesn't exist
mkdir -p ~/.openclaw/skills
# Create a new skill directory
mkdir -p ~/.openclaw/skills/code-reviewer
# Create the SKILL.md file
nano ~/.openclaw/skills/code-reviewer/SKILL.md
# After creating the SKILL.md file, restart the gateway
openclaw gateway restart
# Verify the skill is loaded
openclaw skills list
Installing Skills from ClawHub:
# Search for available skills
openclaw skills search code
# Install a skill from ClawHub
openclaw skills install code-reviewer
# Update all installed skills
openclaw skills update
# Remove a skill
openclaw skills remove code-reviewer
Managing Skill Permissions:
You can control which skills are active using the configuration file:
{
"skills": {
"allowBundled": [
"code-reviewer",
"test-generator",
"project-scaffolder"
]
}
}
This whitelist mode ensures only explicitly approved skills are loaded, providing an additional security layer.
CRITICAL SECURITY WARNING: Be extremely cautious when installing skills from third-party sources. Malicious actors can disguise malware as legitimate skills, and the consequences can be severe. Skills can contain instructions that cause the AI to perform dangerous actions. These dangerous actions include downloading and executing binaries from external sources, which could be malware, ransomware, or cryptocurrency miners. Skills might access sensitive files outside the workspace, such as SSH private keys, password databases, or confidential documents. They could exfiltrate data to remote servers controlled by attackers, potentially stealing your code, credentials, or personal information. Malicious skills might execute arbitrary shell commands with your user privileges, potentially compromising your entire system. They could modify system configurations or install persistence mechanisms that survive reboots.
Always review a skill's SKILL.md file and any accompanying scripts before installation. Look for suspicious patterns that might indicate malicious intent. Obfuscated or encoded content that's difficult to understand may be hiding malicious instructions. Unexpected network requests to unfamiliar domains or IP addresses should raise red flags. File access patterns that go outside normal boundaries, such as reading from SSH directories or system directories, are concerning. Downloads from unknown sources or instructions to execute downloaded files should be carefully scrutinized. Requests to disable security features or bypass sandboxing are major warning signs. Overly broad permissions requests that aren't necessary for the skill's stated purpose indicate potential malicious intent.
OpenClaw provides security features including allowlist configuration for commands and structure-based blocking to prevent dangerous command patterns, but these are not foolproof and can be bypassed by sophisticated attacks. The safest approach is to only install skills you've personally reviewed and trust, or skills from well-known, reputable sources with a track record of security.
Additionally, both OpenClaw and MoltBook have faced security issues related to malicious skills. Indirect prompt injection attacks targeting OpenClaw have been observed on MoltBook, where malicious instructions were embedded in posts to manipulate OpenClaw agents into performing unintended actions. This demonstrates that even seemingly benign content can contain hidden instructions that exploit AI agents.
ADVANCED SECURITY: CONTAINERIZED DEPLOYMENT
For maximum security, consider deploying OpenClaw in a containerized environment using Docker. This provides an additional isolation layer that contains potential security breaches and limits the blast radius if the AI agent is compromised. Containers provide process isolation, filesystem isolation, and network isolation that can prevent a compromised agent from affecting your host system.
Here's a Dockerfile for running OpenClaw in a container:
FROM node:22-slim
# Create non-privileged user to run OpenClaw
# This ensures the container doesn't run as root
RUN useradd -m -s /bin/bash openclaw
# Install system dependencies needed for development tools
RUN apt-get update && apt-get install -y \
git \
python3 \
python3-pip \
curl \
&& rm -rf /var/lib/apt/lists/*
# Switch to non-privileged user for all subsequent operations
USER openclaw
WORKDIR /home/openclaw
# Install OpenClaw globally for the openclaw user
RUN npm install -g openclaw
# Create workspace and config directories
RUN mkdir -p ~/.openclaw/workspace ~/.openclaw/skills
# Expose gateway port if needed for external access
# Note: In production, bind this to localhost only
EXPOSE 18789
# Set up volume for persistent configuration
# This allows configuration to persist between container restarts
VOLUME ["/home/openclaw/.openclaw"]
# Health check to ensure the gateway is running properly
HEALTHCHECK --interval=30s --timeout=10s --start-period=5s --retries=3 \
CMD curl -f http://localhost:18789/health || exit 1
# Start OpenClaw gateway as the main container process
CMD ["openclaw", "gateway", "start"]
Building and Running the Container:
# Build the container image
docker build -t openclaw-secure:latest .
# Create a directory for persistent configuration
mkdir -p ~/openclaw-config
# Run the container with volume mounting
docker run -d \
--name openclaw \
-v ~/openclaw-config:/home/openclaw/.openclaw \
-p 127.0.0.1:18789:18789 \
openclaw-secure:latest
# View logs
docker logs -f openclaw
# Stop the container
docker stop openclaw
# Start the container again
docker start openclaw
# Access the container shell
docker exec -it openclaw bash
Enhanced Security with Docker:
For even greater security, run the container with additional restrictions:
# Run with enhanced security restrictions
docker run -d \
--name openclaw-hardened \
--read-only \
--security-opt=no-new-privileges \
--cap-drop=ALL \
--tmpfs /tmp:rw,noexec,nosuid,size=100m \
-v ~/openclaw-config:/home/openclaw/.openclaw \
-v ~/openclaw-workspace:/home/openclaw/workspace:rw \
-p 127.0.0.1:18789:18789 \
openclaw-secure:latest
This configuration:
- Makes the root filesystem read-only (
--read-only) - Prevents privilege escalation (
--security-opt=no-new-privileges) - Drops all Linux capabilities (
--cap-drop=ALL) - Allows writing only to temporary directories and mounted volumes
- Binds the port to localhost only, preventing network exposure
Docker Compose Configuration:
For easier management, use Docker Compose:
version: '3.8'
services:
openclaw:
build: .
container_name: openclaw
restart: unless-stopped
read_only: true
security_opt:
- no-new-privileges:true
cap_drop:
- ALL
tmpfs:
- /tmp:rw,noexec,nosuid,size=100m
volumes:
- ./openclaw-config:/home/openclaw/.openclaw
- ./openclaw-workspace:/home/openclaw/workspace:rw
ports:
- "127.0.0.1:18789:18789"
environment:
- NODE_ENV=production
healthcheck:
test: ["CMD", "curl", "-f", "http://localhost:18789/health"]
interval: 30s
timeout: 10s
retries: 3
start_period: 5s
Managing with Docker Compose:
# Start OpenClaw
docker-compose up -d
# View logs
docker-compose logs -f
# Stop OpenClaw
docker-compose down
# Restart OpenClaw
docker-compose restart
# Update and rebuild
docker-compose build --no-cache
docker-compose up -d
CRITICAL SECURITY VULNERABILITY DISCLOSURE
OpenClaw has experienced significant security issues that users must be aware of before deploying the system. A high-severity security flaw identified as CVE-2026-25253 was disclosed that allows remote code execution through a crafted malicious link. This vulnerability has a CVSS score of 8.8, indicating high severity.
The vulnerability stems from a logic flaw categorized as CWE-669, which stands for Incorrect Resource Transfer Between Spheres, in how OpenClaw's Control UI handles the gatewayUrl query parameter. Prior to the fix, the application would automatically establish a WebSocket connection to a URL specified in the query string without user confirmation, sending the user's authentication token in the process.
This means an attacker can craft a malicious webpage or link that, when visited or clicked by a user, forces the OpenClaw application to connect to the attacker's server and transmit the user's authentication token. With the stolen token, the attacker can then gain full control over the AI agent. The attacker can modify configurations to disable security features. They can disable sandboxing and user confirmations for dangerous commands. They can execute arbitrary code on the host system with the user's privileges. They can read sensitive files and exfiltrate data. They can steal API keys and credentials. They can install persistent backdoors that survive system restarts.
Even users running OpenClaw locally are at risk, as the exploit uses the victim's browser to bypass local network protections and firewalls. The attack requires only that the victim click a link or visit a compromised webpage while OpenClaw is running. The vulnerability impacts confidentiality, integrity, and availability of the system.
This vulnerability was discovered by security researchers at DepthFirst in late January 2026 and was addressed in OpenClaw version 2026.1.29, released on January 30, 2026. However, many identified OpenClaw instances are still running older, vulnerable versions. Users are strongly advised to take immediate action.
Immediate Actions Required:
# Check your current OpenClaw version
openclaw --version
# Update to the latest version
npm update -g openclaw
# Or reinstall completely
npm uninstall -g openclaw
npm install -g openclaw@latest
# Verify the update
openclaw --version
# Rotate authentication tokens
# Generate a new token
openssl rand -hex 32
# Update your .env file with the new token
nano ~/.openclaw/.env
# Restart the gateway
openclaw gateway restart
# Run a security audit
openclaw security audit --deep
# Review logs for suspicious activity
openclaw logs --follow | grep -i "suspicious\|unauthorized\|failed"
You should update to OpenClaw version 2026.1.29 or later immediately. You should rotate all authentication tokens after updating to invalidate any potentially compromised credentials. You should review system logs for suspicious activity that might indicate exploitation. You should check for unauthorized configuration changes that an attacker might have made. You should audit file access patterns for data exfiltration attempts.
Additionally, security researchers have identified several other concerning issues with OpenClaw. Malicious skills represent a significant threat, as community-contributed skills can be weaponized to deliver malware such as infostealers, ransomware, or cryptocurrency miners. These malicious skills might instruct users to download and run binaries from external sources, or contain obfuscated scripts that execute malicious code. Prompt injection vulnerabilities mean that AI models are vulnerable to attacks where hidden instructions in content such as emails, web pages, or even code comments could cause the agent to execute malicious commands with full system access. This is particularly dangerous on platforms like MoltBook where malicious actors have been observed embedding hidden instructions in posts.
Plaintext credential storage is another concern, as by default OpenClaw stores API keys and tokens in plaintext within configuration files, creating exposure risk if the system is compromised. While environment variables provide some improvement, they are still stored in plaintext in the .env file. Insufficient sandboxing has been criticized, as the Skills framework lacks robust sandboxing, potentially allowing malicious skills to enable remote code execution and data exfiltration. The Tools permission system provides some boundaries, but is not a complete sandbox. Exposed API keys have also been an issue, as MoltBook itself has faced security problems including an API key being mistakenly exposed in public code, which could allow unauthorized access to the platform and potentially to connected OpenClaw agents.
MITIGATION STRATEGIES:
To minimize security risks when using OpenClaw, you should implement comprehensive mitigation strategies. Always run the latest version of OpenClaw with security patches applied. Check for updates regularly:
# Check for outdated packages
npm outdated -g
# Update OpenClaw
npm update -g openclaw
# Run security audit
openclaw security audit --deep
Treat all skill repositories as untrusted code and review thoroughly before installation. Never install skills from unknown sources. Only use skills you've personally reviewed and trust completely, or skills from well-known, reputable sources with a proven track record of security.
Run OpenClaw in a sandboxed or containerized environment using Docker or similar technologies to limit the blast radius of potential compromises. Use a dedicated virtual machine for complete isolation if working with highly sensitive code or data. Never run OpenClaw with root or administrator privileges. Always use a dedicated non-privileged user account.
Set file permissions to 600 for all configuration files:
chmod 600 ~/.openclaw/openclaw.json
chmod 600 ~/.openclaw/.env
chmod 700 ~/.openclaw
chmod 700 ~/.openclaw/credentials
Use environment variables for credentials and never hardcode them in configuration files or commit them to version control.
Be extremely cautious about executing downloaded binaries or scripts suggested by the AI agent. Always review code before execution to understand what it does. Monitor for unexpected network traffic or file access patterns using tools like tcpdump, Wireshark, or system audit logs. Implement network-level restrictions using firewalls to limit which external services OpenClaw can access.
Regularly rotate authentication tokens and API keys, especially after any security incident or suspicious activity. Disable the browser tool unless absolutely necessary, as it presents additional attack surface for prompt injection. Use the most restrictive Tools configuration possible for your use case, following the principle of least privilege.
Cybersecurity experts have warned against using OpenClaw on devices with sensitive data unless these security measures are strictly followed. The combination of broad system access, AI unpredictability, and demonstrated vulnerabilities creates a high-risk environment that requires careful management.
MONITORING AND COST MANAGEMENT
When using remote API providers, monitoring usage and managing costs is essential to avoid unexpected bills and ensure efficient resource utilization. Most providers offer usage dashboards and alerting capabilities that you should configure proactively.
Anthropic Claude:
Anthropic provides a comprehensive usage dashboard at https://console.anthropic.com where you can view your API usage, costs, and rate limits. You can set spending limits in account settings to prevent unexpected charges. The dashboard allows you to monitor token consumption by project, making it easy to identify which applications or use cases are consuming the most resources.
Current pricing for Claude models as of early 2026:
- Claude Sonnet 4.5: ~$3.00 per million input tokens, ~$15.00 per million output tokens
- Claude Haiku 4: ~$0.25 per million input tokens, ~$1.25 per million output tokens
OpenAI GPT:
OpenAI provides usage tracking at https://platform.openai.com/usage where you can view detailed breakdowns of API calls, tokens consumed, and costs incurred. You can set monthly budget limits to prevent overspending and receive email alerts when approaching limits. The platform allows tracking usage by API key, making it easy to attribute costs to specific projects or applications.
Current pricing for GPT models as of early 2026:
- GPT-4 Turbo: ~$10.00 per million input tokens, ~$30.00 per million output tokens
- GPT-3.5 Turbo: ~$0.50 per million input tokens, ~$1.50 per million output tokens
Cost Optimization Strategies:
Implement strategies to minimize costs while maintaining functionality:
- Use local models for routine tasks such as syntax checking, simple refactoring, and basic code reviews. These tasks don't require the advanced reasoning capabilities of expensive cloud models.
- Reserve expensive models like Claude Sonnet or GPT-4 for complex reasoning tasks such as architecture design, complex debugging, and sophisticated code generation where their superior capabilities justify the cost.
- Implement caching for frequently accessed code reviews or documentation lookups to avoid redundant API calls for the same content.
- Set reasonable maxTokens limits in your configuration to prevent runaway generation that could consume excessive tokens without providing value.
- Use lower-cost models like Claude Haiku or GPT-3.5 Turbo for simple queries such as quick questions, simple explanations, or straightforward code modifications.
- Monitor daily usage patterns and set alerts for unusual spikes that might indicate misconfiguration, bugs, or security issues.
- Implement request batching where possible to reduce the overhead of multiple API calls for related tasks.
- Use streaming responses only when necessary, as they can sometimes consume more tokens than non-streaming alternatives.
Example Configuration with Cost-Aware Routing:
{
"agents": {
"defaults": {
"model": {
"primary": "ollama/qwen3-coder-next",
"fallbacks": [
"anthropic/claude-haiku-4",
"anthropic/claude-sonnet-4-5"
]
},
"maxTokens": 4096
}
},
"models": {
"providers": {
"ollama": {
"baseUrl": "http://127.0.0.1:11434/v1",
"apiKey": "ollama-local",
"api": "openai-completions"
},
"anthropic": {
"apiKey": "${ANTHROPIC_API_KEY}",
"baseUrl": "https://api.anthropic.com"
}
},
"heartbeat": {
"model": "anthropic/claude-haiku-4"
}
},
"workspace": "~/.openclaw/workspace"
}
This configuration prioritizes the free local Qwen3-Coder-Next model for all requests, falling back to the economical Claude Haiku for tasks requiring more capability than the local model can provide, and only using the expensive Claude Sonnet when both the local model and Haiku are unavailable or insufficient. The maxTokens limit of 4096 prevents excessively long responses that could consume unnecessary tokens. The heartbeat section uses the cheaper Claude Haiku for simple health checks.
Monitoring Commands:
# View OpenClaw logs for API usage
openclaw logs --follow | grep -i "tokens\|cost\|api"
# Check gateway status
openclaw gateway status
# Run health check
openclaw doctor
# View configuration
openclaw config show
PRACTICAL WORKFLOW EXAMPLES
Let's walk through practical workflows for using your OpenClaw code assistant in real development scenarios.
Workflow 1: Code Review Before Commit
This workflow helps you catch issues before they enter your codebase.
Steps:
Make changes to your code in your editor or IDE as you normally would during development.
Request code review before committing:
Via Telegram: "Review the code in ~/projects/myapp/src/auth.js"OpenClaw analyzes the code using the code-reviewer skill, examining:
- Code quality and maintainability
- Security vulnerabilities
- Potential bugs
- Performance issues
- Testing considerations
Review the feedback provided by the assistant with specific line numbers and recommendations.
Make improvements based on the feedback to address identified issues.
Commit the refined code with confidence:
git add src/auth.js git commit -m "Implement user authentication with security improvements" git push
Workflow 2: Generating New Features
This workflow demonstrates using OpenClaw for agentic code generation.
Steps:
Describe the feature you want to implement:
"Create a REST API endpoint for user registration with email validation, password hashing using bcrypt, and duplicate user checking. Use Express.js and save it to ~/projects/api/routes/auth.js"OpenClaw generates the code including:
- Complete Express route handler
- Email validation logic
- Password hashing with bcrypt
- Duplicate user checking
- Proper error handling
- HTTP status codes
Review the generated code in the workspace or specified location.
Request tests for the new code:
"Generate comprehensive tests for ~/projects/api/routes/auth.js"Run the tests to verify functionality:
npm testIntegrate into your project after verification.
Workflow 3: Refactoring Legacy Code
This workflow shows how to modernize and improve existing code.
Steps:
Identify code that needs refactoring:
# Example: Large, complex function cat ~/projects/legacy/data-processor.jsRequest refactoring:
"Refactor ~/projects/legacy/data-processor.js to improve readability and extract reusable functions. Maintain backward compatibility."OpenClaw refactors the code by:
- Extracting logical sections into separate functions
- Improving variable and function names
- Adding documentation
- Reducing complexity
- Maintaining the public API
Review the refactored code with before/after comparison.
Run existing tests to ensure functionality is preserved:
npm testCommit the refactored code:
git add legacy/data-processor.js git commit -m "Refactor data processor for improved maintainability"
Workflow 4: Scaffolding New Projects
This workflow demonstrates using OpenClaw to generate entire project structures.
Steps:
Describe the project you want to create:
"Create a new FastAPI microservice for user authentication with JWT tokens, Docker support, and PostgreSQL database. Include tests and documentation."OpenClaw scaffolds the project including:
- Project directory structure
- Main application file with API routes
- Authentication middleware
- User model and database schema
- Password hashing utilities
- Configuration files
- Dockerfile and docker-compose.yml
- Test files
- README with setup instructions
Review the generated project in the workspace:
cd ~/.openclaw/workspace/auth-service ls -laSet up the project:
# Copy to your projects directory cp -r ~/.openclaw/workspace/auth-service ~/projects/ # Navigate to the project cd ~/projects/auth-service # Create virtual environment (Python) python3 -m venv venv source venv/bin/activate # Install dependencies pip install -r requirements.txt # Set up environment variables cp .env.example .env nano .envRun the project:
# Start with Docker docker-compose up -d # Or run directly uvicorn main:app --reloadTest the endpoints:
# Run tests pytest # Test API manually curl -X POST http://localhost:8000/api/register \ -H "Content-Type: application/json" \ -d '{"email": "user@example.com", "password": "securepass123"}'
Workflow 5: Debugging Assistance
This workflow shows how to use OpenClaw for debugging complex issues.
Steps:
Encounter a bug during testing or development.
Describe the problem to OpenClaw:
"I'm getting a 'TypeError: Cannot read property 'id' of undefined' error in ~/projects/app/src/user-service.js at line 45. The error occurs when trying to update a user profile. Can you help debug this?"OpenClaw analyzes the code and suggests potential causes:
- Null pointer issues
- Missing error handling
- Incorrect API calls
- Race conditions
Request specific fixes:
"Add null checking and proper error handling to prevent this error"OpenClaw generates the fix with:
- Null/undefined checks
- Proper error handling
- Defensive programming
- Logging for debugging
Apply the fix and test:
# Run tests npm test # Test the specific functionality node test-user-update.jsVerify the bug is resolved and commit the fix.
Workflow 6: Multi-File Feature Implementation
This workflow demonstrates OpenClaw's agentic capabilities for complex, multi-file changes.
Steps:
Describe a complex feature requiring multiple files:
"Implement a complete user authentication system with: - User registration endpoint - Login endpoint with JWT - Password reset functionality - Email verification - User profile management Use Express.js, PostgreSQL, and save to ~/projects/api/"OpenClaw plans the implementation:
- Identifies all necessary files
- Designs the database schema
- Plans the API endpoints
- Determines dependencies
OpenClaw generates all files:
routes/auth.js- Authentication routesroutes/users.js- User management routesmodels/User.js- User database modelmiddleware/auth.js- JWT authentication middlewareutils/email.js- Email sending utilitiesutils/crypto.js- Password hashing utilitiesconfig/database.js- Database configurationmigrations/001_create_users.sql- Database migrationtests/auth.test.js- Authentication teststests/users.test.js- User management tests
Review the generated files in the workspace.
Request documentation:
"Generate API documentation for the authentication endpoints"Set up and test the complete feature:
# Run database migrations npm run migrate # Run tests npm test # Start the server npm start # Test the endpoints curl -X POST http://localhost:3000/api/register \ -H "Content-Type: application/json" \ -d '{"email": "user@example.com", "password": "securepass123"}'
CONCLUSION AND BEST PRACTICES
Building a code assistant with OpenClaw provides a powerful, privacy-respecting alternative to cloud-based AI coding tools. However, success requires careful attention to configuration, security, and workflow integration. OpenClaw gives you complete control over your AI assistant, but with that control comes responsibility for security and proper configuration.
Security Must Be Your Absolute Top Priority:
The platform has significant system access and has experienced serious security vulnerabilities including CVE-2026-25253, which allows remote code execution through malicious links. Always run the latest version with security patches applied to protect against known vulnerabilities. Use containerization or virtual machines for isolation to limit the damage if the agent is compromised. Restrict permissions using the Tools configuration to implement the principle of least privilege. Carefully vet all skills before installation and never install skills from untrusted sources, as malicious skills can be used as malware vectors.
Balance Privacy, Cost, and Capability:
Start with local Ollama models for privacy-sensitive work and routine tasks that don't require advanced reasoning capabilities. Use remote APIs like Claude or GPT-4 for complex reasoning tasks where their superior capabilities justify the cost. This hybrid approach balances privacy, cost, and capability, giving you the best of both worlds.
Leverage the Skills System:
The AgentSkills standard makes OpenClaw highly extensible. Create custom SKILL.md files tailored to your specific tech stack, coding standards, and workflows for maximum value. Well-designed skills can dramatically improve productivity by encoding your team's best practices and automating repetitive tasks.
Configure Proper Boundaries:
Use the Tools configuration to restrict file system access to only necessary directories, limit shell commands to safe operations using allowlists, and set appropriate timeouts to prevent runaway processes. Defense-in-depth through multiple security layers prevents breaches and limits damage.
Optimize for Your Hardware:
If running local models, properly configure GPU acceleration for your hardware platform. NVIDIA GPUs use CUDA, Apple Silicon uses Metal, and AMD GPUs use ROCm or Vulkan. Tune model parameters like num_gpu for your hardware capabilities to achieve optimal performance. Use code-specific models like Qwen3-Coder-Next or DeepSeek-Coder-V2 for better performance on programming tasks.
Monitor and Manage Costs:
Track API usage through provider dashboards, set spending limits to prevent unexpected bills, and implement cost-aware routing strategies that prioritize cheaper models for routine tasks. Unexpected spikes in usage could indicate misconfiguration, bugs, or security issues.
Maintain Secure Credentials:
Never store API keys directly in configuration files. Always use environment variables in your .env file and reference them with the variable syntax. Set file permissions to 600 for all sensitive files to prevent unauthorized access.
Conduct Regular Security Audits:
# Run comprehensive security audit
openclaw security audit --deep
# Check for updates
npm outdated -g
# Update OpenClaw
npm update -g openclaw
# Review logs for suspicious activity
openclaw logs --follow | grep -i "suspicious\|unauthorized\|failed"
Stay informed about security advisories through the OpenClaw GitHub repository and community channels. Update promptly when security patches are released.
Important Limitations:
OpenClaw is a powerful but potentially dangerous tool that requires careful management. It executes with significant system privileges and has access to your code, files, and potentially sensitive data. The security vulnerabilities disclosed, including the high-severity CVE-2026-25253 remote code execution flaw, demonstrate real and serious risks that have been exploited in the wild. This is not a tool you can deploy once and forget about - it requires ongoing vigilance and security-conscious operation.
The Skills system, while powerful and flexible, lacks robust sandboxing. Malicious skills can execute arbitrary code with your user privileges, access sensitive files outside the workspace, and exfiltrate data to remote servers. Only install skills you've personally reviewed and trust completely.
Prompt injection attacks are a real threat, especially when the AI agent interacts with external content. Hidden instructions in seemingly benign content can manipulate the agent into performing unintended actions. Be cautious about which external sources your agent accesses.
Getting Started Safely:
Follow these steps to get started with OpenClaw safely:
# 1. Install Node.js 22+
nvm install 22
nvm use 22
# 2. Install Ollama (for local models)
# Visit https://ollama.ai for installation instructions
# 3. Install OpenClaw
curl -fsSL https://openclaw.ai/install.sh | bash
# or
npm install -g openclaw@latest
# 4. Run onboarding wizard
openclaw onboard
# 5. Set up environment file
touch ~/.openclaw/.env
chmod 600 ~/.openclaw/.env
nano ~/.openclaw/.env
# 6. Set file permissions
chmod 700 ~/.openclaw
chmod 600 ~/.openclaw/openclaw.json
# 7. Run security audit
openclaw security audit --deep
# 8. Start the gateway
openclaw gateway start
# 9. Test with simple queries
# Via Telegram or Control UI: "What can you help me with?"
The flexibility of OpenClaw's architecture means there's no single correct configuration. Experiment with different models, create skills that encode your team's workflows, and iterate on routing strategies. Start conservatively with restrictive permissions and gradually expand access as you gain confidence.
As the OpenClaw ecosystem continues to evolve, new models, skills, and integration possibilities will emerge. Stay engaged with the community, contribute your own skills when appropriate, and maintain a security-conscious approach to incorporating new capabilities.
With proper configuration, thoughtful skill development, and vigilant security practices, OpenClaw can become a valuable member of your development team, handling routine tasks, providing expert guidance, and helping you maintain high-quality software while preserving complete control over your code and data.
