Getting Started with OpenClaw: A Complete Beginner's Guide

What Is OpenClaw?

OpenClaw is an open-source AI agent framework designed for messaging platforms. It lets you create intelligent assistants — called agents — and deploy them across Telegram, Discord, Slack, WhatsApp, and other channels. Unlike chatbot builders that lock you into a single platform, OpenClaw is platform-agnostic: one agent can operate across multiple channels simultaneously, and you control the entire stack from a single configuration file.

At its core, OpenClaw is a runtime engine. You write a configuration file that declares which agents exist, which channels they connect to, which AI models power them, and which skills they can use. OpenClaw reads that file, boots up the agents, connects to the messaging platforms, and starts handling conversations. There is no GUI baked in — it is a server-side process that runs on a VPS, a Raspberry Pi, or any machine with Node.js.

The project has gained traction because of its modularity. A vibrant ecosystem of community-built skills — over 5,700 at the time of writing — extends agent capabilities far beyond simple Q&A. Skills can send emails, search the web, interact with GitHub, browse websites, execute code, manage calendars, and much more. If you can imagine a task that an AI assistant should perform, there is likely already a skill for it on ClawHub.

Core Concepts

Before you touch any configuration, it helps to understand the five building blocks that make up every OpenClaw deployment. These concepts map directly to the top-level keys in your configuration file, so learning them now will make everything else click.

Agents

An agent is the AI personality that handles conversations. Each agent has a name, a system prompt that defines its behavior, a model that powers its intelligence, and a list of skills it can use. You might have a “Support Agent” that answers customer questions, a “DevOps Agent” that monitors your infrastructure, and a “Personal Assistant” that manages your schedule — all running under the same OpenClaw instance. Agents are isolated by default: each one maintains its own conversation history and context window.

Channels

A channel is a connection to a messaging platform. OpenClaw supports Telegram, Discord, Slack, and WhatsApp out of the box, with community adapters for platforms like Microsoft Teams and IRC. Each channel entry in your configuration specifies the platform type, authentication credentials (like a bot token), and which agent should respond on that channel. A single agent can be attached to multiple channels, or you can assign different agents to different channels.

Skills

Skills are plugins that extend what an agent can do. Without skills, an agent can only generate text responses based on its model. With skills, it gains the ability to take actions: send an email, create a GitHub issue, look up the weather, query a database, or run a shell command. Skills are published to ClawHub and installed using the clawhub CLI. Each skill exposes one or more tools that the agent can invoke during a conversation. You decide which skills each agent has access to, giving you fine-grained control over capabilities.

Models

Models define the AI backends that power your agents. OpenClaw supports Anthropic Claude, OpenAI GPT, Google Gemini, Mistral, local models via Ollama, and any OpenAI-compatible API endpoint. Each model entry specifies the provider, the model name (like claude-sonnet-4-20250514), and the API key. You can define multiple models and assign different models to different agents — for example, a lightweight model for simple FAQ responses and a more capable model for complex reasoning tasks.

Tools

Tools are built-in utilities that ship with OpenClaw itself, separate from community skills. The most common tools are exec (run shell commands), filesystem (read and write files), and http (make HTTP requests). Tools are powerful but require caution — an agent with the exec tool can run arbitrary commands on your server. Always apply the principle of least privilege: only grant tools that an agent genuinely needs.

The Configuration File: openclaw.json

Everything in OpenClaw is driven by a single configuration file called openclaw.json. Despite the .json extension, the file actually uses JSON5 format, which means you can include comments, use trailing commas, and write unquoted keys. This is a deliberate design choice: real-world configs get complex quickly, and comments are essential for maintainability.

The default location for this file is ~/.openclaw/openclaw.json. You can override this with the --config flag when starting OpenClaw. The file has four top-level keys that correspond directly to the core concepts we just covered: channels, agents, skills, and models.

Here is a minimal configuration that sets up one Telegram channel, one agent, one model, and no skills:

{
  // Messaging platform connections
  channels: {
    telegram_main: {
      platform: "telegram",
      bot_token: "YOUR_TELEGRAM_BOT_TOKEN",
      agent: "assistant",
    },
  },

  // AI agent definitions
  agents: {
    assistant: {
      name: "My Assistant",
      model: "claude",
      system_prompt: "You are a helpful assistant.",
    },
  },

  // AI model configurations
  models: {
    claude: {
      provider: "anthropic",
      model: "claude-sonnet-4-20250514",
      api_key: "YOUR_ANTHROPIC_API_KEY",
    },
  },

  // Skills (plugins) — empty for now
  skills: {},
}

