# ACP 接入总览

> **最后核实**：2026-09-18 · 📄 依据官方文档（[agentclientprotocol.com](https://agentclientprotocol.com) 当日查阅）

## 接入速览

| 项目 | 说明 |
|---|---|
| 可用模型 | 取决于挂载的 agent：Claude Agent / Claude Code 系 ✅（Anthropic 腿）· GPT ✅（Codex 类 agent）· 国产 ✅ · Gemini 视 agent 而定 |
| 协议与 Base URL | 配置在 **agent 本身**：Anthropic 腿 `https://api.qcode.cc/api`（Claude 系 agent） |
| 配置位置 | agent 的环境变量 / 自身配置文件；宿主只是启动它 |
| 官方文档 | [Agent Client Protocol](https://agentclientprotocol.com) |

**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 编辑器接入](/docs/ide/zed) |
| Devin Desktop（原 Windsurf） | 2026-06-02 起支持，Agent Command Center 内挂载 | [Devin Desktop 接入](/docs/ide/devin-desktop) |
| JetBrains 系 | 通过 ACP 插件接入 | [JetBrains IDE](/docs/ide/jetbrains) |
| Neovim / Emacs / Sublime / Qt Creator 等 | 官方编辑器名录在列 | — |

## 哪些 agent 会说 ACP

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

## 配置：一次配好，处处生效

### Claude Code（走 Anthropic 腿）

```bash
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` 块，效果相同。
> 详见 [环境变量配置](/docs/getting-started/environment)。

### Codex CLI（走 OpenAI Responses 腿）

Codex 用 TOML 配置，`base_url` 填到 `/openai` 为止。见 [Codex 完整教程](/docs/ide/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

```bash
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](https://probe.qcode.cc)，输入 API Key 即可确认请求是否真的到达。

## 相关文档

- [接入点与 API 格式](/docs/getting-started/endpoints-and-api-paths) — 协议 × 模型家族真源表
- [环境变量配置](/docs/getting-started/environment)
- [Zed 编辑器接入](/docs/ide/zed) · [Devin Desktop 接入](/docs/ide/devin-desktop) · [JetBrains IDE](/docs/ide/jetbrains)