ACP Overview

Agent Client Protocol: one setup that works across Zed, Devin Desktop and JetBrains — run Claude Code as an ACP agent with its environment pointed at QCode

ACP Overview¶

The Agent Client Protocol (ACP) is an open standard that decouples editors from AI agents — think LSP, but for agents. Any editor that speaks ACP can host any agent that speaks ACP, with no bespoke integration per agent.

For QCode users this has a very practical consequence:

🔑 Configure the agent itself (for example the Claude Code CLI) against QCode, and every host follows automatically. ACP hosts launch the agent as a child process, so it inherits your environment. Once ANTHROPIC_BASE_URL / ANTHROPIC_AUTH_TOKEN are set, sessions in Zed, Devin Desktop and JetBrains all route through QCode — you do not repeat the setup per editor.

Hosts that speak ACP¶

Agents that speak ACP¶

Common ones are Claude Code, Codex CLI and OpenCode, plus anything that implements ACP itself. Each host ships its own adapter and launch command, so defer to the host's documentation for exact commands.

Setup: configure once, works everywhere¶

Claude Code (Anthropic leg)¶

export ANTHROPIC_BASE_URL="https://api.qcode.cc/api"
export ANTHROPIC_AUTH_TOKEN="cr_your_qcode_key"

Persist them in ~/.zshrc / ~/.bashrc. From mainland China, use https://asia.qcode.cc/api.

You can also put them in the env block of ~/.claude/settings.json for the same effect. See Environment Variables.

Codex CLI (OpenAI Responses leg)¶

Codex is configured through TOML with base_url stopping at /openai. See the Codex guide.

🔴 A common trap: GUI-launched editors do not see your shell environment¶

On macOS and Linux, an editor started from the Dock, a launcher or a desktop icon does not read ~/.zshrc. The symptom: claude reaches QCode from a terminal, but the ACP session inside the editor fails to authenticate.

Two ways to handle it:

1. Launch the editor from a terminal (e.g. zed .) so it inherits the current shell environment
2. Put the configuration in the agent's own config file rather than a shell profile (Claude Code: the env block of ~/.claude/settings.json)

Option 2 is more robust because it does not depend on how the editor was started.

Verifying that traffic reaches QCode¶

KEY="cr_your_qcode_key"
curl -s -o /dev/null -w '%{http_code}\n' -X POST https://api.qcode.cc/api/v1/messages \
  -H "x-api-key: $KEY" -H "anthropic-version: 2023-06-01"
# 400 = path and key are both fine (a missing body is expected); 401 = key problem

Once the endpoint checks out, open a session in the host. If it still fails, the problem is in how the host launches the agent (usually the environment trap above), not in QCode.

Every request through QCode is reported to probe.qcode.cc — enter your API key to confirm requests actually arrive.

Related¶

• Endpoints & API Paths — protocol × model-family table
• Environment Variables
• Zed Setup · Devin Desktop Setup · JetBrains IDEs