Notice the JSON5 features: unquoted keys, trailing commas, and inline comments. This file declares a Telegram channel called telegram_main that routes messages to an agent called assistant, which uses the Anthropic Claude model. This is the simplest possible OpenClaw setup, and it is enough to get a working bot running.

Setting Up Your First Agent

Let us walk through the process of getting your first OpenClaw agent running from scratch. We will use Telegram as the channel and Anthropic Claude as the model, but you can substitute any supported platform and provider.

Step 1: Install OpenClaw

OpenClaw is distributed as an npm package. You need Node.js 18 or higher installed on your machine. Open a terminal and run:

npm install -g openclaw

This installs the openclaw command globally. Verify the installation by running openclaw --version.

Step 2: Get Your API Keys

You need two credentials: an Anthropic API key and a Telegram bot token.

Anthropic API key: Sign up at console.anthropic.com, navigate to API Keys, and create a new key. Copy the key immediately — you will not be able to see it again.

Telegram bot token: Open Telegram and message @BotFather. Send /newbot, follow the prompts to give your bot a name and username, and BotFather will reply with a token. Save this token.

Step 3: Create Your Configuration

Create the OpenClaw config directory and file:

mkdir -p ~/.openclaw
nano ~/.openclaw/openclaw.json

Paste the minimal configuration from the previous section, replacing YOUR_TELEGRAM_BOT_TOKEN and YOUR_ANTHROPIC_API_KEY with your actual credentials. Customize the system_prompt to define your agent's personality and behavior. The system prompt is the most important part of your agent: it determines how your bot responds, what tone it uses, what it refuses to do, and how it handles edge cases.

Step 4: Run OpenClaw

Start the OpenClaw runtime:

openclaw start

OpenClaw will read your config, validate it, connect to Telegram, and start listening for messages. Open Telegram, find your bot, and send it a message. You should see a response powered by Claude within a few seconds. Congratulations — you have a working AI agent. Now let us make it more useful by adding skills.

Adding Skills

A bare agent can hold a conversation, but it cannot take actions in the real world. Skills change that. The OpenClaw ecosystem includes over 5,700 community-built skills on ClawHub, covering categories like communication, development, productivity, security, and automation. You can browse these skills on ClawHub directly, or use the ClawChart Skills Directory for a searchable, categorized view.

Installing Skills with the ClawHub CLI

Skills are installed using the clawhub CLI, which ships alongside OpenClaw. To install a skill, run:

clawhub install @anthropic/web-search
clawhub install @community/send-email
clawhub install @community/github

Each skill is downloaded and registered locally. After installing, you need to add the skill to your config file and assign it to an agent. Here is what your config might look like after adding the web search and email skills:

{
  skills: {
    web_search: {
      skill: "@anthropic/web-search",
      config: {
        max_results: 5,
      },
    },
    send_email: {
      skill: "@community/send-email",
      config: {
        smtp_host: "smtp.gmail.com",
        smtp_port: 587,
        smtp_user: "you@gmail.com",
        smtp_pass: "YOUR_APP_PASSWORD",
      },
    },
  },

  agents: {
    assistant: {
      name: "My Assistant",
      model: "claude",
      system_prompt: "You are a helpful assistant...",
      // Assign skills to this agent
      skills: ["web_search", "send_email"],
    },
  },
  // ... channels and models as before
}

Recommended Starter Skills

If you are just getting started, these skills provide the most value with the least configuration:

• •@anthropic/web-search — lets your agent search the web for up-to-date information
• •@community/send-email — send emails on behalf of users or as notifications
• •@community/github — create issues, open PRs, read repos, and manage GitHub workflows
• •@community/memory — gives your agent persistent memory across conversations
• •@community/calendar — manage Google Calendar events and reminders

Each skill may require its own API keys or configuration parameters. Check the skill's documentation on ClawHub for specific setup instructions.

Visualizing Your Configuration with ClawChart

As your configuration grows — more agents, more channels, more skills — the JSON file becomes harder to reason about. Which agent is connected to which channel? Which skills does each agent have access to? Are there any misconfigurations or security issues? This is where ClawChart comes in.

ClawChart is a free, browser-based tool that turns your openclaw.json into an interactive node graph. You paste your config (or upload the file), and ClawChart renders every channel, agent, skill, model, and tool as a visual node with connections showing how they relate. You can see at a glance which agent handles which channel, which model powers each agent, and which skills are assigned where.

How to Use ClawChart

