ACP agent configuration

[winged plume]

So i told my openclaw assitant to create agents for me in my discord channel using ACP i wanted claude, gemini and codex it did the follow config below. is it correct and are these the best models to use for the channel or is there a bestter way to do this, take note that i have the various clis installed claude code cli, gemini cli, codex cli. i assumed it will connect directly to the CLIs.

{
"id": "claude",
"name": "Claude Coding Agent",
"workspace": "/Users/.openclaw/workspace-coding",
"model": {
"primary": "anthropic/claude-sonnet-4-6"
}
},
{
"id": "codex",
"name": "Codex Coding Agent",
"workspace": "/Users/.openclaw/workspace-coding",
"model": {
"primary": "openai/gpt-5.4"
}
},
{
"id": "gemini",
"name": "Gemini Coding Agent",
"workspace": "/Users/.openclaw/workspace-coding",
"model": {
"primary": "google/gemini-3.1-flash-lite-preview"
}
}
]

[last thorn]

To help others find answers, you can mark your question as solved via Right click solution message -> Apps -> ✅ Mark Solution

[glass prism]

That config is “normal OpenClaw agents that call model APIs”, not ACP/CLI-backed agents.

1) Will it connect to your installed CLIs?

No — having Claude Code / Gemini CLI / Codex CLI installed does not auto-wire them.
To use those CLIs, you need ACP runtime (via the ACP backend plugin, typically acpx) and an agent (or binding) whose runtime.type is "acp". See: https://docs.openclaw.ai/tools/acp-agents

Your snippet only sets:

model: { primary: "provider/model" }

…which means “use this provider over HTTP”, not “run the CLI”.

2) Is the config “correct” as-is?

It’s syntactically plausible for API-based agents, but a few red flags:

• workspace: "/Users/.openclaw/workspace-coding" looks wrong on macOS (usually /Users/<you>/... or just use ~/.openclaw/workspace-coding).
• If your intent was “Codex subscription OAuth / Codex CLI”, note the docs treat Codex as openai-codex/..., not plain openai/... (API). (So your “codex” agent might not be doing what you think.)
• “Best models” depends on your goals/cost/tool-reliability — I wouldn’t hardcode “best” without checking what your gateway actually has available (/model list or openclaw models list). Model advice also changes fast; #models is the best place for current recs.

3) The “better way” (if you want CLI harnesses in Discord)

Recommended pattern: keep one normal chat agent for orchestration, and spawn a coding harness when needed:

• In Discord, run:
  /acp spawn codex --mode persistent --thread auto
  (or claude / gemini)
• Then keep follow-ups inside the bound thread.

Docs/runbook: https://docs.openclaw.ai/tools/acp-agents

If you want a channel to always be an ACP session, use bindings[] with type:"acp" and set the agent’s runtime.type:"acp" (examples are in that doc).

4) Quick checks to run (so we’re not guessing)

Please paste these outputs:

1. openclaw --version
2. openclaw models status
3. /acp doctor (from that Discord channel)

That’ll confirm whether ACP is enabled, whether the acpx backend is installed/healthy, and what models/providers are actually available on your gateway host.

[winged plume]

Last login: Tue Mar 10 16:36:42 on ttys009
➜ ~ openclaw --version
OpenClaw 2026.3.8 (ce9e91f)

➜ ~ openclaw models status
🦞 OpenClaw 2026.3.8 (ce9e91f)
I'll butter your workflow like a lobster roll: messy, delicious, effective.
Config : ~/.openclaw/openclaw.json
Agent dir : ~/.openclaw/agents/main/agent
Default : anthropic/claude-opus-4-6
Fallbacks (2) : anthropic/claude-opus-4-5-20250918, anthropic/claude-sonnet-4-6
Image model : -
Image fallbacks (0): -
Aliases (6) : opus -> anthropic/claude-opus-4-6, opus45 -> anthropic/claude-opus-4-5-20250918, gemini-flash-lite -> google/gemini-3.1-flash-lite-preview, sonnet46 -> anthropic/claude-sonnet-4-6, qwen35-4b -> ollama/qwen3.5:4b, gpt -> openai/gpt-5.4
Configured models (8): anthropic/claude-opus-4-6, anthropic/claude-opus-4-5-20250918, openrouter/anthropic/claude-4.6-opus, openrouter/anthropic/claude-opus-4.5, google/gemini-3.1-flash-lite-preview, anthropic/claude-sonnet-4-6, ollama/qwen3.5:4b, openai/gpt-5.4
Auth overview
Auth store : ~/.openclaw/agents/main/agent/auth-profiles.json

