# 在 Xcode 26 的 Intelligence 设置里把 Router One 加为聊天 provider

> https://router.one/zh/integrations/xcode 的 Markdown 镜像，供 AI 助手与爬虫使用。Router One 是 OpenAI 兼容的统一 LLM API 网关。
> 最后更新：2026-09-15

Xcode 26 内置了编程助手：在会话侧栏里向 agent 或聊天模型提问，让它解释、生成和修复代码，项目上下文由 Xcode 自动收集。除了内置的 ChatGPT 和 Claude 账号登录，Intelligence 设置还接受任何支持 Chat Completions API 的 provider，所以 Router One 只需加一次，作为 Internet Hosted 聊天 provider：它的 /v1/models 列表会把 GPT、Claude、Gemini、Grok 和 DeepSeek 系列填进 Xcode 的模型选择器，一把 Key 全覆盖，每次提问都在 Dashboard → Logs 留下成本和延迟 Trace。本指南讲清对话框需要的两个值、为什么地址是不带 /v1 的主机根地址、如何在 New Conversation 里选模型，以及 Xcode 每轮重发对话记录和附件时一段对话会花多少。Xcode 26.3 起加入的 agent（Claude Agent 和 Codex，26.6 起还有 Gemini）各自登录账号，不在本指南范围内。

## 确认 Xcode 版本，并为这台 Mac 单独建 Key

编程智能功能内置在 Xcode 26 里。Apple 按版本给出 macOS 要求：Xcode 26 到 26.3 要求 macOS Sequoia 15.6 或更新版本，Xcode 26.4 到 26.6 要求 macOS Tahoe 26.2 或更新版本。26.3 的发布说明修复了自定义模型 provider 在 Xcode 重启后消失的问题，能升级就用 26.3 或更新版本。然后为这台 Mac 单独创建一把设了 maxSpend 的 Router One Key，它只填进 Add a Chat Provider 对话框。SDK 和多数客户端用的带 /v1 的 base URL 不要拿来填 Xcode：这个对话框要的是主机根地址，下文说明。受管理的 Mac 上，如果 MDM 配置把 CodingAssistantAllowExternalIntegrations 设为 false，编程助手会整个关闭，也就加不了任何 provider。

## 把 Xcode 配置到 Router One base URL

选择 Xcode > Settings，在侧栏选 Intelligence，点 Chat 下方的 Add a Chat Provider。对话框里选 Internet Hosted；Locally Hosted 是给运行在你 Mac 上的模型服务用的，填的是端口和可选的描述，不是 URL。URL 填不带 /v1 的主机根地址 https://api.router.one：Apple 文档把 provider 必须提供的两个端点写成 {Model provider URL}/v1/models 和 {Model provider URL}/v1/chat/completions，也就是说 Xcode 会在你填的地址后面自己拼上 /v1/models 和 /v1/chat/completions，OpenAI 兼容 SDK 用的带 /v1 的 base URL 会让这一段重复出现。Key 那一行填为这台 Mac 创建的 Router One Key：Apple 文档对对话框其余内容只写了「the URL and other details」，WWDC25 的 What's new in Xcode 26 讲到接入其他 provider 时说的是「enter your API key」；网关按 Authorization: Bearer 校验这把 Key。点 Add。Xcode 通过 GET /v1/models 拉取模型列表，Router One 的这个端点需要 Key；选择器里显示的就是它返回的目录 ID，例如 anthropic/claude-sonnet-5 或 openai/gpt-5.5，你可以选择显示哪些模型并标记常用。使用时点 Coding Assistant 按钮或按 Command-0，点 New Conversation，在 Chat 下选这个 ID；消息输入框的占位文字会显示当前模型。之后每次提交的提问都会以这个 ID 发到 POST /v1/chat/completions：

`xcode-intelligence-settings`

```text
# Xcode → Settings → Intelligence → Chat → Add a Chat Provider
# Select Internet Hosted (Locally Hosted asks for a port on your Mac instead)
URL:      https://api.router.one
API key:  sk-your-router-one-key
# Xcode itself requests {URL}/v1/models and {URL}/v1/chat/completions
# Coding Assistant (Command-0) → New Conversation → Chat: <exact-model-id-from-/models>
```

## 每个值填在哪里，怎么验证

来自 Router One 的值只有两个，其余都是 Xcode 自己的行为；最后两行说明这个地址不负责配置什么：