1. 1.Paste your config: Go to clawchart.xyz and paste your openclaw.json into the editor panel on the left side. ClawChart parses the JSON5 in real time.
2. 2.Explore the graph: The right side shows an interactive node graph. Nodes are color-coded by type: channels are blue, agents are green, skills are purple, models are orange, and tools are yellow. Click any node to see its full configuration.
3. 3.Run a security audit: Click the Security Audit tab to scan your config for common vulnerabilities — exposed API keys, overly permissive tools, missing rate limits, and more. The audit runs entirely in your browser; your config is never sent to any server.
4. 4.Browse and add skills: Use the Skills Directory to discover new skills, filter by category, and add them to your config directly from the visual editor.

Visual editing is especially valuable when you are managing multi-agent setups. Instead of scrolling through hundreds of lines of JSON, you can see the entire architecture at once and spot misconfigurations instantly. For a deeper comparison between manual JSON editing and visual editing, see our guide on Visual Config Editing vs. JSON by Hand.

Deploying Your Agent

Running openclaw start on your local machine is great for development, but for a production agent that runs 24/7, you need to deploy it to a server. There are two main approaches.

Option A: Self-Hosting

If you prefer full control, you can deploy OpenClaw to any VPS provider (Hetzner, DigitalOcean, AWS, etc.). Here is what you need:

• •A VPS with at least 1 GB of RAM and a modern Linux distribution (Ubuntu 22.04 or higher recommended)
• •Docker (optional but recommended) for containerized deployments with easy updates and rollbacks
• •A process manager like PM2 or systemd to keep OpenClaw running after SSH disconnects and to auto-restart on crashes
• •A firewall configured to block all unnecessary ports and restrict SSH access
• •SSL/TLS if you are using webhooks (some platforms require HTTPS callback URLs)

Self-hosting gives you maximum flexibility but requires you to manage server security, updates, backups, and monitoring yourself. For a comprehensive checklist of security hardening steps, read our Security Hardening Guide.

Option B: ClawChart 1-Click Launch

If you want to skip the server administration entirely, ClawChart offers a 1-Click Launch feature. You build your configuration visually in ClawChart, choose a server tier, and ClawChart provisions a fully secured VPS, installs OpenClaw, deploys your config, and starts your agents — all within minutes. The server comes pre-configured with a firewall, fail2ban, automatic security updates, Docker isolation, and all eight security layers from our hardening guide.

1-Click Launch is ideal for users who want a production-ready deployment without the overhead of server management. You get a dedicated VPS (not shared hosting), full SSH access if you need it, and the ability to update your config through ClawChart at any time.

Next Steps

You now have a working OpenClaw agent running on Telegram. Here is where to go from here to unlock the full potential of the framework.

Multi-Agent Setups

OpenClaw shines when you run multiple agents with different specializations. You could have a customer support agent on your website chat, a DevOps agent in your Slack workspace, and a personal assistant on your WhatsApp — all managed from the same openclaw.json. Each agent has its own system prompt, model, and skill set, so they behave as distinct specialists while sharing the same infrastructure.

Adding More Channels

Expanding to a new platform is as simple as adding another channel entry to your config. If your agent is already performing well on Telegram, you can add a Discord channel that routes to the same agent. The agent's behavior, skills, and model stay the same — only the delivery platform changes. This is particularly useful for organizations that need to meet users where they already are.

Advanced Skills

Once you are comfortable with basic skills, explore more powerful ones. Browser automation skills let your agent navigate websites, fill forms, and extract data. Code execution skills let your agent write and run code in a sandboxed environment. Database skills let your agent query SQL and NoSQL databases directly. These advanced capabilities transform your agent from a conversational assistant into an autonomous worker.

Community Resources

The OpenClaw community is active and welcoming. Join the OpenClaw Discord server to ask questions, share configs, and discover new skills. Browse the GitHub repository for documentation, examples, and the source code. And use ClawHub to discover and publish skills. The ecosystem is growing rapidly, and contributions from users like you are what make OpenClaw better for everyone.

Start Building

OpenClaw makes it possible to build sophisticated AI agents without writing a single line of application code. You define your agents, channels, skills, and models in a configuration file, and the framework handles the rest — message routing, model inference, skill execution, and platform-specific formatting.

The fastest way to get started is to open ClawChart, paste a minimal config, and explore the visual graph. You will immediately see how the pieces fit together. From there, add skills, tweak your system prompt, run a security audit, and when you are ready, deploy with 1-Click Launch or to your own server. Your first agent is just a few minutes away.