Shell env : off
Providers w/ OAuth/tokens (1): anthropic (2)

• anthropic effective=profiles:~/.openclaw/agents/main/agent/auth-profiles.json | profiles=3 (oauth=0, token=2, api_key=1) | anthropic:openclaw-claude-token=token:sk-ant-o...AEDe_jk2, anthropic:anthropi-openclaw=token:sk-ant-o...IqeVWwAA, anthropic:direct-api-key=sk-ant-a...S9cYCwAA [disabled:billing 3h] | env=sk-ant-a...S9cYCwAA | source=env: ANTHROPIC_API_KEY
• google effective=profiles:~/.openclaw/agents/main/agent/auth-profiles.json | profiles=1 (oauth=0, token=0, api_key=1) | google:gemini=AIzaSyCu...NzrE2CSw
• openai effective=profiles:~/.openclaw/agents/main/agent/auth-profiles.json | profiles=1 (oauth=0, token=0, api_key=1) | openai:default=sk-proj-...VQ-lHDAA
• openrouter effective=profiles:~/.openclaw/agents/main/agent/auth-profiles.json | profiles=1 (oauth=0, token=0, api_key=1) | openrouter:default=sk-or-v1...601eeaaf | env=sk-or-v1...601eeaaf | source=env: OPENROUTER_API_KEY
  OAuth/token status
• anthropic
  • anthropic:anthropi-openclaw static
  • anthropic:openclaw-claude-token static
    ➜ ~ /acp doctor
    zsh: no such file or directory: /acp
    ➜ ~

/acp doctor

ACP doctor:

configuredBackend: acpx
activeRuntimeSessions: 0
runtimeIdleTtlMs: 0
evictedIdleRuntimes: 0
activeTurns: 0
queueDepth: 0
turnLatencyMs: avg=0, max=0
turnCounts: completed=0, failed=0
errorCodes: (none)
registeredBackend: (none)
healthy: no

ACP error (ACP_BACKEND_MISSING): ACP runtime backend is not configured. Install and enable the acpx runtime
plugin.
next: Run /acp doctor, install/enable the backend plugin, then retry.
next: openclaw plugins install acpx
next: openclaw config set plugins.entries.acpx.enabled true
next: verify acpx is installed (acpx --help).
connected | idle
agent main (Tóbi) | session main (openclaw-tui) | anthropic/claude-opus-4-6 | think adaptive | tokens 54k/200k
(27%)

[glass prism]

Nice — 2026.3.8 is recent enough for the ACP stuff in the docs.

Your config snippet is not ACP

Those model.primary: "provider/model" agents are API-backed OpenClaw agents. They won’t “use your installed Claude/Codex/Gemini CLIs” unless you configure ACP runtime.

If you want “connect directly to the CLIs”, your agents need something like:

• runtime.type: "acp"
• runtime.acp.agent: "codex" | "claude" | "gemini"
• plus ACP enabled + the ACP backend plugin (usually acpx) installed/enabled

Docs: https://docs.openclaw.ai/tools/acp-agents

Also: your workspace path looks wrong

On macOS you almost certainly want one of these instead:

• "workspace": "~/.openclaw/workspace-coding" (recommended)

• or "/Users/<your-username>/.openclaw/workspace-coding"

/Users/.openclaw/... is missing the username and is usually not a real directory.

What I need from you to confirm your ACP wiring

Please paste:

1. openclaw models status
2. In Discord (same channel/thread), run: /acp doctor and paste the output

Those two will tell us:

• whether ACP is enabled (acp.enabled=true)
• whether the acpx backend is installed/healthy
• whether your gateway is actually set up to spawn claude/codex/gemini ACP sessions

Once you paste that, I’ll tell you the exact minimal config changes (or whether you can skip config entirely and just use /acp spawn …).

[winged plume]

my workspace path is not wrong i was the one who deleted the username part

[glass prism]

Perfect — that models status output tells us one important thing:

What you have right now is API model config, not ACP/CLI wiring

openclaw models status is showing your main agent using agents.defaults.model.* (Opus + Anthropic fallbacks, plus OpenAI/Gemini models in the allowlist). That’s the “call provider APIs by model id” path.

It does not indicate that ACP is enabled, nor that Codex/Claude/Gemini CLIs are being used.

Quick sanity check: did those 3 agents even get created?

Run:

openclaw agents list

If you only see main, then that snippet never actually landed in agents.list[] (or didn’t reload).

If your goal is “use the installed CLIs”, the agent config needs ACP runtime

Those agents should look more like “runtime=acp”, not model.primary=....

The docs pattern is:

• install/enable the acpx plugin backend
• set acp.enabled=true + acp.allowedAgents=[...]
• set the agent’s runtime.type:"acp" and runtime.acp.agent:"codex|claude|gemini"

Docs + example config: https://docs.openclaw.ai/tools/acp-agents

Next 2 outputs that will unblock this

1. From your shell:

openclaw plugins list

(we’re looking for acpx and whether it’s enabled)

2. In Discord, run:

/acp doctor

…and paste it. That usually immediately tells us what’s missing (ACP disabled, backend not installed, CLI not found on PATH, permission mode issues, etc.).

After you paste those, I’ll tell you the exact minimal commands/config edits to get “/acp spawn codex/claude/gemini” working in your channel the way you expect.

Yep — the zsh: no such file or directory: /acp is just because you ran it in your terminal.

/acp … is a chat slash command, not a shell command

You need to send this as a message in Discord to your OpenClaw bot, e.g. literally type in the Discord channel/thread:

/acp doctor

(Do not run it in zsh.)

Terminal-side checks to run instead

In your shell, run these and paste the output:

openclaw plugins list

openclaw plugins doctor

We’re looking for whether the acpx plugin/backend is installed + enabled.

Why your “3 agents” config still isn’t ACP

Everything you pasted with:

model: { primary: "anthropic/..." | "openai/..." | "google/..." }

is the API-provider route. That will never “connect directly to the CLIs”.

To use the CLIs (Claude Code / Codex CLI / Gemini CLI) you need ACP enabled + an ACP backend (usually acpx):

Docs: https://docs.openclaw.ai/tools/acp-agents

One important clue from your output: Shell env : off

That means your gateway/service isn’t importing your login shell environment. Even after ACP is enabled, this can matter because the ACP backend may need to find claude, codex, gemini on PATH (depending on how acpx is configured). We’ll confirm via /acp doctor once you run it in Discord.

Next step

1. Paste openclaw plugins list + openclaw plugins doctor (from terminal)
2. Paste the response from Discord when you message the bot: /acp doctor

Then I’ll tell you exactly what to add/change (install/enable acpx, acp.enabled=true, allowedAgents, thread binding flags, and permissionMode so coding sessions don’t fail non-interactively).

Good — that /acp doctor output is the smoking gun:

ACP_BACKEND_MISSING: ACP runtime backend is not configured. Install and enable the acpx runtime plugin.

So ACP is reachable from Discord, but the backend plugin that actually runs Claude/Codex/Gemini CLIs isn’t installed/enabled yet.

Fix (run on the gateway host in your terminal)

Follow exactly what the doctor suggested:

openclaw plugins install acpx
openclaw config set plugins.entries.acpx.enabled true
openclaw gateway restart

Then sanity-check:

openclaw plugins list | rg acpx
acpx --help # this verifies the acpx binary is available on PATH

(If acpx isn’t on PATH but the plugin is installed, that’s still OK — the plugin can run its pinned binary. The important part is that OpenClaw sees the plugin as enabled after restart.)

Then re-run in Discord (as a message to the bot)

