Getting Started with OpenClaw and Local Agents on Ubuntu

Step 1: Understand what OpenClaw adds

A language model produces answers; an agent runtime connects a model to sessions, tools and a work environment. OpenClaw adds a Gateway, a Control UI and agent configuration so you can keep that environment running between individual requests. Start with one agent and one test workspace before arranging a team.

Local agent can mean a runtime on your workstation while its model is remote. A fully local setup also needs local inference and local supporting services. Keep that distinction explicit when choosing a provider. This guide starts with Linux, a browser and no external messaging channel.

Step 2: Check the runtime and install

Check node --version against the current OpenClaw requirements before installing. The official getting-started page checked on October 9, 2026 lists Node.js 24.16+ or 26.1+ and recommends Node 26. Recheck that page when you follow this guide: runtime requirements change.

Download and review the official installer, then run it. The current installer starts onboarding. Choose Custom setup when you want to deliberately select a local provider instead of reusing a detected cloud login. You can return with openclaw configure. See the official getting-started guide.

Open the complete copyable example — example-01.txt

# Open full code above.

Step 3: Connect a local Ollama provider

Install Ollama and verify a direct answer first using the previous guide. In OpenClaw’s provider setup choose Ollama and its Local only route. Use http://127.0.0.1:11434 as the native base URL on the same machine; do not append /v1. OpenClaw’s Ollama integration uses the native chat API.

Select a downloaded model that the current provider discovery lists with the capabilities you need. A 3B text model is useful for learning about context, but a plain chat response does not qualify it for tool calls or long agent work. First check a short question, then one harmless tool call and its result. If a model prints tool JSON as text, investigate provider configuration and model capability rather than treating that text as successful execution.

Use the current Ollama provider overview and setup reference for your version. Keep the daemon and Gateway on loopback for this single-machine lab. Local-only selection should not silently fall back to a cloud model.

Step 4: Run the Gateway and open the dashboard

If onboarding left a foreground Gateway running, stop that foreground process with Ctrl+C before installing the background service. Then run the commands below and open the dashboard. The standard local Gateway port is 18789, but use the actual status output if you configured another one.

Send a simple question in the Control UI. Verify the selected agent and model, the response and the absence of unintended tools. A running service proves availability; one real completion proves that the provider route works for that request.

Open the complete copyable example — example-02.txt

openclaw gateway install
openclaw gateway status
openclaw dashboard

Step 5: Give one agent a clear workspace

Use openclaw agents add lab-helper to enter the agent setup wizard, then list the configured agents. Give this agent a dedicated workspace. Inspect the generated files before editing; use AGENTS.md for operating rules and SOUL.md for tone and role where your workspace supports them.

A useful first brief is: ‘Summarize notes from this workspace. Read only the notes folder. Do not send messages, install packages or change files. State which file supports each answer.’ Apply matching read-only tool and sandbox settings; prose rules alone are not an access-control boundary.

Keep task results in the workspace and secrets in the supported credential store. Separate agents should have their own workspace/session configuration rather than share a single mutable conversation. See agent CLI commands and multi-agent routing.

Open the complete copyable example — example-03.txt

# Open full code above.

Step 6: Verify a task before adding autonomy

Place a short public test note in the workspace and ask the selected agent to summarize it with its filename. Check that it actually used a file-reading tool, then compare the answer with the file. Next ask for a missing fact and expect an explicit unknown. Finally check that a write request is blocked under your configured policy.

Only after those checks should you add a bounded action such as creating a draft in a scratch folder. Give it an expected output, a maximum run duration and a review step. Persistent context, memory search and model training are different mechanisms; verify memory retrieval before claiming the agent remembers prior work.

Troubleshooting begins with openclaw gateway status and the current diagnostic commands in the docs. Provider failure, tool denial and a missing channel binding are separate problems. Read the actual error and inspect one layer at a time. Do not expose an unauthenticated Gateway to the internet to fix a local connection issue.

For Japanese reading, follow the marked sentence ‘The agent reads the file.’ When you need explicit branching, retries and approval gates across tasks, continue with the LangGraph guide.

Continue the series

• A DIY Violoop Alternative: GL-RM10 + Codex Automation, Step by Step
• Ollama on Ubuntu: Run a Small Model and Add Context Knowledge
• Getting Started with Codex on Ubuntu for Linux Work and Automation
• LangGraph for Practical Workflows: State, Approval and Recovery