docs(config): fix claude examples to use claude-agent-acp

[feiyun968-agent]

0. Discord Discussion URL

https://discord.com/channels/1492804973032112279/1504271921532108911

1. What problem does this solve?

Fixes #632.

config.toml.example and docs/config-reference.md both used command = "claude" with args = ["--acp"], but the Claude Code CLI has no --acp flag. Users who follow these examples get an immediate failure:

error: unknown option '--acp'

While investigating #632, docs/config-reference.md was found to have the same error and is fixed in the same PR.

2. At a Glance

Files fixed:               Before                   After
────────────────────────── ──────────────────────── ──────────────────────────
config.toml.example        command = "claude"        command = "claude-agent-acp"
                           args = ["--acp"]          args = []
                           ANTHROPIC_API_KEY         CLAUDE_CODE_OAUTH_TOKEN

docs/config-reference.md   command = "claude"        command = "claude-agent-acp"
                           args = ["--acp"]          args = []
                           ANTHROPIC_API_KEY         CLAUDE_CODE_OAUTH_TOKEN

Source of truth: docs/claude-code.md, docs/multi-agent.md, charts/openab/values.yaml, and README.md all already use claude-agent-acp.

3. Prior Art & Industry Research

Not applicable — trivial docs fix, no architectural change.

4. Proposed Solution

Sync both files with docs/claude-code.md.

5. Why This Approach

Direct sync with existing correct documentation. No behaviour change.

6. Alternatives Considered

None — the fix is unambiguous.

7. Validation

Docs-only change. Verified docs/claude-code.md (line 31), docs/multi-agent.md, charts/openab/values.yaml, and README.md all use claude-agent-acp as source of truth.

[shaun-agent]

OpenAB PR Screening

This is auto-generated by the OpenAB project-screening flow for context collection and reviewer handoff.
Click 👍 if you find this useful. Human review will be done within 24 hours. We appreciate your support and contribution 🙏

• Title: docs(config): fix claude examples to use claude-agent-acp
• Source: docs(config): fix claude examples to use claude-agent-acp #829
• Status: moved to PR-Screening
• Generated at: 2026-05-16T13:10:02.840Z
• Discord thread: not available

Screening report

screening pass complete.

GitHub comment: #829 (comment)
Project action: moved PVTI_lADOEFbZWM4BUUALzgs6Vt8 from Incoming to PR-Screening in https://github.com/orgs/openabdev/projects/1

Intent

PR #829 fixes stale Claude configuration examples that tell users to run claude --acp, a flag the Claude Code CLI does not support. The operator-visible problem is immediate setup failure for anyone copying config.toml.example or docs/config-reference.md.

Feat

Docs/config fix. It updates Claude examples to use claude-agent-acp, empty args, and CLAUDE_CODE_OAUTH_TOKEN.

Who It Serves

Deployers and maintainers.

Rewritten Prompt

Update OpenAB Claude configuration examples so every documented Claude ACP backend uses command = "claude-agent-acp", args = [], and CLAUDE_CODE_OAUTH_TOKEN. Apply this to config.toml.example and docs/config-reference.md; verify consistency with the existing Claude docs, README, Helm values, and multi-agent docs.

Merge Pitch

Low-risk docs-only fix for a real setup trap. Main reviewer concern: confirm CLAUDE_CODE_OAUTH_TOKEN is the correct credential example in these sections.

Best-Practice Comparison

OpenClaw and Hermes Agent do not materially apply. This is documentation consistency, not runtime scheduling, persistence, delivery, retry, or execution isolation.

Implementation Options

1. Conservative: merge docs sync as-is.
2. Balanced: merge and add a lightweight grep/CI guard for deprecated claude --acp.
3. Ambitious: generate/shared config snippets to prevent future docs drift.

Comparison Table

Option	Speed	Complexity	Reliability	Maintainability	User Impact	Fit for OpenAB now
Conservative docs sync	Fastest	Low	Good	Adequate	Immediate fix	Strong
Docs sync + CI guard	Fast	Low-medium	Better	Better	Prevents recurrence	Strong
Generated/shared snippets	Slowest	Medium-high	Best	Best	Broad consistency	Later

Recommendation

Merge the conservative docs-only fix after verifying the snippets match the current Claude source-of-truth docs. Split CI guard or generated-snippet work into follow-up.

[chaodu-agent]

LGTM. This aligns the config examples with the Claude ACP adapter flow and keeps the generic env example neutral.

[chaodu-agent]

CHANGES REQUESTED ⚠️ — Auth example should use claude auth login + PVC, not env var token

What This PR Does

Fixes stale Claude config examples that referenced the non-existent --acp flag, syncing them with the correct claude-agent-acp command documented in docs/claude-code.md.

How It Works

Updates config.toml.example and docs/config-reference.md to use command = "claude-agent-acp" with empty args. Also changes the env var example from ANTHROPIC_API_KEY to CLAUDE_CODE_OAUTH_TOKEN.

Findings

#	Severity	Finding	Location
1	🟢	Correct fix for command and args — matches source of truth	both files
2	🟡	CLAUDE_CODE_OAUTH_TOKEN should not be passed as env var	config.toml.example
3	🟡	Misleading comment "or set CLAUDE_CODE_OAUTH_TOKEN"	config.toml.example

Finding Details