/acp doctor

At that point it should move past “backend missing” and start telling you the next issues (common next one is missing CLI executables on PATH because your gateway service has Shell env: off).

Docs for the overall setup: https://docs.openclaw.ai/tools/acp-agents

Once /acp doctor is clean, we can circle back to your original “3 agents” config — but the short version is: those model.primary agents are API-based; ACP/CLI sessions are configured via ACP runtime + /acp spawn … (or bindings/runtime.type="acp" if you want it permanent).

Ah got it — you redacted the username for posting here.

Two practical notes:

1. In your real openclaw.json, the path must be an actual valid path.
   If you don’t want to leak /Users/<you>/…, just use the tilde form (recommended):

workspace: "~/.openclaw/workspace-coding"

That keeps it portable and avoids exposing your username.

2. If you end up running multiple agents that can write files, consider giving them separate workspaces (or at least separate subfolders) to avoid them stepping on the same repo/files simultaneously.

Re ACP: once you install/enable the acpx plugin and restart, run /acp doctor again in Discord — that will tell us the next missing piece (usually PATH/CLI visibility or permissions mode).

[winged plume]

alot of what you said here is good but i can see repetitions and its quite volminous i want you to break the solution down into 2 paths.

1. what part of all you have said here is what i should manually do to setup the ACP
2. what part of what you have said here are what i should prompt my openclaw to do for me.

[glass prism]

Path 1 — what you should do manually (recommended)

Do these on the gateway host (your Mac/VPS where OpenClaw is running):

1. Install + enable the ACP backend plugin (acpx)

openclaw plugins list
openclaw plugins install acpx
openclaw plugins enable acpx # if this errors, use: openclaw config set plugins.entries.acpx.enabled true

2. Turn on ACP + allow the harnesses you want

openclaw config set acp.enabled true
openclaw config set acp.backend "acpx"
openclaw config set acp.allowedAgents '["claude","codex","gemini"]'

3. (Discord) allow thread-bound ACP spawns

openclaw config set session.threadBindings.enabled true
openclaw config set channels.discord.threadBindings.enabled true
openclaw config set channels.discord.threadBindings.spawnAcpSessions true

4. Avoid non-interactive permission failures (common gotcha)
   If you want the coding CLIs to be able to write files/run commands:

openclaw config set plugins.entries.acpx.config.permissionMode "approve-all"
openclaw config set plugins.entries.acpx.config.nonInteractivePermissions "deny"

5. Restart

openclaw gateway restart

6. Verify from Discord
   Send to the bot (in Discord):

/acp doctor
/acp spawn codex --mode oneshot --thread off

---

Path 2 — what to prompt your OpenClaw to do for you

Use prompts when you want the bot to drive the process, but you still supervise.

A) Best “safe” prompt (bot guides, you copy/paste commands)

Send in Discord:

“Run /acp doctor and tell me exactly what’s missing. Then give me the exact openclaw plugins … and openclaw config set … commands to fix it. Keep it minimal and ordered.”

B) “Do it for me” prompt (bot executes changes; only if you trust it + have exec enabled)
Send in Discord:

“Install and enable the acpx plugin, enable ACP with acp.backend=acpx, allow agents claude/codex/gemini, enable Discord threadBindings spawn for ACP, set acpx permissionMode to approve-all + nonInteractivePermissions=deny, then restart the gateway. After restart, run /acp doctor again and report the result.”

If you tell me whether you want A (guide) or B (auto-execute), I can tailor the exact minimal wording for your setup.

[winged plume]

which of these commands restart the gateway

openclaw gateway restart or /restart

[glass prism]

openclaw gateway restart is the definite one — it restarts the Gateway service from your terminal on the gateway host (launchd/systemd/etc).

/restart is a chat slash-command (send it in Discord to the bot). It only works if your config allows it (commands.restart must be enabled). If it’s disabled, it’ll be ignored or you’ll get a “restart disabled” style message.

Rule of thumb:

• Have shell access to the gateway host → use openclaw gateway restart
• No shell access / you’re already in Discord → try /restart (if enabled)