ACP 接入总览

Agent Client Protocol:一份配置在 Zed / Devin Desktop / JetBrains 等宿主里通用——把 Claude Code 当 ACP agent 跑,环境变量指向 QCode

更新于 2026-10-15

需要 API Key? 前往注册 →端点与 Base URL →

本页目录

最后核实:2026-10-15 · 📄 依据官方文档(agentclientprotocol.com 当日查阅)

接入速览

项目 说明
可用模型 取决于挂载的 agent:Claude Agent / Claude Code 系 ✅(Anthropic 接口)· GPT ✅(Codex 类 agent)· 国产 ✅ · Gemini:QCode 暂不提供
协议与 Base URL 配置在 agent 本身:Anthropic 接口 https://api.qcode.cc/api(Claude 系 agent)
配置位置 agent 的环境变量 / 自身配置文件;宿主只是启动它
官方文档 Agent Client Protocol

Agent Client Protocol(ACP) 是一个开放标准,让编辑器与 AI agent 解耦通信——类似 LSP 之于语言服务器。编辑器只要会说 ACP,就能挂载任何会说 ACP 的 agent,不必为每个 agent 单独做集成。

对 QCode 用户来说,这带来一个很实际的结论:

🔑 你只需要把 agent 本身(例如 Claude Code CLI)接好 QCode,宿主编辑器就自动跟着走。 ACP 宿主是以子进程方式启动 agent 的,agent 会继承你的环境变量。 所以 ANTHROPIC_BASE_URL / ANTHROPIC_AUTH_TOKEN 配好之后,Zed、Devin Desktop、 JetBrains 里的会话走的都是 QCode,不需要在每个编辑器里重复配一遍。

哪些宿主支持 ACP

宿主 说明 本站文档
Zed 原生支持,agent panel 内直接开会话 Zed 编辑器接入
Devin Desktop(原 Windsurf) 2026-06-02 起支持,Agent Command Center 内挂载 Devin Desktop 接入
JetBrains 系 通过 ACP 插件接入 JetBrains IDE
Neovim / Emacs / Sublime / Qt Creator 等 官方编辑器名录在列 —

哪些 agent 会说 ACP

常见者包括 Claude Agent(官方名录里的名字,即 Claude Agent SDK 的 ACP 封装 claude-agent-acp)、OpenCode 等;完整名录见 agentclientprotocol.com。任何自己实现了 ACP 的 agent 都可以被挂载。 不同宿主自带的 adapter 与启动命令不一样,具体命令以宿主文档为准。

配置:一次配好,处处生效

Claude Code(走 Anthropic 接口)

export ANTHROPIC_BASE_URL="https://api.qcode.cc/api"
export ANTHROPIC_AUTH_TOKEN="cr_你的QCode密钥"

写进 ~/.zshrc / ~/.bashrc 持久化。中国大陆把域名换成 https://asia.qcode.cc/api。

也可以写进 ~/.claude/settings.json 的 env 块,效果相同。 详见 环境变量配置。

Codex CLI(走 OpenAI Responses 接口)

Codex 用 TOML 配置,base_url 填到 /openai 为止。见 Codex 完整教程。

🔴 一个容易踩的坑:GUI 启动的编辑器读不到 shell 环境变量

macOS / Linux 上从 Dock、启动器或桌面图标启动的编辑器,不会读取 ~/.zshrc。 结果是:终端里 claude 能连 QCode,编辑器里的 ACP 会话却报鉴权失败。

两种处理方式:

  1. 从终端启动编辑器(例如 zed .),继承当前 shell 的环境
  2. 把配置写进 agent 自己的配置文件而不是 shell profile (Claude Code 用 ~/.claude/settings.json 的 env 块)

第 2 种更稳,因为它不依赖启动方式。

验证走没走到 QCode

KEY="cr_你的QCode密钥"
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 = 路径与密钥都通(缺请求体属预期);401 = 密钥有问题

端点侧确认无误后,在宿主里开一次会话;如仍失败,问题在宿主如何启动 agent(多半是上面那个环境变量坑),不在 QCode。

所有经 QCode 的请求都会上报到 probe.qcode.cc,输入 API Key 即可确认请求是否真的到达。

ACP 的启动方式:为什么环境变量能「继承」

