OpenClaw setup: install, configure the Gateway, add a model

OpenClaw is an open-source Gateway for AI agents. You run it on your own computer or server, and it connects chat apps (Telegram, WhatsApp, Slack) to a model and a set of tools. One command installs it, and the file ~/.openclaw/openclaw.json configures it. Below: installation, connecting a model through codexkey, the security risks and a comparison with Hermes Agent.

What OpenClaw is and what it is for

The OpenClaw documentation calls the project a self-hosted gateway between your chats and AI agents. The Gateway is a single process: it holds sessions, routing and channel connections. The channel list is long: Discord, Google Chat, iMessage, Matrix, Microsoft Teams, Signal, Slack, Telegram, WhatsApp, Zalo and web chat. The browser control panel is the easiest place to configure it, and by default it opens at http://127.0.0.1:18789/.

The code lives in the openclaw/openclaw repository under the MIT license, and the project has about 393 thousand stars. OpenClaw Foundation, an independent non-profit, maintains it. OpenClaw has no model of its own: it needs a provider key or a login to an already installed Claude Code or Codex CLI. A codexkey key works as the provider.

How to install OpenClaw on macOS, Linux and Windows

The installer detects your system, installs Node if needed, then installs OpenClaw and starts the setup wizard.

Node requirements: 24.16.0 or newer in the 24.x line, or 26.1.0 and above, with Node 26 recommended. Security fixes landed in 24.22.1 and 26.12.1, so take those. Remember that curl | bash runs someone else's script. If that bothers you, download the file, read it and run it yourself, or install through npm.

What to do after installing

The openclaw onboard wizard offers two modes. Quick start finds the AI access you already have, tests it with a real request, saves the config and opens the panel. Custom setup walks you through every option step by step. In Quick start the Gateway runs in the terminal window until you press Ctrl+C. To keep it running in the background, run:

openclaw gateway install
openclaw gateway status
openclaw dashboard

The first command installs a service: a LaunchAgent on macOS, a user systemd unit on Linux and WSL2, a scheduled task on Windows. The second shows that the Gateway is listening on port 18789. The third opens the panel, where you can write your first message. If something goes wrong, openclaw doctor lists what it found, and openclaw triage runs read-only checks. On Windows the documentation treats the Windows Hub app as the easiest route, though the PowerShell installer and a Gateway inside WSL2 are supported too.

How to connect a model to OpenClaw through codexkey

codexkey offers an OpenAI-compatible address, https://api.codexkey.online/v1, and one sk_cdx_... key for every model. You can pay with a Russian-issued card, through SBP (the Russian Faster Payments System) or with crypto. No vendor account and no VPN are needed. The config from the codexkey guide goes into ~/.openclaw/openclaw.json:

{
  "models": {
    "mode": "merge",
    "providers": {
      "codexkey": {
        "baseUrl": "https://api.codexkey.online/v1",
        "apiKey": "sk_cdx_YOUR_KEY",
        "api": "openai-completions",
        "models": [
          { "id": "gpt-6-astra", "name": "GPT-6 Astra", "contextWindow": 1000000, "maxTokens": 128000 },
          { "id": "claude-sonnet-5", "name": "Claude Sonnet 5", "contextWindow": 1000000, "maxTokens": 32000 }
        ]
      }
    }
  },
  "agents": { "defaults": { "model": { "primary": "codexkey/gpt-6-astra" } } }
}

After that, restart the service and check the config:

openclaw gateway restart
openclaw doctor

How to read the fields. baseUrl and apiKey set the address and the key. api picks the protocol: openai-completions for OpenAI-compatible servers, and per the OpenClaw documentation there is also anthropic-messages. In models, each model is described by an ID, a name, a context size and an output limit. In primary, a model is written as provider, slash, ID.

Three details. The config is JSON5, so comments are allowed. The Gateway accepts only a file that matches the schema exactly: a stray key or a typo stops startup, and openclaw doctor shows the cause. The key does not have to sit in the file, since OpenClaw can substitute an environment variable, for example "apiKey": "${CODEXKEY_API_KEY}".

Prices come from the codexkey price list as of 29 October 2026; check the models page for current ones. An agent pushes a long context through the model many times per session, and the bill climbs fast: there is a separate article on AI agent bills. Keep a small balance while you test. A quick start with a key is described in the documentation.

OpenClaw security: what is at risk when an agent has system access