| Xcode 字段 | 填什么 | 怎么验证 |
| --- | --- | --- |
| Intelligence → Chat → Add a Chat Provider | Internet Hosted | Locally Hosted 要的是你 Mac 上的端口和可选描述，不是 URL；Router One 通过互联网访问 |
| URL | https://api.router.one | 点 Add 后选择器出现模型；地址以 /v1 结尾会让 Xcode 请求 /v1/v1/models，网关返回 404 not_found |
| API key（对话框里的「other details」） | 为这台 Mac 单独创建、设了 maxSpend 的 Router One Key | 第一次提问出现在 Dashboard → Logs 里这把 Key 名下；Key 错误时是 401 invalid api key，选择器为空 |
| New Conversation → Chat（模型选择器） | /v1/models 返回的精确目录 ID，例如 anthropic/claude-sonnet-5 | Logs 里每条 Trace 的模型与 /models 逐字一致；选择器列出的每个 ID 都在 /v1/chat/completions 上提供服务 |
| Project Context、@ 引用、附件 | Xcode 默认设置；聊天模型的 Project Context 默认开启 | 上下文随 Chat Completions 请求一起发送：Logs 里的输入 tokens 随对话记录和附件增长 |
| Agents（Claude Agent、Codex、Gemini） | 不由这个地址配置 | Apple 文档写的是 Get / Install、Account 行登录和各 agent 自己的配置文件夹，没有 URL 字段；本指南只覆盖 Chat 部分 |

## 给一台 Mac 的对话定预算，并逐条核对

在会话里提交的每个提问至少是一个 POST /v1/chat/completions，源代码编辑器里的 coding tools 操作也一样：Explain、Document、Generate a Playground、Generate a Preview 和 Generate Fix for Issue 都发给当前聊天模型。Apple 的发布说明还提到编程助手使用的工具，例如「find text in file」；Xcode 用到这些工具时，模型的每一次往返都是又一个请求，有各自的 request_id 和费用。Chat Completions 不在服务端保存对话状态，Apple 也说明新消息会保留之前问答的上下文，所以每一轮都会重发对话记录，连同 Xcode 收集的项目上下文和你附加的文件；长对话的输入 tokens 一轮比一轮多，Logs 里某一行比上一行贵时先查这一点。Stop 按钮在 Xcode 侧结束回复：网关在回复完成前看到连接关闭，Trace 会记为 HTTP 499 client_cancelled，只按上游报告的用量计费；已经完成的回复照全额计费，而且 Apple 的 Xcode 26 说明列出了一个已知问题：状态栏的 Cancel 按钮有时不能停止正在执行的消息。给这台 Mac 单独一把设了 maxSpend 的 Key：失控的对话会在上限处收到 HTTP 402 停下，钱包和其他 Key 不受影响。按时间、模型和 request_id 对账；对话太长时新开一个会话来重置记录，不要一直续。Router One 只记录模型调用；应用改动、修改历史、Git 快照和 Xcode 的工具都在 Xcode 里运行。

## Xcode 该填哪个模型 ID？

从 /models 页复制精确的模型 ID，保留大小写、连字符和版本后缀，不要用展示名称代替。打开该模型的详情页，核对支持的 API 端点、上下文窗口和工具调用等能力，再与 Xcode 当前选择的 provider 和功能对应。模型出现在目录里，不等于当前客户端能调用它的所有功能。建议为每个工具单独建 API Key，并设置 maxSpend 消费上限。

## Xcode 用的是哪种 API 协议？

OpenAI 兼容描述的是接口格式，不能据此推断 Chat Completions（/v1/chat/completions）、Responses（/v1/responses）和 Anthropic Messages（/v1/messages）可以互换。先核对工具当前版本、provider 配置和实际请求路径，再查模型详情与 API 兼容性事实页。一次普通对话成功，也不能证明服务端工具、历史状态或文件编辑功能都受支持。

## 在 trace 里验证 Xcode 的调用

先在 Xcode 发出一次简单文本请求，再到 Dashboard → Logs 按时间、模型和 request_id 核对 trace：tokens、花费、延迟和状态码。成功后再分别验证流式输出、工具调用和多轮历史。失败时保留实际请求路径、完整错误消息及 request_id；没有对应日志时，先查客户端配置和网络，不能仅凭客户端报错认定是网关或上游故障。

## 常见问题

### provider 加好了，但模型选择器里没有 Router One 的模型，哪里出了问题？

先查 URL。Apple 文档把 Xcode 期望的端点写成 {Model provider URL}/v1/models 和 {Model provider URL}/v1/chat/completions，所以 URL 字段只放主机根地址 https://api.router.one。填成 https://api.router.one/v1，Xcode 会去请求 https://api.router.one/v1/v1/models，网关返回 HTTP 404 not_found，消息里直接写明你的客户端会自己在 base URL 后拼 /v1/...，请去掉末尾的 /v1；选择器自然没有东西可显示。删掉 /v1，保存后重试。URL 正确但选择器仍为空，说明 Key 被拒绝：GET /v1/models 需要有效的 Key，Key 错误时返回 401 invalid api key 并附 request_id。另外注意版本：Xcode 26.3 修复了自定义模型 provider 在重启后消失的问题，昨天还在、今天不见了的 provider 是升级的理由。模型出现后，发一个简短提问，到 Dashboard → Logs 按时间、模型和 request_id 核对。