截至 2026-10-15,据 ACP 官方的传输层说明:ACP 用 JSON-RPC 编码消息,推荐的 stdio 传输下,客户端(编辑器)把 agent 作为子进程启动,agent 从标准输入读取 JSON-RPC 消息、向标准输出写消息,消息以换行分隔;agent 可以把日志写到标准错误(stderr)。协议还规定 agent 不得向 stdout 写任何不是合法 ACP 消息的内容。

这对排查有两个直接的结论:

  • 子进程默认继承启动它的编辑器的环境,所以配在 shell 里的 ANTHROPIC_BASE_URL 能否生效,取决于编辑器自己是怎么被启动的(见上文 GUI 启动的坑)。
  • 如果你给 agent 套了自己的包装脚本,脚本里不要用 echo 往 stdout 打印欢迎语或调试信息,否则会被当成非法消息;需要输出时写到 stderr。

关键配置项说明

配置 用途 说明
ANTHROPIC_BASE_URL Claude 系 agent 的接入地址 填 https://api.qcode.cc/api,不带 /v1,末尾不带斜杠
ANTHROPIC_AUTH_TOKEN QCode 密钥 cr_ 开头,以 Authorization: Bearer 头发出
~/.claude/settings.json 的 env 块 把上面两项写进 agent 自己的配置 不依赖编辑器怎么启动,最稳
Codex 的 base_url Codex 类 agent 的接入地址 填到 /openai 为止,见 Codex 完整教程
宿主里的 agent 启动命令 告诉编辑器怎么拉起 agent 因宿主而异,以宿主文档为准

常见报错与排查

现象 常见原因 处理
终端里 claude 正常,编辑器里 ACP 会话报鉴权失败 编辑器从 Dock 或启动器启动,没读到 shell 环境变量 从终端启动编辑器,或把配置写进 ~/.claude/settings.json 的 env
401 / Invalid API key 密钥错、带空格,或环境里有旧的 ANTHROPIC_API_KEY 抢了认证 env \| grep -i anthropic 查残留变量
404 Base URL 多了 /v1 或末尾带斜杠 改回 https://api.qcode.cc/api
model_not_available_on_endpoint Claude 系 agent 里选了 GPT 型号,或 Codex 类 agent 里选了 Claude 型号 Claude 走 Anthropic 接口,GPT 走 OpenAI Responses,见 接入点与 API 格式
会话一直卡在「启动中」或立即断开 agent 没能作为子进程正常启动,或包装脚本往 stdout 打印了内容 先在终端里手动运行同一条启动命令;再查包装脚本
QCode 一侧查不到请求 请求没有发出,或发往了别的地址 到 probe.qcode.cc 输入 Key 核对,再回查 Base URL

常见问题

我要在每个编辑器里都配一遍 QCode 吗?

不用。配的是 agent 本身(例如 Claude Code),编辑器只负责启动它。agent 接好 QCode 之后,Zed、Devin Desktop、JetBrains 里的 ACP 会话用的是同一份配置。

ACP 和 LSP 有什么关系?

思路类似:LSP 让编辑器与语言服务器解耦,ACP 让编辑器与 AI agent 解耦。编辑器会说 ACP,就能挂载任何会说 ACP 的 agent,不必为每个 agent 单独做集成。

怎么确认从 Dock 启动的编辑器拿到了环境变量?

在编辑器里开一次 ACP 会话并发一句话,然后到 probe.qcode.cc 输入 Key 看有没有这次请求。没有,说明环境变量没传到 agent,改把配置写进 ~/.claude/settings.json 的 env 块。

ACP 会话能用 GPT 吗?

取决于你挂载的是哪种 agent。Claude 系 agent 只能走 Anthropic 接口,用 Claude 与国产模型;要用 GPT,请挂载 Codex 类 agent,并按 Codex 的方式把 base_url 指向 https://api.qcode.cc/openai。QCode 暂不提供 Gemini 模型。

中国大陆应该填哪个域名?

把 api.qcode.cc 换成 asia.qcode.cc(亚洲接入点),Key 不变;不稳定时再换回来。

相关文档

开始使用 QCode

一把 API Key 同时用于 Claude Code、Codex 等工具;按 token 计费,各模型单价见 qcode.cc/models

企业团队版 →