# Getting Started with Claude Code + OpenClaw: The Complete Setup Guide

Canonical: https://clawdocx.com/blog/getting-started-claude-code-openclaw
Author: Theo Marsh
Published: 2026-03-16
Updated: 2026-09-19

> Learn how to connect Claude Code to OpenClaw using ACP: run coding sessions from chat, spawn thread-bound agents, and use voice mode, /loop, and hooks.

## Claude Code Meets OpenClaw

Claude Code has evolved rapidly in early 2026 — voice mode, 1 million token context, `/loop` for recurring tasks, hooks, sub-agents, and `/effort` controls. But the real unlock for OpenClaw users is **ACP integration**: the ability to run Claude Code as a managed coding agent directly from your chat channels.

Instead of context-switching to a terminal, you can tell your OpenClaw agent "start Claude Code on this repo" from Telegram, Discord, or Slack — and it spins up a supervised session with full tool access, thread binding, and automatic output delivery.

This guide walks you through everything: installing Claude Code, connecting it to OpenClaw via ACP, and using the major new features that shipped in March 2026.

---

## Prerequisites

Before you start, make sure you have:

- **OpenClaw running** on your machine (Mac, Linux, or WSL). If you haven't set this up yet, check out our [Getting Started with OpenClaw](/blog/getting-started-openclaw-free) guide first.
- **A Claude subscription** — Claude Code requires a Max, Team, or Enterprise plan, or an Anthropic Console API key.
- **Node.js 20+** installed (you already have this if OpenClaw is running).

> **Note**
>
> Claude Code also supports third-party providers (Bedrock, Vertex, Microsoft Foundry) if you prefer not to use a direct Anthropic account. See the official docs for provider-specific setup.

---

## Step 1: Install Claude Code

Claude Code installs as a standalone CLI. Pick your method:

### Native Install (Recommended)

```bash
# macOS, Linux, WSL
curl -fsSL https://claude.ai/install.sh | bash

# Windows PowerShell
irm https://claude.ai/install.ps1 | iex
```

Native installs auto-update in the background — you always get the latest features.

### Homebrew (macOS)

```bash
brew install --cask claude-code
```

### Verify Installation

```bash
claude --version
```

You should see version **2.1.76** or later (March 2026). On first run, Claude Code will prompt you to log in via your browser.

---

## Step 2: Connect Claude Code to OpenClaw via ACP

ACP (Agent Client Protocol) is how OpenClaw runs external coding tools as supervised child processes. Instead of OpenClaw trying to do everything inline, it delegates coding work to Claude Code as a proper harness — with its own context window, tool permissions, and session lifecycle.

### Enable ACP in OpenClaw

OpenClaw keeps its configuration in one JSON5 file, `~/.openclaw/openclaw.json`, by default, and `$include` can split it across several. Make sure ACP is enabled there:

```json5
// ~/.openclaw/openclaw.json
{
  acp: {
    enabled: true,
  },
}
```

### Register Claude Code as an ACP Agent

OpenClaw needs to know about Claude Code as an available harness. The acpx backend's built-in alias for Claude Code is `claude`, so that is the id the ACP allowlist takes:

```json5
// ~/.openclaw/openclaw.json
{
  acp: {
    enabled: true,
    backend: "acpx",
    allowedAgents: ["claude"],
  },
}
```

`backend: "acpx"` needs the runtime plugin on the Gateway host first. The ACP agents quickstart answers "Does this work out of the box?" with "Yes, after installing the official ACP runtime plugin", and gives two commands for it:

```bash
openclaw plugins install @openclaw/acpx
openclaw config set plugins.entries.acpx.enabled true
```

> **Tip**
>
> If you want Claude Code as your default coding agent, set `acp.defaultAgent` to `claude`, and you can then just say "run this in code" without naming the harness. `defaultAgent` is the fallback ACP target agent id when a spawn does not specify one.

### Test the Bridge

The readiness check runs from chat, and the ACP agents quickstart gives one command for it: "Run `/acp doctor` for a readiness check."

```text
/acp doctor
```

It tells you whether an ACP backend is loaded, enabled and healthy, which the quickstart asks you to confirm before blaming OpenClaw for a failed spawn. The similarly named `openclaw acp client` is a different tool: that one drives OpenClaw's own ACP bridge for IDEs, described on the CLI page as a way to "sanity-check the bridge without an IDE", and it does not exercise the acpx harness that runs Claude Code.

---

## Step 3: Run Your First Session from Chat

Now for the fun part. From any connected messaging channel (Telegram, Discord, Slack), you can ask your OpenClaw agent to spin up Claude Code:

**Natural language:**
> "Start Claude Code on my project and add error handling to the API routes"

**Slash command:**
> `/acp spawn claude --mode persistent --thread auto`

### What Happens Under the Hood

1. OpenClaw picks `runtime: "acp"` and resolves `claude` as the harness.
2. A new ACP session starts with Claude Code running against your project directory.
3. If you're on Discord or a thread-capable channel, the session binds to a thread — all follow-ups route to the same Claude Code instance.
4. Claude Code's output (file changes, command results, summaries) gets delivered back to your chat.

### One-Shot vs Persistent Sessions

| Mode | Use Case | Command |
|------|----------|---------|
| **One-shot** | Quick fix, single task, fire-and-forget | `/acp spawn claude --mode oneshot --thread off` |
| **Persistent** | Ongoing work, follow-up conversations | `/acp spawn claude --mode persistent --thread auto` |

