在 Xcode 中接入 Qoder、Claude、Codex 与 DeepSeek Harness

最近,我在 Xcode 27.2 里加了四个自定义 Agent:Qoder、Claude Agent、Codex Agent 和 DeepSeek Harness(DSH),现在都能正常工作。Claude Agent 与 Codex Agent 使用 DeepSeek 模型,DSH 则采用官方推荐的 ACP profile 插件形态。

真正花时间的地方不是点击 Xcode 的 Add an Agent,而是分清几条容易混淆的边界:Claude Agent 与 Claude 模型不是同一个概念,Codex 不能直接复用 Claude 的 Anthropic 兼容配置,DSH 的 ACP profile 与编辑器适配插件也各自承担不同职责。

我把这次接入整理成一篇配置记录。先说清 ACP 调用链,再分别给出安装、Xcode 表单和模型配置,最后统一验收与排查问题。

实测环境

下表记录的是这次实际使用的版本,其他版本我没有逐一验证。DSH 当前仍带有 RC 版本号,升级时尤其需要关注插件兼容性。

软件或依赖 本次版本
Xcode 27.2
Qoder CLI 1.1.95
@agentclientprotocol/claude-agent-acp ^0.109.1
@agentclientprotocol/codex-acp ^2.9.0
@deepseek-ai/dsh ^0.2.2-rc.5
Node.js 26.13.1
npm 11.20.0

Claude、Codex 和 DSH 都被我放在各自的项目目录内局部安装,不依赖 npm 全局命令。这样入口位置固定,依赖可以锁定,卸载时也不用清理全局 Node.js 环境。

Xcode 统一的是 ACP 入口,不是 Agent 内部配置

Xcode 可以作为 ACP Client,通过标准输入输出启动并驱动外部 Agent。ACP(Agent Client Protocol)在这里解决的问题是:编辑器如何创建会话、发送提示词,以及接收 Agent 的消息、工具调用和权限请求。

四种方案的调用链如下:

flowchart LR
  X[Xcode 27.2<br/>ACP Client] --> Q[qoder --acp]
  X --> C[claude-agent-acp]
  X --> CX[codex-acp]
  X --> D[dsh --profile acp]

  Q --> QS[Qoder 服务]
  C --> DS[DeepSeek 模型服务]
  CX --> DS
  D --> DS

Xcode 只统一了注册和启动方式。进入各自的调用链后,四份配置就不能互相替代了:

Agent Xcode 启动的程序 ACP 能力来自哪里 模型与认证配置
Qoder Qoder CLI CLI 原生 --acp 模式 Qoder 登录态或个人访问令牌
Claude Agent claude-agent-acp Claude Agent SDK 的 ACP 适配器 Anthropic 兼容端点与环境变量
Codex Agent codex-acp Codex App Server 的 ACP 适配器 Codex 配置文件与环境变量
DSH dsh --profile acp DSH ACP profile 与编辑器适配插件 DSH 凭据或环境变量

这里还要区分 ACP 与 MCP 的方向:本文讨论的是 Xcode 通过 ACP 调用 Agent;如果目标是让终端里的 Agent 操作 Xcode,则涉及 Xcode 对外提供工具的另一条链路。两条链路可以共存,但配置时不要混为一谈。

先记住 Xcode 表单的四个规则

打开 Xcode → Settings → Intelligence → Agents → Add an Agent…,可以看到 Name、Executable、Arguments、Interpreter 和 Environment Variables 等字段。Xcode 27.2 已经支持直接填写环境变量,因此不必再为了注入 API Key 编写包装脚本。

这张表单我反复用到了四次,有几个字段始终按下面的规则处理。

1. Executable 使用绝对路径

Xcode 启动 Agent 时不继承交互式 shell 的完整环境,也不要指望它展开 ~ 或按照 .zshrc 中的 PATH 查找命令。

在终端执行:

1
2
command -v node
command -v qoder

把输出的完整路径填入表单。本文示例目录为 ~/Desktop/explore,写入 Xcode 时则应展开为 /Users/<你的用户名>/Desktop/explore。

