Skip to content

LeoYeAI/agent-master-skills / skills/bengii-gemini-fix

openclaw

Flagged

Comprehensive guide for installing, configuring, operating, and troubleshooting OpenClaw — a self-hosted, multi-channel AI agent gateway. Use when the user asks about OpenClaw setup, configuration, channel management (WhatsApp/Telegram/Discord/Slack/iMessage/etc.), model provider setup, Gateway operations, multi-agent routing, security hardening, troubleshooting, or any maintenance task related to their local OpenClaw installation. Also use when encountering errors from `openclaw` CLI commands or the Gateway daemon.

FileKindSize
README.mdmarkdown7.5 KB
README_CN.mdmarkdown7.3 KB
SKILL.mdskill md18.7 KB
_meta.jsonconfig286 B
references/acp_agents.mdmarkdown12.6 KB
references/agent_runtime.mdmarkdown5.6 KB
references/architecture.mdmarkdown3.8 KB
references/automation.mdmarkdown5.8 KB
references/bonjour.mdmarkdown3.3 KB
references/browser.mdmarkdown8.5 KB
references/channel_routing.mdmarkdown4.0 KB
references/channel_troubleshooting.mdmarkdown11.6 KB
references/channels.mdmarkdown6.2 KB
references/clawhub.mdmarkdown3.6 KB
references/config_reference.mdmarkdown11.2 KB
references/diffs_firecrawl.mdmarkdown3.3 KB
references/elevated.mdmarkdown2.8 KB
references/exec.mdmarkdown6.5 KB
references/exec_approvals.mdmarkdown3.1 KB
references/gateway_internals.mdmarkdown7.7 KB
references/gateway_ops.mdmarkdown9.6 KB
references/heartbeat.mdmarkdown4.9 KB
references/hooks.mdmarkdown14.6 KB
references/install.mdmarkdown4.1 KB
references/llm_task.mdmarkdown2.6 KB
references/lobster.mdmarkdown7.8 KB
references/media.mdmarkdown4.2 KB
references/memory.mdmarkdown11.9 KB
references/model_failover.mdmarkdown3.1 KB
references/multi_agent.mdmarkdown4.4 KB
references/nodes.mdmarkdown8.8 KB
references/openprose.mdmarkdown2.6 KB
references/pairing.mdmarkdown3.1 KB
references/pdf_tool.mdmarkdown3.5 KB
references/platforms.mdmarkdown2.7 KB
references/plugins.mdmarkdown6.9 KB
references/polls.mdmarkdown2.2 KB
references/presence_discovery.mdmarkdown2.2 KB
references/providers.mdmarkdown6.0 KB
references/queue.mdmarkdown2.1 KB
references/remote_access.mdmarkdown4.7 KB
references/sandboxing.mdmarkdown5.6 KB
references/secrets.mdmarkdown5.4 KB
references/security.mdmarkdown24.5 KB
references/sessions.mdmarkdown8.9 KB
references/skills.mdmarkdown4.4 KB
references/slash_commands.mdmarkdown5.1 KB
references/streaming.mdmarkdown1.8 KB
references/subagents.mdmarkdown12.3 KB
references/thinking.mdmarkdown2.8 KB
references/tools.mdmarkdown13.3 KB
references/tui.mdmarkdown4.0 KB
references/voice.mdmarkdown2.7 KB
references/web_tools.mdmarkdown2.7 KB
references/web_ui.mdmarkdown4.5 KB

references/acp_agents.md

View on GitHub
# OpenClaw ACP Agents Reference

## Table of Contents