An agent with access to files and commands can wreck your working data through its own mistake or on someone else's prompt. What follows is only what the documentation itself confirms.

• One Gateway is built for one trust boundary. According to the security guide, OpenClaw does not protect against hostile users on a shared agent. If the audience is mixed, run separate Gateways and keys, and preferably separate OS users or hosts.
• On a regular install the Gateway listens on loopback only. Most channels answer unknown senders in direct messages with a pairing code. Container images are the exception: they are open to the outside by default and need authentication added.
• Tools in the main session run on your host until you set up a sandbox. Treat incoming messages as untrusted.
• The openclaw security audit command looks for configuration drift, and it can fix some of the findings itself.

The skills in the ClawHub catalog are a separate story. Koi Security researchers checked 2857 skills and found 341 malicious ones, 335 of them from a single campaign, ClawHavoc (news from 2 February 2026). A skill asked you to run commands in a "Prerequisites" section, and on macOS that installed the Atomic Stealer malware. The practical lesson: install skills only after reading their files, and run the agent on a separate machine, in a virtual machine or under a separate user, where your keys and work documents are not present. What should never go to a model at all is listed in the article on what not to send to a language model.

OpenClaw and Ollama: local models

For local models OpenClaw talks to Ollama's native API, not the OpenAI-compatible one. So baseUrl takes the server root, for example http://host:11434, without /v1: the documentation warns outright that an address with /v1 breaks tool calling. There is also an Ollama Cloud option through the ollama-cloud provider. How much your hardware can handle, and how reliably a local model calls tools, depends on the model, so test on your own tasks. To compare against an API, keep a codexkey key and the same agent at hand: switching takes one primary line.

OpenClaw or Hermes Agent: which to pick

Nous Research makes Hermes Agent. The comparison page sits in OpenClaw's own documentation, so it is hardly neutral, and it is a snapshot from August 2026. This is what it says:

Source: the comparison in the OpenClaw documentation. The choice depends on how you want to restrict the agent and where it should run. We would run both on one small task with a separate key and compare behavior and spend. codexkey has a ready config for Hermes as well, ~/.hermes/config.yaml:

model:
  provider: custom
  default: gpt-6-astra
  context_length: 1000000
  base_url: https://api.codexkey.online/v1
  api_mode: chat_completions
  api_key: sk_cdx_YOUR_KEY

For Claude models, set api_mode: anthropic_messages and put a Claude model in default. The context_length parameter is required: without it Hermes assumes a 128K model context. If you want an agent for code in the terminal rather than for chats, look at OpenCode, and the choice between gateways is covered in the guide to AI model aggregators with one API key.

FAQ

What is OpenClaw?

An open-source Gateway under the MIT license that you run yourself. It connects chats (Telegram, WhatsApp, Slack and others) to an AI agent. OpenClaw has no model inside, so it needs a provider key or a login to Claude Code or Codex CLI.

How do I install OpenClaw on Windows?

The documentation recommends the Windows Hub app. Fallbacks are the PowerShell installer iwr -useb https://openclaw.ai/install.ps1 | iex or a Gateway in WSL2. After installing, run openclaw gateway install and openclaw gateway status.

How do I connect a model to OpenClaw?

Add a provider to the models.providers block of ~/.openclaw/openclaw.json: an address, a key, a protocol and a list of models. Then set agents.defaults.model.primary as provider/model. The ready codexkey config is above; after editing, run openclaw gateway restart.

What is the OpenClaw Gateway and how do I restart it?

The Gateway is a single process that handles sessions, routing and chat connections. openclaw gateway status shows its state, openclaw gateway restart restarts it, openclaw doctor runs diagnostics and openclaw dashboard opens the panel.

Is OpenClaw safe?

That depends on the setup. By default the Gateway listens on loopback only, and unknown senders get a pairing code. Risk grows if you expose the Gateway to the outside, turn pairing off or install other people's skills without reading them. Run the agent away from your working data, and openclaw security audit will flag configuration drift.

OpenClaw or Hermes Agent: which should I pick?

Hermes Agent from Nous Research is a platform with a CLI, a messenger gateway and plugins. OpenClaw is a Gateway for chats and agents with a documented trust model. Try both on one task: agent behavior and token spend will decide, not the names.

Does OpenClaw work with Ollama?

Yes, through Ollama's native API. Give baseUrl the server root without /v1, for example http://host:11434, or tool calling breaks.