Hello World: Build Your First OpenClaw Agent

1. Introduction

Artificial‑intelligence agents are becoming the backbone of modern SaaS products, from automated customer support to dynamic content generation. OpenClaw simplifies the heavy lifting by providing a modular architecture that separates memory, gateway, and agent logic. Whether you are a solo developer or part of a growing startup, mastering this framework gives you a reusable foundation for any AI‑driven feature.

For a broader view of how AI platforms are shaping businesses, explore the UBOS platform overview, which highlights complementary services you might integrate later.

2. Prerequisites

Before diving into code, ensure you have the following:

• Node.js ≥ 18.x (LTS recommended)
• Git client for cloning repositories
• Python 3.10+ (optional, for advanced memory adapters)
• A OpenAI API key (or any compatible LLM endpoint)
• Basic familiarity with JavaScript/TypeScript

If you are budgeting your project, take a quick look at the UBOS pricing plans to gauge potential cloud costs for scaling your agents.

3. Installing OpenClaw

OpenClaw can be installed directly from its GitHub repository. Follow these steps:

# Clone the repository
git clone https://github.com/openclaw/openclaw.git
cd openclaw

# Install dependencies
npm ci

# Verify the installation
npm run test:unit   # should pass all unit tests

For the most up‑to‑date instructions, refer to the OpenClaw official repository. The command npm run test:unit confirms that the core modules—including memory and gateway—are correctly wired.

4. Creating a Hello World agent

Now we’ll build the simplest possible agent that replies with “Hello, World!” whenever it receives a user message.

4.1 Project scaffold

Create a new folder for your agent and initialize a Node project:

mkdir hello-world-agent
cd hello-world-agent
npm init -y
npm i openclaw

4.2 Define the agent logic

Create a file named agent.js with the following content:

const { Agent, Memory, Gateway } = require('openclaw');

// Simple in‑memory store (no persistence needed for Hello World)
const memory = new Memory({
  // No configuration required for the default volatile store
});

// Gateway that forwards messages to the LLM (here we use a mock)
const gateway = new Gateway({
  // In a real scenario you would provide an LLM endpoint.
  // For this tutorial we use a dummy function.
  async call(prompt) {
    // Echo back a static response
    return 'Hello, World!';
  },
});

// Agent definition
class HelloWorldAgent extends Agent {
  constructor() {
    super({ memory, gateway });
  }

  // Core method invoked for each incoming message
  async handleMessage(userMessage) {
    // Store the user message in memory (optional for this demo)
    await this.memory.save({ role: 'user', content: userMessage });

    // Ask the gateway (LLM) for a response
    const reply = await this.gateway.call(userMessage);

    // Save the reply to memory
    await this.memory.save({ role: 'assistant', content: reply });

    return reply;
  }
}

// Export a ready‑to‑use instance
module.exports = new HelloWorldAgent();

4.3 Run the agent

Create a tiny driver script run.js to interact with the agent from the command line:

const helloAgent = require('./agent');
const readline = require('readline');

const rl = readline.createInterface({
  input: process.stdin,
  output: process.stdout,
});

rl.question('You: ', async (input) => {
  const response = await helloAgent.handleMessage(input);
  console.log('Agent:', response);
  rl.close();
});

Execute the script:

node run.js
You: How are you?
Agent: Hello, World!

This minimal example demonstrates the three core pillars of OpenClaw: memory (where conversational context lives), gateway (the bridge to an LLM), and the agent framework (orchestrating the flow).

For developers who love rapid prototyping, the UBOS templates for quick start provide similar scaffolding for web‑based AI tools.

5. Understanding memory, gateway, and framework interactions

OpenClaw’s architecture is deliberately MECE (Mutually Exclusive, Collectively Exhaustive). Each component has a single responsibility, making the system both testable and extensible.

5.1 Memory layer

The Memory class abstracts storage. Out‑of‑the‑box, it offers:

• Volatile in‑memory store (ideal for demos)
• Redis‑backed persistence for production workloads
• Vector‑store adapters (e.g., Chroma DB) for semantic retrieval

When an agent receives a message, it first logs the interaction to memory. This enables:

1. Contextual continuity across turns
2. Audit trails for compliance
3. Fine‑grained prompt engineering based on conversation history

5.2 Gateway layer

The Gateway is the only piece that talks to an external LLM. It receives a prompt (often a concatenation of recent memory entries) and returns a raw response. Because the gateway is a thin wrapper, you can swap providers without touching the agent logic:

• OpenAI’s gpt‑4o
• Anthropic’s Claude models
• Self‑hosted LLMs via vLLM or Ollama

In the Hello World example we used a mock gateway that always returns a static string. In real projects, you would configure the gateway with an API key and optional system prompts.

5.3 Agent framework

The Agent class glues memory and gateway together. Its responsibilities include:

• Fetching relevant memory chunks (e.g., last 5 messages)
• Formatting the prompt according to a template
• Invoking the gateway and handling errors
• Persisting the LLM’s answer back to memory

Because the framework is opinionated yet extensible, you can inherit from Agent and override methods such as preprocess() or postprocess(). This is the pattern used by advanced AI marketing agents, which enrich prompts with product catalogs and campaign KPIs before calling the LLM.

6. Testing the agent

Robust testing ensures that memory updates, gateway calls, and response handling work as expected. OpenClaw ships with a Jest‑based test harness.

6.1 Unit test example

Create agent.test.js:

const HelloWorldAgent = require('./agent');

test('agent returns Hello, World! and stores interaction', async () => {
  const reply = await HelloWorldAgent.handleMessage('Test message');
  expect(reply).toBe('Hello, World!');

  const history = await HelloWorldAgent.memory.getAll();
  expect(history).toEqual([
    { role: 'user', content: 'Test message' },
    { role: 'assistant', content: 'Hello, World!' },
  ]);
});

Run the test suite:

npm run test:unit
PASS  ./agent.test.js
  ✓ agent returns Hello, World! and stores interaction (45 ms)

6.2 Integration testing with UI

If you prefer a visual playground, spin up a quick web UI using the Workflow automation studio. Connect the agent as a backend service, then send messages through a simple chat widget. This approach validates end‑to‑end latency and helps you fine‑tune the gateway’s temperature settings.

7. Conclusion

By following this step‑by‑step guide you now have a functional OpenClaw “Hello, World” agent and a clear mental model of how memory, gateway, and the agent framework collaborate. The modular design encourages you to replace any component—swap a volatile memory for a vector store, upgrade the gateway to a more powerful LLM, or extend the agent class with domain‑specific logic.

Next steps for ambitious developers include:

• Integrating UBOS for startups to provision scalable cloud resources.
• Exploring the Enterprise AI platform by UBOS for multi‑tenant deployments.
• Adding vector‑based retrieval with the Chroma DB integration for semantic memory.
• Embedding voice capabilities via the ElevenLabs AI voice integration to turn your agent into a conversational assistant.

Remember, the power of OpenClaw lies in its composability. As you iterate, keep your memory, gateway, and agent logic cleanly separated—this will pay dividends when you scale from a single “Hello, World” demo to a production‑grade AI service.