Persistent sessions stay alive until you close them (`/acp close`) or they hit the idle timeout.

---

## Step 4: Key March 2026 Features You Should Know

### Voice Mode — Talk to Code

Claude Code now supports push-to-talk voice input via the `/voice` command. Hold spacebar to speak, release to send.

```bash
# In a Claude Code terminal session
/voice
```

Voice mode supports 20 languages and is optimized for technical terms and repo names. It's rolling out gradually — update to the latest version if you don't see it yet.

> **Note**
>
> Voice mode works in direct Claude Code terminal sessions. When running through OpenClaw's ACP bridge, you interact via text in your chat channel — but you can still use OpenClaw's own TTS/voice features on top.

### /loop — Recurring Tasks in Your Terminal

The `/loop` command turns Claude Code into a lightweight monitoring system:

```bash
# Check deploy status every 5 minutes
/loop 5m check the deploy status

# Run tests every 30 seconds during development
/loop 30s run the test suite

# Monitor for new issues hourly
/loop 1h check for new GitHub issues
```

Loops stay active for the session lifetime. Disable with the `CLAUDE_CODE_DISABLE_CRON` environment variable.

### /effort — Control How Hard Claude Thinks

The new `/effort` command lets you dial analysis depth up or down:

| Level | Symbol | When to Use |
|-------|--------|-------------|
| Low | ○ | Quick answers, simple operations |
| Medium | ◐ | Standard development (default for Opus 4.6) |
| High | ● | Complex debugging, architecture decisions |

For maximum effort on a single turn, use the **"ultrathink"** keyword in your prompt instead.

### 1 Million Token Context Window

Opus 4.6 now supports **1 million tokens** of context on Max, Team, and Enterprise plans — up from 200K. This means entire codebases fit in context without premature compaction. If you're working on large projects, this alone is worth the upgrade.

### Hooks — Automate Around Claude Code

Claude Code supports four hook types that fire at key lifecycle points:

- **`command`** — Run a shell command (lint on save, deploy on commit)
- **`http`** — POST to a webhook URL
- **`prompt`** — Single LLM evaluation
- **`agent`** — Multi-turn sub-agent with tool access

Example: Auto-run tests after every file edit:

```json
{
  "hooks": {
    "afterEdit": {
      "type": "command",
      "command": "npm test -- --related"
    }
  }
}
```

---

## Step 5: Managing ACP Sessions

Once Claude Code is running through OpenClaw, you have full control from chat:

### Check Status

```
/acp status
```

Shows active sessions, their state, and resource usage.

### Steer a Running Session

Need to redirect without replacing context:

```
/acp steer focus on the authentication module, skip the UI for now
```

### Switch Models Mid-Session

```
/acp model anthropic/claude-opus-4-6
```

### Cancel or Close

```
/acp cancel    # Stop current turn, keep session alive
/acp close     # End session, remove thread bindings
```

---

## Common Patterns

### Code Review from Chat

> "Start Claude Code on the feature-auth branch, review the PR changes, and summarize issues"

Claude Code reads the diff, analyzes the changes, and posts a structured review back to your chat.

### Bug Fix Pipeline

> "Run Claude Code: the /api/users endpoint returns 500 when email is missing. Find the bug and fix it."

One-shot mode works great here — Claude Code investigates, patches, and reports back.

### Overnight Build Sessions

Set up a persistent session before bed:

> "Start Claude Code in a thread. Build out the REST API for the payments module based on the spec in docs/payments-api.md. Commit to a feature branch when done."

Come back to a thread full of progress updates and a ready branch.

---

## Troubleshooting

**"ACP agent not found"**: make sure `claude` is in your `acp.allowedAgents` list and the Claude Code CLI is installed and on your PATH.

**Session times out immediately** — Check that your Claude subscription is active. Opus 4.6 requires Max, Team, or Enterprise.

**Thread binding not working** — Thread bindings are adapter-specific. On Discord, enable `channels.discord.threadBindings.spawnAcpSessions=true`. Telegram does not support native thread bindings.

**Claude Code hangs on large repos** — With the 1M context window, large codebases work better than before, but extremely large monorepos may still need scoping. Use a `.claudeignore` file to exclude build artifacts and vendor directories.

---

## What's Next

Claude Code through OpenClaw is the fastest path from "I need this built" to working code — without leaving your messaging app. The ACP integration means you get full coding agent capabilities with OpenClaw's orchestration, memory, and multi-channel delivery on top.

Pair it with OpenClaw's cron jobs for scheduled code maintenance, or chain it with other ACP agents (Codex, Gemini CLI) for multi-agent development workflows.

For deeper dives into advanced Claude Code configurations, hooks automation, and multi-agent team setups, check out the premium guides on ClawDocx.

---

*Have questions or want to share your Claude Code + OpenClaw setup? Join the [OpenClaw Discord community](https://discord.com/invite/clawd).*

## Sources

- [OpenClaw: Configuration](https://docs.openclaw.ai/gateway/configuration)
- [OpenClaw: ACP agents: setup](https://docs.openclaw.ai/tools/acp-agents-setup)
- [OpenClaw: ACP agents quickstart](https://docs.openclaw.ai/tools/acp-agents/quickstart)
- [OpenClaw: ACP agents sessions](https://docs.openclaw.ai/tools/acp-agents/sessions)
- [OpenClaw: ACP](https://docs.openclaw.ai/cli/acp)
- [OpenClaw: Configuration: runtime basics](https://docs.openclaw.ai/gateway/config-runtime)