2. Arguments 每行填写一个参数

例如 DSH 的启动参数是两个独立值:

1
2
--profile
acp

不要把它们当成需要 shell 再解析的一整行命令。

3. 脚本需要 Interpreter,原生二进制不需要

npm 局部安装后,node_modules/.bin/ 下的入口通常是脚本。对这类入口,我采用下面的填法:

  • Executable 填脚本入口的绝对路径;
  • Interpreter 填 command -v node 得到的绝对路径。

Qoder 原生可执行文件则不需要 Interpreter。

4. 密钥不要进入文章、截图和命令行参数

下文所有密钥均使用 sk-你的DeepSeek-Key 占位。配置 Xcode 后,截图、录屏或共享配置前也要检查 Environment Variables 是否已经脱敏。

Qoder:直接启动 Qoder CLI 的 ACP 模式

Qoder 是这次接入最省事的一个:Qoder CLI 已提供 ACP 模式,不需要额外安装协议适配器。

安装并登录

按照 Qoder CLI 官方安装文档执行:

1
2
3
4
5
curl -fsSL https://qoder.com/install | bash

qoder --version
qoder login
command -v qoder

本次验证的版本为 1.1.95。qoder login 会打开浏览器完成认证,ACP 模式与 CLI 共享登录状态。

如果不使用共享登录态,也可以在 Xcode 的 Environment Variables 中配置 QODER_PERSONAL_ACCESS_TOKEN。已经完成 qoder login 时,不必重复添加。

填写 Xcode 表单

字段 配置
Name Qoder
Executable command -v qoder 输出的绝对路径
Arguments --acp
Interpreter 留空
Environment Variables 使用共享登录态时留空

添加后,首次启动按 Xcode 提示选择 Allow。打开编码助手,新建会话并选择 Qoder,即可开始使用。

如果 Agent 无法启动,优先在终端检查 qoder --version 和登录状态,不要先修改其他无关字段。

Claude Agent:通过 ACP 适配器使用 DeepSeek

这里最容易混淆的一点是:接入的是 Claude Agent 运行时,调用的模型却可以不是 Claude。

@agentclientprotocol/claude-agent-acp 使用 Claude Agent SDK 实现 ACP 服务。DeepSeek 提供 Anthropic 兼容端点,因此可以保留 Claude Agent 的工具体系,同时把模型请求发往 DeepSeek。

调用链为:

1
Xcode → claude-agent-acp → Claude Agent SDK → DeepSeek Anthropic 兼容端点

局部安装适配器

1
2
3
4
5
mkdir -p ~/Desktop/explore/claude-acp
cd ~/Desktop/explore/claude-acp

npm init -y
npm install @agentclientprotocol/claude-agent-acp

安装后的入口为:

1
~/Desktop/explore/claude-acp/node_modules/.bin/claude-agent-acp

本次 package.json 中记录的依赖范围为 ^0.109.1。如果希望完全复现实验环境,可以在安装命令后指定经验证的版本,并使用 lock 文件固定实际安装结果。

准备 DeepSeek 环境变量

DeepSeek API Key 可在 DeepSeek 开放平台 创建。需要配置四个变量:

1
2
3
4
5
6
7
8
9
# DeepSeek 的 Anthropic 兼容端点,注意末尾不带 /v1
ANTHROPIC_BASE_URL=https://api.deepseek.com/anthropic

# 在 DeepSeek 开放平台获取
ANTHROPIC_AUTH_TOKEN=sk-你的DeepSeek-Key

# 主模型与后台小任务模型
ANTHROPIC_MODEL=deepseek-flash
ANTHROPIC_SMALL_FAST_MODEL=deepseek-flash

配置时先核对 ANTHROPIC_BASE_URL。这里使用的是 Anthropic 兼容端点 https://api.deepseek.com/anthropic,不要再拼接 /v1。

