在 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 | command -v node |
把输出的完整路径填入表单。本文示例目录为 ~/Desktop/explore,写入 Xcode 时则应展开为 /Users/<你的用户名>/Desktop/explore。
2. Arguments 每行填写一个参数
例如 DSH 的启动参数是两个独立值:
1 | --profile |
不要把它们当成需要 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 | curl -fsSL https://qoder.com/install | bash |
本次验证的版本为 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 | mkdir -p ~/Desktop/explore/claude-acp |
安装后的入口为:
1 | ~/Desktop/explore/claude-acp/node_modules/.bin/claude-agent-acp |
本次 package.json 中记录的依赖范围为 ^0.109.1。如果希望完全复现实验环境,可以在安装命令后指定经验证的版本,并使用 lock 文件固定实际安装结果。
准备 DeepSeek 环境变量
DeepSeek API Key 可在 DeepSeek 开放平台 创建。需要配置四个变量:
1 | # DeepSeek 的 Anthropic 兼容端点,注意末尾不带 /v1 |
配置时先核对 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 | mkdir -p ~/Desktop/explore/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 | model = "deepseek-flash" |
几个字段分别位于不同层面:
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 | DEEPSEEK_API_KEY=sk-你的DeepSeek-Key |
其中 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 | mkdir -p ~/Desktop/explore/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 可以投入编码工作。我会继续检查下面几项:
- 进程启动:新建会话后 Agent 不立即退出;
- 模型响应:可以连续对话,流式输出没有明显中断;
- 工程读取:能够读取当前工程文件,并基于实际代码回答;
- 文件修改:能完成一次小范围修改,Xcode 能展示对应变更;
- 权限交互:需要授权时,Xcode 能显示权限请求并传递用户选择;
- Xcode 工具:按需验证一次构建或测试,确认 Agent 不只是通用聊天窗口;
- 模型路由:结合配置和 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是否安装到了acpprofile;- DSH 运行时与插件版本是否兼容;
- 当前进程能否读取已保存的模型凭据。
结语
回到最初那张 Add an Agent 表单,它统一的是入口,不是 Agent 内部的模型协议和认证方式。四次配置填写的是同样的字段,背后却是四条不同的调用链。
如果只按使用场景来选,我会这样判断:
- 想在 Xcode 中使用 Qoder,直接启动 Qoder CLI 的 ACP 模式;
- 想使用 Claude Agent 的运行时与 DeepSeek 模型,选择
claude-agent-acp和 Anthropic 兼容端点; - 想使用 Codex Agent,先确认模型端点支持 Responses,再处理 provider 和模型目录;
- 想使用 DeepSeek Harness 的插件体系,采用
acpprofile 并安装编辑器适配插件。
这次接入最值得留下的不是某一份表单截图,而是排错顺序:先跑通启动链路,再处理模型路由,最后验证 Xcode 工具能力。