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
Need an API key? Sign up →Endpoints & base URLs →
On This Page
- At a glance
- Hosts that speak ACP
- Agents that speak ACP
- Setup: configure once, works everywhere
- 🔴 A common trap: GUI-launched editors do not see your shell environment
- Verifying that traffic reaches QCode
- How ACP starts the agent: why environment variables are "inherited"
- Key settings explained
- Common errors and how to troubleshoot
- FAQ
- Related
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_TOKENare 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
envblock of~/.claude/settings.jsonfor 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:
- Launch the editor from a terminal (e.g.
zed .) so it inherits the current shell environment - Put the configuration in the agent's own config file rather than a shell profile
(Claude Code: the
envblock 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_URLset 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
echogreetings 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.
Related¶
- Endpoints & API Paths — protocol × model-family table
- Environment Variables
- Zed Setup · Devin Desktop Setup · JetBrains IDEs
Get started with QCode
One API key for Claude Code, Codex and more — billed per token, per-model prices on qcode.cc/models