ANTHROPIC_MODEL 决定主要任务的模型,ANTHROPIC_SMALL_FAST_MODEL 用于适合小快模型的后台任务。本次两者均设为 deepseek-flash。

填写 Xcode 表单

字段 配置
Name Claude Agent · DeepSeek
Executable /Users/<你的用户名>/Desktop/explore/claude-acp/node_modules/.bin/claude-agent-acp
Arguments 留空
Interpreter command -v node 输出的绝对路径
Environment Variables 添加上述四个变量

注意这里用的是 ANTHROPIC_AUTH_TOKEN。不要因为它同样以 ANTHROPIC_ 开头,就直接换成 ANTHROPIC_API_KEY;这次验证通过的是前者。

Codex Agent:第三方模型必须走 Responses 协议

Codex 的接入不能只复制 Claude 的环境变量。它通过 ~/.codex/config.toml 选择模型和 provider,并要求上游支持 Responses API。仅提供 Chat Completions 的端点,不能直接套用这份配置。

调用链为:

1
Xcode → codex-acp → Codex App Server → DeepSeek Responses 端点

局部安装适配器

1
2
3
4
5
mkdir -p ~/Desktop/explore/codex-acp
cd ~/Desktop/explore/codex-acp

npm init -y
npm install @agentclientprotocol/codex-acp

本次依赖范围为 ^2.9.0。该 npm 包包含兼容的 Codex 依赖,常规接入不需要再单独全局安装 Codex CLI。

入口路径为:

1
~/Desktop/explore/codex-acp/node_modules/.bin/codex-acp

创建 models.json,声明 DeepSeek 模型

Codex 不仅要知道模型名称,还需要模型目录中的元数据,例如上下文窗口、推理强度、工具调用格式和输入模态。

按照 DeepSeek 官方 Codex 接入文档,创建:

1
~/.codex/models.json

将官方文档给出的完整 JSON 写入该文件。当前文档同时包含 deepseek-flash 与 deepseek-v4-pro,其中 deepseek-flash 的输入模态包含图片。

我没有把整份模型目录搬进文章:内容较长,而且应随官方模型元数据同步更新,从二手教程复制残缺片段反而容易出错。需要理解这份文件时,先看下面几项信息就够了:

配置项 作用
slug 模型标识,例如 deepseek-flash
display_name 在模型选择界面显示的名称
input_modalities 声明模型是否支持图片等输入
推理与工具相关字段 让 Codex 按模型能力提供对应选项

编辑 config.toml,选择 provider

打开 ~/.codex/config.toml,写入或合并以下核心配置:

1
2
3
4
5
6
7
8
9
10
11
12
model = "deepseek-flash"
model_provider = "deepseek"
preferred_auth_method = "apikey"
forced_login_method = "api"
model_reasoning_effort = "high"
model_catalog_json = "~/.codex/models.json"

[model_providers.deepseek]
name = "DeepSeek"
base_url = "https://api.deepseek.com/"
env_key = "DEEPSEEK_API_KEY"
wire_api = "responses"

几个字段分别位于不同层面:

  • model:默认模型,本次为 deepseek-flash;
  • model_provider:引用下面的 [model_providers.deepseek];
  • model_catalog_json:指向上一步创建的模型目录;
  • base_url:DeepSeek API 地址,不要自行追加 /responses;
  • wire_api = "responses":明确使用 Responses 协议;
  • env_key:保存环境变量的名称,不是 API Key 本身。

DeepSeek 官方当前示例使用 experimental_bearer_token 直接保存 API Key。文章里没有沿用这个字段,而是改用 env_key,避免在 TOML 中明文记录密钥。如果配置是从官方一键脚本或示例复制的,应将原有的 experimental_bearer_token 替换为上述环境变量方式,不要同时保留两套认证配置。

models.json 与 config.toml 都属于 Codex 用户级配置,不是 codex-acp 安装目录中的文件,也不是 Xcode 内置 Codex Agent 的专属配置。

在 Xcode 中注入密钥并启动

Environment Variables 添加:

1
2
DEEPSEEK_API_KEY=sk-你的DeepSeek-Key
DEEPSEEK_MODEL=deepseek-flash

其中 DEEPSEEK_API_KEY 与 env_key 对应,密钥只由环境变量传入。DEEPSEEK_MODEL 可用于需要读取该变量的封装或运行环境,但当前这份 Codex 配置的模型来源仍是 config.toml 中的 model;切换模型时不能只改环境变量而忘记配置文件。

完整表单如下:

字段 配置
Name Codex · DeepSeek
Executable /Users/<你的用户名>/Desktop/explore/codex-acp/node_modules/.bin/codex-acp
Arguments 留空
Interpreter command -v node 输出的绝对路径
Environment Variables DEEPSEEK_API_KEY,按需添加 DEEPSEEK_MODEL

这样配置后,密钥不需要出现在 Codex 命令行参数中,也不需要明文写入 provider 配置。

DSH:为 ACP profile 安装编辑器适配插件

DSH 本身提供 acp profile,可以通过 stdio 为 ACP Client 服务,所以 Xcode 最终启动的是:

1
dsh --profile acp

只有这个 profile 还不够。DSH 核心 ACP profile 更偏向自动化 Client,本次因此采用推荐的插件形态,为 acp profile 安装 @openma/deepseek-harness-acp,补齐 Xcode 中需要的编辑器交互。

局部安装 DSH

1
2
3
4
5
mkdir -p ~/Desktop/explore/dsh
cd ~/Desktop/explore/dsh

npm init -y
npm install @deepseek-ai/dsh

本次依赖范围为 ^0.2.2-rc.5。DSH 与插件仍在演进,升级时最好同时确认运行时与插件的版本要求。

配置模型凭据

启动一次 Web UI:

1
./node_modules/.bin/dsh web

在 Settings → Models 中保存 DeepSeek API Key。已经通过 DSH 凭据机制保存密钥时,Xcode 中不必再次填写 DEEPSEEK_API_KEY。

如果当前环境选择通过进程环境变量提供密钥,也可以在 Xcode 表单中显式添加,两种方式按实际配置选一种即可。

为 acp profile 安装插件

1
./node_modules/.bin/dsh plugin --profile acp add @openma/deepseek-harness-acp@latest

这里插件的安装目标是 acp profile,不是普通项目目录,也不是 Web profile。适配插件负责把 DSH 的会话事件转换为编辑器需要的 ACP 表现,例如流式消息、工具调用、diff 和权限请求。

填写 Xcode 表单

字段 配置
Name DeepSeek Harness
Executable /Users/<你的用户名>/Desktop/explore/dsh/node_modules/.bin/dsh
Arguments 第一行 --profile,第二行 acp
Interpreter command -v node 输出的绝对路径
Environment Variables 使用已保存的 DSH 凭据时留空,否则按需添加 DEEPSEEK_API_KEY

如果 Agent 能启动但界面表现不完整,先检查插件是否安装到了正确的 profile,而不是急着修改模型端点。

四种方案放在一起看,差异只有三层

回头看这四份配置,真正需要记住的是三层:

对比项 Qoder Claude Agent Codex Agent DSH
启动层 qoder --acp claude-agent-acp codex-acp dsh --profile acp
协议层 CLI 原生 ACP Claude Agent SDK 外加 ACP 适配器 Codex App Server 外加 ACP 适配器 ACP profile 加编辑器插件
模型层 Qoder 自身配置 Anthropic 兼容端点 Responses 端点与 Codex provider DSH 模型与凭据配置
密钥来源 登录态或 Token Xcode 环境变量 Xcode 环境变量,由 env_key 引用 DSH 凭据或环境变量
局部 npm 入口需要 Node.js 通常不适用 需要 需要 需要

这个分层也决定了排错顺序:先确认进程能启动,再确认 ACP 会话能建立,最后确认模型请求和工具调用正常。

验收不要停在“能回复一句话”