- [Overview](#overview)
- [ACP vs Sub-Agents](#acp-vs-sub-agents)
- [Fast Operator Flow](#fast-operator-flow)
- [ACP Controls](#acp-controls)
- [ACP Command Cookbook](#acp-command-cookbook)
- [Thread-Bound Sessions](#thread-bound-sessions)
- [Session Target Resolution](#session-target-resolution)
- [Supported Harnesses](#supported-harnesses)
- [Required Config](#required-config)
- [Plugin Setup](#plugin-setup)
- [Permission Configuration](#permission-configuration)
- [Troubleshooting](#troubleshooting)
- [ACP CLI Bridge](#acp-cli-bridge-openclaw-acp)

## Overview

ACP (Agent Communication Protocol) agents allow OpenClaw to spawn and manage external AI agent runtimes (Codex, Claude Code, Gemini CLI, OpenCode, etc.) as persistent or one-shot sessions, with thread-bound routing and live controls.

Natural-language triggers:
- "Start a persistent Codex session in a thread and keep it focused."
- "Run this as a one-shot Claude Code ACP session and summarize the result."
- "Use Gemini CLI for this task in a thread, then keep follow-ups in that same thread."

## ACP vs Sub-Agents

| Feature | ACP (`runtime: "acp"`) | Sub-agents (`runtime: "subagent"`) |
|---|---|---|
| Session key | `agent:<agentId>:acp:<uuid>` | `agent:<agentId>:subagent:<uuid>` |
| Slash commands | `/acp ...` | `/subagents ...` |
| Tool call | `sessions_spawn` with `runtime:"acp"` | `sessions_spawn` with `runtime:"subagent"` |
| External runtime | Yes (via acpx harness) | No (internal Pi) |
| Thread binding | Supported | Supported |
| Persistent sessions | Yes | One-shot or persistent |

## Fast Operator Flow

```
/acp spawn codex --mode persistent --thread auto   # 1. Spawn session
# Work in the bound thread...
/acp status                                          # 2. Check state
/acp model <provider/model>                          # 3. Tune model
/acp permissions <profile>                           # 4. Set permissions
/acp timeout <seconds>                               # 5. Set timeout
/acp steer tighten logging and continue              # 6. Nudge without replacing context
/acp cancel                                          # 7. Stop current turn
/acp close                                           # 8. Close session + remove bindings
```

## ACP Controls

| Command | Description |
|---|---|
| `/acp spawn` | Create new ACP session |
| `/acp cancel` | Stop current turn |
| `/acp steer` | Nudge active session without replacing context |
| `/acp close` | Close session + remove bindings |
| `/acp status` | Runtime state summary |
| `/acp set-mode` | Change execution mode (e.g., `plan`) |
| `/acp set <key> <value>` | Generic runtime option override |
| `/acp cwd <path>` | Update working directory |
| `/acp permissions <profile>` | Set permission profile |
| `/acp timeout <seconds>` | Set timeout |
| `/acp model <id>` | Change model |
| `/acp reset-options` | Clear all runtime overrides |
| `/acp sessions` | List active ACP sessions |
| `/acp doctor` | Diagnose ACP setup |
| `/acp install` | Install ACP dependencies |

### Runtime Options Mapping

| `/acp` Command | Runtime Config Key |
|---|---|
| `/acp model <id>` | `model` |
| `/acp permissions <profile>` | `approval_policy` |
| `/acp timeout <seconds>` | `timeout` |
| `/acp cwd <path>` | cwd override |
| `/acp set <key> <value>` | generic path (`key=cwd` uses cwd path) |

## ACP Command Cookbook

```
/acp spawn codex --mode persistent --thread auto --cwd /repo
/acp cancel agent:codex:acp:<uuid>
/acp steer --session support inbox prioritize failing tests
/acp close
/acp status
/acp set-mode plan
/acp set model openai/gpt-5.2
/acp cwd /Users/user/Projects/repo
/acp permissions strict
/acp timeout 120
/acp model anthropic/claude-opus-4-5
/acp reset-options
/acp sessions
/acp doctor
/acp install
```

## Thread-Bound Sessions

Thread binding works across channels:

1. OpenClaw binds a thread to a target ACP session
2. Follow-up messages in that thread route to the bound ACP session
3. ACP output is delivered back to the same thread
4. Unfocus/close/archive/idle-timeout or max-age expiry removes the binding

**Spawn thread modes** (`--thread`):

| Mode | Behavior |
|---|---|
| `auto` | Create thread if channel supports it |
| `here` | Bind to current thread |
| `off` | No thread binding |

### Required Config for Thread Binding

```json5
{
  session: {
    threadBindings: {
      enabled: true,
      idleHours: 24,
      maxAgeHours: 0,
    },
  },
  channels: {
    discord: {
      threadBindings: {
        enabled: true,
        spawnAcpSessions: true,
      },
    },
  },
}
```

## Session Target Resolution

When a `/acp` command refers to a target session, resolution order:

1. Explicit target argument (or `--session` for `/acp steer`)
   - tries key → UUID-shaped session id → label
2. Current thread binding (if thread is bound to ACP session)
3. Current requester session fallback

## Supported Harnesses

| Harness | Agent ID |
|---|---|
| Pi (OpenClaw internal) | `pi` |
| Claude Code | `claude` |
| Codex | `codex` |
| OpenCode | `opencode` |
| Gemini CLI | `gemini` |

Custom agents can be added with `--agent <command>`.

## Required Config

```json5
{
  acp: {
    enabled: true,
    dispatch: { enabled: true },
    backend: "acpx",
    defaultAgent: "codex",
    allowedAgents: ["pi", "claude", "codex", "opencode", "gemini"],
    maxConcurrentSessions: 8,
    stream: {
      coalesceIdleMs: 300,
      maxChunkChars: 1200,
    },
    runtime: {
      ttlMinutes: 120,
    },
  },
}
```

## Plugin Setup

### Install acpx Backend

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

# From source
openclaw plugins install ./extensions/acpx

# Verify
/acp doctor
```

## Permission Configuration

### permissionMode

| Mode | Behavior |
|---|---|
| `approve-all` | Auto-approve all permission prompts |
| `approve-reads` | Auto-approve read-only, prompt for writes |
| `deny-all` | Deny all permission prompts |

### nonInteractivePermissions

| Mode | Behavior |
|---|---|
| `fail` | Throw `AcpRuntimeError` on permission prompt |
| `deny` | Silently deny permission |

### Configure

```bash
openclaw config set plugins.entries.acpx.config.permissionMode approve-all
openclaw config set plugins.entries.acpx.config.nonInteractivePermissions fail
```

**Recommended for non-interactive**: `permissionMode=approve-reads` + `nonInteractivePermissions=fail`.

## Troubleshooting

| Error | Fix |
|---|---|
| `ACP runtime backend is not configured` | Run `/acp doctor`, install acpx plugin |
| `ACP is disabled by policy (acp.enabled=false)` | Set `acp.enabled=true` |
| `ACP dispatch is disabled by policy` | Set `acp.dispatch.enabled=true` |
| `ACP agent "<id>" is not allowed by policy` | Add `agentId` to `acp.allowedAgents` |
| `Unable to resolve session target: ...` | Check `/acp sessions` for active sessions |
| `--thread here requires running inside an active thread` | Use `--thread auto` or `off` |
| `Only <user-id> can rebind this thread` | Original spawner must rebind |
| `Thread bindings are unavailable for <channel>` | Use `--thread off` or enable thread bindings |
| `AcpRuntimeError: Permission prompt unavailable` | Set `permissionMode` to `approve-all` |

---

## ACP CLI Bridge (`openclaw acp`)

> Source: https://docs.openclaw.ai/cli/acp

The `openclaw acp` command runs an ACP-compatible stdio bridge, letting external IDE agents (Codex, Claude Code, Zed, etc.) send prompts into an OpenClaw Gateway session.

### Usage

```bash
# Default (local Gateway)
openclaw acp

# Remote Gateway
openclaw acp --url wss://gateway-host:18789 --token <token>

# Remote Gateway (token from file — preferred for process safety)
openclaw acp --url wss://gateway-host:18789 --token-file ~/.openclaw/gateway.token

# Attach to an existing session key
openclaw acp --session agent:main:main

# Attach by label (must already exist)
openclaw acp --session-label "support inbox"

# Reset the session key before the first prompt
openclaw acp --session agent:main:main --reset-session
```

### ACP Client (Debug Mode)

```bash
# Default
openclaw acp client

# Point the spawned bridge at a remote Gateway
openclaw acp client --server-args --url wss://gateway-host:18789 --token-file ~/.openclaw/gateway.token

# Override the server command (default: openclaw)
openclaw acp client --server "node" --server-args openclaw.mjs acp --url ws://127.0.0.1:19001
```

### Security Notes (Auto-Approval)

- Auto-approval is **allowlist-based** and only applies to trusted core tool IDs.
- `read` auto-approval is scoped to the current working directory (`--cwd` when set).
- Unknown/non-core tool names, out-of-scope reads, and dangerous tools always require explicit prompt approval.
- Server-provided `toolCall.kind` is treated as **untrusted metadata** (not an authorization source).

### Selecting Agents

```bash
openclaw acp --session agent:main:main      # Main agent, main session
openclaw acp --session agent:design:main    # Design agent
openclaw acp --session agent:qa:bug-123     # QA agent, specific issue
```

### Session Mapping

| Flag | Description |
|---|---|
| `--session <key>` | Use a specific Gateway session key |
| `--session-label <label>` | Resolve an existing session by label |
| `--reset-session` | Mint a fresh session id for that key (same key, new transcript) |
| `--require-existing` | Fail if the session key/label does not exist |

JSON meta equivalent:
```json
{
  "_meta": {
    "sessionKey": "agent:main:main",
    "sessionLabel": "support inbox",
    "resetSession": true
  }
}
```

### Options

#### `openclaw acp` Options

| Flag | Description |
|---|---|
| `--url <url>` | Gateway WebSocket URL (defaults to `gateway.remote.url`) |
| `--token <token>` | Gateway auth token |
| `--token-file <path>` | Read auth token from file (preferred) |
| `--password <password>` | Gateway auth password |
| `--password-file <path>` | Read auth password from file |
| `--session <key>` | Default session key |
| `--session-label <label>` | Default session label to resolve |
| `--require-existing` | Fail if session doesn't exist |
| `--reset-session` | Reset session before first use |
| `--no-prefix-cwd` | Do not prefix prompts with working directory |
| `--verbose, -v` | Verbose logging to stderr |

#### `acp client` Options

| Flag | Description |
|---|---|
| `--cwd <dir>` | Working directory for the ACP session |
| `--server <command>` | ACP server command (default: `openclaw`) |
| `--server-args <args...>` | Extra arguments passed to the ACP server |
| `--server-verbose` | Enable verbose logging on the ACP server |
| `--verbose, -v` | Verbose client logging |

### Auth Resolution

- **`--token`/`--password`** can be visible in local process listings — prefer `--token-file`/`--password-file` or env vars.
- **Local mode**: env (`OPENCLAW_GATEWAY_*`) → `gateway.auth.*` → `gateway.remote.*` fallback
- **Remote mode**: `gateway.remote.*` with env/config fallback per remote precedence rules
- **`--url` is override-safe**: does not reuse implicit config/env credentials; pass explicit `--token`/`--password`

### Environment

- ACP runtime backend processes receive `OPENCLAW_SHELL=acp`.
- `openclaw acp client` sets `OPENCLAW_SHELL=acp-client` on the spawned bridge process.

### Use from acpx (Codex, Claude, Other ACP Clients)

```bash
# One-shot request into your default OpenClaw ACP session
acpx openclaw exec "Summarize the active OpenClaw session state."

# Persistent named session for follow-up turns
acpx openclaw sessions ensure --name codex-bridge
acpx openclaw -s codex-bridge --cwd /path/to/repo \
  "Ask my OpenClaw work agent for recent context relevant to this repo."
```

#### acpx Config (`~/.acpx/config.json`)

```json
{
  "agents": {
    "openclaw": {
      "command": "env OPENCLAW_HIDE_BANNER=1 OPENCLAW_SUPPRESS_NOTES=1 openclaw acp --url ws://127.0.0.1:18789 --token-file ~/.openclaw/gateway.token --session agent:main:main"
    }
  }
}
```

### Zed Editor Setup

Add to `~/.config/zed/settings.json`:

```json
{
  "agent_servers": {
    "OpenClaw ACP": {
      "type": "custom",
      "command": "openclaw",
      "args": ["acp"],
      "env": {}
    }
  }
}
```

Remote with specific agent:
```json
{
  "agent_servers": {
    "OpenClaw ACP": {
      "type": "custom",
      "command": "openclaw",
      "args": [
        "acp",
        "--url", "wss://gateway-host:18789",
        "--token", "<token>",
        "--session", "agent:design:main"
      ],
      "env": {}
    }
  }
}
```

### How to Use This

1. Ensure the Gateway is running (local or remote).
2. Configure the Gateway target (config or flags):
   ```bash
   openclaw config set gateway.remote.url wss://gateway-host:18789
   openclaw config set gateway.remote.token <token>
   ```
3. Point your IDE to run `openclaw acp` over stdio.

rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first.Stars: 194kUpdated Claude CodeCodexVerifiedInstall