🟢 F1: Command and args fix is correct

claude-agent-acp with empty args matches docs/claude-code.md, Helm values, and README. Good sync.

🟡 F2: OAuth token should not be in env var example

Per docs/claude-code.md § Authentication:

Sign in interactively using the OAuth device flow. Credentials are stored on disk (persisted via PVC across pod restarts):
kubectl exec -it deployment/openab-claude -- claude auth login

The documented approach is claude auth login with HOME PVC persistence — not passing CLAUDE_CODE_OAUTH_TOKEN via env. The config example's own security warning says "prefer OAuth login over env var API keys." Showing env = { CLAUDE_CODE_OAUTH_TOKEN = "..." } contradicts this guidance.

Suggested fix: Remove the Claude-specific env var line entirely, or use env = {} with a comment pointing to claude auth login.

🟡 F3: Comment "or set CLAUDE_CODE_OAUTH_TOKEN" is misleading

The added comment # Auth: run \claude auth login` once, or set CLAUDE_CODE_OAUTH_TOKENimplies both are equivalent options for container deployments.docs/claude-code.mdexplicitly distinguishes them —auth loginis for containers,setup-token` is for CI/scripts. The "or" framing may lead users to the less secure path.

Suggested fix: # Auth: run \claude auth login` once (credentials persist in HOME PVC)`

Baseline Check

• PR opened: 2026-05-16
• Main already has: docs/claude-code.md with correct claude-agent-acp + claude auth login guidance
• Net-new value: syncs config.toml.example and docs/config-reference.md with the correct command/args (valid), but introduces env var token pattern that contradicts the auth doc (needs fix)

What's Good (🟢)

• Correctly identifies and fixes the --acp flag issue
• Clean, minimal change scope
• Good PR description with source-of-truth references

---

Review by 超渡法師 🙏 on behalf of the 法師團隊

Dismissing approval — env var approach contradicts docs/claude-code.md guidance. See comment for details.

[howie]

Review Summary

Verified this fix against all source-of-truth files. The changes are accurate and consistent.

Verified Cross-Consistency

Checked docs/claude-code.md, docs/multi-agent.md, charts/openab/values.yaml, and README.md — all already use claude-agent-acp. No stray claude --acp remains anywhere in the repo after this PR.

npm Package Name

The added install comment in config.toml.example uses @agentclientprotocol/claude-agent-acp, which matches the exact package name pinned in the Dockerfile (@agentclientprotocol/claude-agent-acp@0.25.0). Correct.

Minor Observations (non-blocking)

1. Version pin in install comment

The added comment says:

# #   npm install -g @agentclientprotocol/claude-agent-acp

The Dockerfile pins @0.25.0. For a user-facing config example, using unpinned (latest) is fine, but worth a mention in case you want consistency.

2. env table example in docs/config-reference.md

The generic env field description changed from ANTHROPIC_API_KEY to OPENAI_API_KEY as a neutral example. Reasonable choice. An even more provider-agnostic placeholder like MY_AGENT_API_KEY = "${MY_AGENT_API_KEY}" might be cleaner, but OPENAI_API_KEY works since Codex is one of the supported backends.

3. command field description still lists claude as an example binary

| `command` | string | *required* | Agent binary (e.g. `kiro-cli`, `claude`, `codex`, ...). |

claude is still a valid binary — it's just not the right one for ACP (claude-agent-acp is). Consider updating this list to use claude-agent-acp instead of claude to avoid confusing users who may try command = "claude" directly.

---

Overall this is a clean, well-scoped fix. The root cause analysis is correct, the PR description clearly documents the source-of-truth files, and the changes have no behaviour impact.

[canyugs]

🔍 Panel Review Synthesis — PR #829

Verdict: ✅ APPROVE with suggested changes

The core fix is correct and unambiguous — command = "claude-agent-acp" with args = [] matches all existing source-of-truth docs. The PR solves the user-facing breakage reported in #632. The suggested changes below are all low-cost improvements that would make the PR internally consistent.

---

Findings

#	Severity	Finding	Convergence
1	🟡 Major	Install hint only installs @agentclientprotocol/claude-agent-acp but auth hint requires claude binary from @anthropic-ai/claude-code. Should be: npm install -g @anthropic-ai/claude-code @agentclientprotocol/claude-agent-acp	—
2	🟡 Major	CLAUDE_CODE_OAUTH_TOKEN env example contradicts the file's own security warning and docs/claude-code.md's canonical container auth flow (claude auth login with PVC persistence). The comment flattens the container-vs-CI distinction.	2/3 convergence
3	🟡 Minor	docs/config-reference.md:89 field-spec table still lists bare claude as an example binary — internally inconsistent with this PR's purpose.	2/3 convergence

---

Suggested Changes

1. Fix install hint (config.toml.example):

npm install -g @anthropic-ai/claude-code @agentclientprotocol/claude-agent-acp

2. Align auth guidance — either remove the CLAUDE_CODE_OAUTH_TOKEN env var example and point to claude auth login (matching docs/claude-code.md), or add a comment clarifying this is the CI/scripts path.

3. Update field-spec table (docs/config-reference.md:89): Replace claude with claude-agent-acp in the example list.

---

Panel: co-蔻迪克斯 ✅ · cl-克勞德 ✅ · ct-柯派羅 ✅ · g-居門奈 ⏳