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

Updated 2026-11-13

Need an API key? Sign up →Endpoints & base URLs →

On This Page

Last verified: 2026-10-15 · 📄 Per official docs (agentclientprotocol.com, checked the same day)

At a glance

Item Details
Models you can use depend on the mounted agent: Claude Agent / Claude Code (Anthropic endpoint) ✅ · GPT ✅ (Codex-style agents) · Chinese models ✅ · Gemini not offered by QCode for now
Protocol & Base URL configured in the agent itself: Anthropic endpoint https://api.qcode.cc/api for Claude-family agents
Where to configure the agent's environment / own config file; the host merely launches it
Official docs Agent Client Protocol

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

Host Notes Our docs
Zed Native support; sessions open in the agent panel Zed Setup
Devin Desktop (formerly Windsurf) Supported since 2026-06-02, inside the Agent Command Center Devin Desktop Setup
JetBrains IDEs Through an ACP plugin JetBrains IDEs
Neovim / Emacs / Sublime / Qt Creator etc. listed in the official editors catalogue —

Agents that speak ACP

Notable entries include Claude Agent (the name in the official registry — the ACP wrapper of the Claude Agent SDK, claude-agent-acp) and OpenCode; the full catalogue lives on agentclientprotocol.com. Anything implementing ACP can be mounted. Each host ships its own adapter and launch command, so defer to the host's documentation.

Setup: configure once, works everywhere

Claude Code (Anthropic endpoint)

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 endpoint)

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.

How ACP starts the agent: why environment variables are "inherited"

As of 2026-10-15, according to ACP's official transport documentation: ACP encodes messages as JSON-RPC, and with the recommended stdio transport the client (the editor) launches the agent as a subprocess; the agent reads JSON-RPC messages from standard input and writes messages to standard output, delimited by newlines, and may write logs to standard error (stderr). The protocol also forbids the agent from writing anything to stdout that is not a valid ACP message.

Two practical conclusions follow for troubleshooting:

  • A subprocess inherits the environment of whatever launched it by default, so whether ANTHROPIC_BASE_URL set in your shell takes effect depends on how the editor itself was started (see the GUI-launch pitfall above).
  • If you wrap the agent in your own script, do not echo greetings or debug output to stdout inside it, or it will be treated as an invalid message; write such output to stderr instead.

Key settings explained

Setting Purpose Notes
ANTHROPIC_BASE_URL Endpoint for Claude-family agents Use https://api.qcode.cc/api, without /v1 and without a trailing slash
ANTHROPIC_AUTH_TOKEN Your QCode key Starts with cr_, sent as an Authorization: Bearer header
env block in ~/.claude/settings.json Writes the two values above into the agent's own config Independent of how the editor starts; the most robust option
Codex base_url Endpoint for Codex-style agents Ends at /openai; see the full Codex guide
The agent launch command in the host Tells the editor how to start the agent Differs per host; follow the host's documentation

Common errors and how to troubleshoot

Symptom Likely cause Fix
claude works in the terminal but the ACP session in the editor fails authentication The editor was started from the Dock or launcher and did not read your shell variables Start the editor from a terminal, or put the config in the env block of ~/.claude/settings.json
401 / Invalid API key Wrong or space-padded key, or a stale ANTHROPIC_API_KEY taking over authentication Run env \| grep -i anthropic to find leftovers
404 /v1 added to the Base URL, or a trailing slash Set it back to https://api.qcode.cc/api
model_not_available_on_endpoint A GPT model was chosen in a Claude-family agent, or a Claude model in a Codex-style agent Claude uses the Anthropic interface and GPT uses OpenAI Responses; see Endpoints and API Formats
The session hangs on "starting" or disconnects immediately The agent could not start as a subprocess, or a wrapper script prints to stdout Run the same launch command by hand in a terminal first, then inspect the wrapper script
No requests visible on the QCode side The request was not sent, or went to another address Check with your key at probe.qcode.cc, then recheck the Base URL

FAQ

Do I have to configure QCode separately in every editor?

No. You configure the agent itself (for example Claude Code); the editor only launches it. Once the agent is connected to QCode, ACP sessions in Zed, Devin Desktop and JetBrains use the same configuration.

How does ACP relate to LSP?

The idea is similar: LSP decouples editors from language servers, and ACP decouples editors from AI agents. An editor that speaks ACP can mount any agent that speaks ACP without a dedicated integration for each one.

How do I confirm that an editor started from the Dock received the environment variables?

Open an ACP session in the editor and send one message, then enter your key at probe.qcode.cc to see whether that request appears. If it does not, the variables did not reach the agent; put the configuration into the env block of ~/.claude/settings.json instead.

Can ACP sessions use GPT?

That depends on which agent you mount. Claude-family agents use the Anthropic interface only, with Claude and Chinese models. For GPT, mount a Codex-style agent and point its base_url at https://api.qcode.cc/openai as Codex expects. QCode does not currently offer Gemini models.

Which domain should I use in mainland China?

Replace api.qcode.cc with asia.qcode.cc (the Asia endpoint); the key stays the same. Switch back if it is unstable.

Get started with QCode

One API key for Claude Code, Codex and more — billed per token, per-model prices on qcode.cc/models

Enterprise →