### 能让 Xcode 通过 Anthropic Messages 端点调用 Claude 系列模型吗？

不能。Apple 写明加入的 provider「needs to support the Chat Completions API」，并且只列了 /v1/models 和 /v1/chat/completions 两个端点，所以 Xcode 里的自定义聊天 provider 都只讲 Chat Completions，没有切换到 Anthropic Messages 格式的设置；Chat 下的 Claude Sonnet & Opus 是 Apple 自己的账号登录，不是自定义 provider。在 Router One 上这不损失什么：/v1/chat/completions 服务目录里的所有聊天模型，保持同一个主机根地址，在模型选择器里选一个 Claude 系列 ID（例如 anthropic/claude-sonnet-5）即可，Logs 里的 Trace 会带这个 ID。网关的 /v1/messages 端点是给自己发送 Anthropic Messages 请求的客户端用的，例如 Claude Code；/v1/responses 只对已列出的 GPT 系列和 DeepSeek ID 原生提供。这两个端点都不能从 Xcode 的对话框里选择。

### Router One 这个 provider 需要 macOS 26 或 Apple silicon 的 Mac 吗？

Apple 的要求按 Xcode 版本给出，与 provider 无关：Xcode 26 到 26.3 要求 macOS Sequoia 15.6 或更新版本，Xcode 26.4 到 26.6 要求 macOS Tahoe 26.2 或更新版本，所以只有较新的 26.x 版本才需要 macOS 26。Xcode 26 发布说明只在一种情况下提到 Apple silicon，就是下载并在本机运行本地模型；「Coding intelligence features in Xcode require Apple Intelligence」则列在已解决问题里。Router One 这样的 Internet Hosted provider 在 Apple 的描述里不带这两个条件。网关这一侧在任何 Mac 上都一样：主机根地址、Key 和目录 ID 不变。

### Xcode 能通过网关用哪些模型？

选用当前目录中同时支持 Xcode 所用端点和所需功能的模型。精确 ID、当前单价与能力以 /models 及模型详情为准；不要仅按 GPT、Claude 等系列名判断兼容性。客户端能列出模型，只证明模型发现成功，仍需验证实际调用。

### 能列出模型，但调用报 400 或 404，怎么办？

先记录实际请求路径和错误消息，再核对精确模型 ID。400 可能是参数、工具类型或模型与端点不匹配；404 可能是请求路径或资源不存在，不能直接判定模型下线。若错误提示 must be called via，按它指明的端点调整客户端 provider，或换用支持当前端点的模型。不要在所有工具里统一增删 /v1 或 /chat/completions。

### 中国大陆能直连吗？

能。网关在大陆可直连、无需 VPN，配置与全球环境完全一致。

### 报 401/402/403/429 怎么排查？

先到 Dashboard → Logs 核对请求及错误消息。401 查 Key 是否传入和有效；402 查钱包余额与 maxSpend；403 查 Key 权限和访问限制；429 查请求频率、token 限额及上游限流，按错误来源处理。保留 request_id，再按错误码速查页逐项排查。

## 相关页面

- 全部接入指南：https://router.one/zh/integrations
- Xcode 的 API 错误排查：https://router.one/zh/llm-api-error-codes
- API 兼容性：端点与功能对照：https://router.one/zh/facts/api-compatibility.md
- Responses API 配置与限制：https://router.one/zh/codex-responses-api
- Qwen Code 接入：https://router.one/zh/integrations/qwen-code
- Google ADK 接入：https://router.one/zh/integrations/google-adk
- 所有编程工具走同一个网关：https://router.one/zh/use-cases/ai-coding-tools
- 连接与 /v1 路径排查：https://router.one/zh/api-connection-troubleshooting
- 按 Key 追踪模型调用成本：https://router.one/zh/llm-cost-tracking
- Xcode 官方文档：Setting up coding intelligence：https://developer.apple.com/documentation/xcode/setting-up-coding-intelligence
- Xcode 官方文档：Writing code with intelligence in Xcode：https://developer.apple.com/documentation/xcode/writing-code-with-intelligence-in-xcode
- Xcode 官方文档：Xcode 26 Release Notes：https://developer.apple.com/documentation/xcode-release-notes/xcode-26-release-notes
- 网关层负责什么：https://router.one/zh/llm-api-gateway
- OpenAI 兼容 API：https://router.one/zh/openai-compatible-api
- API 文档：https://router.one/zh/docs
- 本页规范地址：https://router.one/zh/integrations/xcode
- 模型与每模型 token 价格：https://router.one/zh/models （markdown：https://router.one/zh/models.md ）
- 定价：https://router.one/zh/pricing
- API 文档（markdown）：https://router.one/zh/docs.md
- 公司事实（markdown）：https://router.one/zh/facts/company.md