只发一句“你好”并得到回复,还不足以说明这个 Agent 可以投入编码工作。我会继续检查下面几项:

  1. 进程启动:新建会话后 Agent 不立即退出;
  2. 模型响应:可以连续对话,流式输出没有明显中断;
  3. 工程读取:能够读取当前工程文件,并基于实际代码回答;
  4. 文件修改:能完成一次小范围修改,Xcode 能展示对应变更;
  5. 权限交互:需要授权时,Xcode 能显示权限请求并传递用户选择;
  6. Xcode 工具:按需验证一次构建或测试,确认 Agent 不只是通用聊天窗口;
  7. 模型路由:结合配置和 DeepSeek 平台用量记录,确认请求使用了预期模型。

验证修改能力时,建议选择一个可快速还原的小任务,并保留默认权限确认。不要为了让第一次测试“顺利”而直接放开全部文件和命令权限。

故障排查:沿着调用链逐层定位

Agent 添加后立即退出

依次检查:

  • Executable 是否为真实存在的绝对路径;
  • npm 脚本是否填写了 Node.js Interpreter;
  • Node.js 路径是否来自当前机器上的 command -v node;
  • Arguments 是否逐行填写;
  • 对应目录中的依赖是否完整安装。

ACP 进程在终端直接运行时可能等待 stdio 输入,这本身不是卡死。终端验证后按 Ctrl+C 退出即可。

Claude Agent 报认证或模型错误

重点检查:

  • ANTHROPIC_BASE_URL 是否为 https://api.deepseek.com/anthropic;
  • 地址末尾是否误加了 /v1;
  • 是否使用 ANTHROPIC_AUTH_TOKEN;
  • API Key 是否添加在当前 Agent 的 Environment Variables 中;
  • ANTHROPIC_MODEL 与 ANTHROPIC_SMALL_FAST_MODEL 是否为可用模型。

Codex 找不到模型、密钥或协议不兼容

重点检查:

  • ~/.codex/models.json 是否包含当前模型的完整元数据;
  • config.toml 中的 model 与模型目录里的 slug 是否一致;
  • model_provider 是否与 [model_providers.deepseek] 对应;
  • env_key 是否写成了 DEEPSEEK_API_KEY,而不是密钥本身;
  • 是否还残留其他 bearer token 配置,导致实际认证方式与预期不同;
  • 上游是否真正支持 Responses API。

另外,普通对话成功不代表所有 Xcode 工具都必然可用。遇到“能聊天、不能干活”时,应把模型连接问题与工具能力问题分开排查。

DSH 能启动,但缺少编辑器交互

重点检查:

  • Arguments 是否确实为 --profile 和 acp;
  • @openma/deepseek-harness-acp 是否安装到了 acp profile;
  • DSH 运行时与插件版本是否兼容;
  • 当前进程能否读取已保存的模型凭据。

结语

回到最初那张 Add an Agent 表单,它统一的是入口,不是 Agent 内部的模型协议和认证方式。四次配置填写的是同样的字段,背后却是四条不同的调用链。

如果只按使用场景来选,我会这样判断:

  • 想在 Xcode 中使用 Qoder,直接启动 Qoder CLI 的 ACP 模式;
  • 想使用 Claude Agent 的运行时与 DeepSeek 模型,选择 claude-agent-acp 和 Anthropic 兼容端点;
  • 想使用 Codex Agent,先确认模型端点支持 Responses,再处理 provider 和模型目录;
  • 想使用 DeepSeek Harness 的插件体系,采用 acp profile 并安装编辑器适配插件。

这次接入最值得留下的不是某一份表单截图,而是排错顺序:先跑通启动链路,再处理模型路由,最后验证 Xcode 工具能力。

参考资料

  1. Apple:Extending and customizing agents
  2. Qoder CLI:ACP
  3. Qoder CLI:安装文档
  4. agentclientprotocol/claude-agent-acp
  5. agentclientprotocol/codex-acp
  6. DeepSeek:Codex 接入指南
  7. DeepSeek Harness npm 包
  8. openma-ai/deepseek-harness-acp