> ## Documentation Index
> Fetch the complete documentation index at: https://docs.venice.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Xcode

> 在 Xcode 的 Intelligence 设置中将 Venice 添加为聊天提供商，即可在 macOS 上的 Xcode 编码助手中使用私密的 Venice 模型。

[Xcode](https://developer.apple.com/xcode/) 内置了一个编码助手，可以回答有关您项目的问题、编写和重构代码以及修复错误。除了内置的提供商之外，Xcode 还接受任何支持 Chat Completions API 的聊天提供商，因此您可以在 Xcode 的 Intelligence 设置中添加 Venice，并在编码助手对话中使用 Venice 模型。

> **编码助手**
>
> 使用 Venice 模型提问、生成代码和重构

> **直接连接**
>
> Xcode 从您的 Mac 直接向 Venice 发送请求

> **隐私选择**
>
> 根据代码需要选择相应隐私级别的模型

***

## 前置条件

* 来自 [venice.ai/settings/api](https://venice.ai/settings/api?utm_source=venice-api-documentation) 的 Venice API 密钥
* [Xcode](https://developer.apple.com/xcode/) 26.3 或更高版本（较早的 Xcode 26 版本在 Xcode 重新启动时可能会丢失自定义聊天提供商）
* macOS Tahoe 26 或更高版本（Xcode 27 需要 macOS Tahoe 26.6 或更高版本以及搭载 Apple 芯片的 Mac）

***

## 设置

**1. 获取您的 Venice API 密钥**

在 [venice.ai/settings/api](https://venice.ai/settings/api?utm_source=venice-api-documentation) 生成密钥。对于 Xcode，**Inference Only** 密钥即可满足需要。

建议创建一个设置了 **Epoch Consumption Limit** 的专用密钥，这样您可以限制 Xcode 的花费，并在不影响其他应用的情况下吊销该密钥。请参阅[生成 API 密钥](https://docs.venice.ai/zh/guides/getting-started/generating-api-key.md)。

**2. 打开 Intelligence 设置**

在 Xcode 中，选择 **Xcode > Settings**，然后在侧边栏中选择 **Intelligence**。

**3. 将 Venice 添加为聊天提供商**

在 **Chat** 下，点击 **Add a Chat Provider** 并选择 **Internet Hosted**。部分 Xcode 26 版本中该按钮名为 **Add a Model Provider**。

输入以下值，然后点击 **Add**：

| 字段 | 值 |
| - | - |
| URL | `https://api.venice.ai/api` |
| API Key | `Bearer your-venice-api-key` |
| API Key Header | `Authorization` |
| Description | `Venice` |

请完全按照所示填写 URL，不要包含 `/v1`，也不要带末尾斜杠。Xcode 会在其后追加 `/v1/models` 和 `/v1/chat/completions`，从而生成 `https://api.venice.ai/api/v1` 下的 Venice 标准 endpoint。

Xcode 会将 **API Key** 字段作为 `Authorization` 标头的完整值发送。请将 `your-venice-api-key` 替换为您的密钥，并保留 `Bearer ` 前缀。

**4. 选择您的模型**

在 **Chat** 下选择 Venice 提供商。Xcode 会从 Venice 获取模型列表。启用您想使用的模型，并为最常用的模型加星标，使其显示在模型菜单顶部。

该列表包含所有 Venice 文本模型，但编码助手只能使用支持工具调用的模型。选择之前请查看[模型要求](#模型要求)，或者先从 `z-ai-glm-5-3-flash` 开始。

**5. 开始对话**

打开一个项目，然后点击 **Coding Assistant** 按钮或按下 **Command-0**。点击 **New Conversation**，并在 **Chat** 下选择一个 Venice 模型。消息输入框中的占位文本会显示该对话所使用的模型。

发送一条简短的提示词以测试连接：

```txt theme={"system"}
Summarize what this project does in three bullet points.
```

***

## 验证设置

发送测试提示词才是真正的检验。Xcode 中显示完整的模型列表并不能证明您的密钥有效，因为无论密钥是否有效，Venice 的 `GET /models` endpoint 都会返回模型目录。Venice 只会在您发送消息时检查密钥。

如果提示词发送失败，请在 Xcode 之外验证您的 API 密钥：

```bash theme={"system"}
curl https://api.venice.ai/api/v1/api_keys/rate_limits \
  -H "Authorization: Bearer $VENICE_API_KEY"
```

该 endpoint 需要有效的密钥，因此如果这里返回 `401`，说明问题出在密钥上，而非 Xcode 的配置。如果密钥有效，请对照[故障排除](#故障排除)检查提供商设置。

***

## 模型要求

> [!WARNING]
>
> **模型必须支持工具调用。** 在聊天对话中，Xcode 会为模型提供用于搜索和编辑项目的工具，因此不支持工具调用的模型无法处理编码助手的请求。

[文本模型目录](https://docs.venice.ai/zh/models/text.md)将此能力列为 **Function Calling**，大多数 Venice 文本模型都支持该能力。

理想情况下，模型的上下文窗口还应达到 200K token 或以上。Xcode 没有为聊天提供商提供上下文窗口设置，而在开启 **Project Context** 时，请求除了包含 Xcode 的工具定义外，还可能包含大量项目代码。

列出同时满足这两项要求的 Venice 模型：

```bash theme={"system"}
curl -s https://api.venice.ai/api/v1/models \
  | jq -r '.data[] | select(.model_spec.capabilities.supportsFunctionCalling and .model_spec.availableContextTokens >= 200000) | .id'
```

***

## 选择模型

以下模型满足这两项要求：

| 使用场景 | 示例模型 ID |
| - | - |
| 编码 | `deepseek-v4-pro-0813` |
| 较低成本 | `z-ai-glm-5-3-flash` |
| 最困难的任务 | `grok-4-7` |
| 通过 **Upload files** 上传截图和设计稿 | `qwen-3-8-27b` |

比较其他模型时：

* [`GET /models/traits?type=text`](https://docs.venice.ai/zh/api-reference/endpoint/models/traits) 会返回 Venice 当前推荐的模型，例如用于编码的 `default_code`。
* **Project Context** 会使请求变得很大，因此输入 token 定价比平时更为重要。请在[文本模型目录](https://docs.venice.ai/zh/models/text.md)中比较价格。

Venice 会定期下线和替换模型。如果某个模型停止工作，请查看[弃用说明](https://docs.venice.ai/zh/overview/deprecations.md)并切换到当前可用的模型。

***

## 智能体

聊天提供商仅为聊天对话提供支持。Xcode 的内置智能体（例如 Claude Agent 和 Codex）以及您通过 Agent Client Protocol（ACP）添加的任何智能体都需要单独配置，并且不会通过聊天提供商发送请求。与聊天相比，智能体还能使用 Xcode 的更多能力，例如构建和测试您的应用。

要在 Venice 模型上运行可访问您 Xcode 项目的智能体，请为 Venice 配置一个终端智能体，并将其连接到 Xcode 26.3 及更高版本提供的 Model Context Protocol（MCP）服务器：

**1. 允许外部智能体**

在 Xcode 的 Intelligence 设置中，在 **Model Context Protocol** 下开启 **Allow external agents to use Xcode tools**。

**2. 使用 Venice 设置智能体**

请按照 [Codex CLI](https://docs.venice.ai/zh/guides/integrations/codex-cli.md) 或 [Claude Code](https://docs.venice.ai/zh/guides/integrations/claude-code.md) 指南操作。

**3. 将智能体连接到 Xcode**

在智能体中注册 Xcode 的 MCP 服务器：

```bash Codex CLI theme={"system"}
codex mcp add xcode -- xcrun mcpbridge
```

```bash Claude Code theme={"system"}
claude mcp add --transport stdio xcode -- xcrun mcpbridge
```

**4. 向智能体发送提示词**

先在 Xcode 中打开您的项目，然后在终端中向智能体发送提示词。智能体连接时，Xcode 会向您发出提醒。

***

## 隐私

Xcode 会从您的 Mac 直接向 Venice 发送聊天请求。聊天对话中默认开启 **Project Context**，因此 Xcode 会在每个请求中包含项目中的相关代码和其他上下文。要限制 Xcode 发送的内容，请在消息输入框中关闭 **Project Context**，并使用 `@` 显式引用文件和符号。

Venice 不会在其代理层存储或记录提示词和响应内容。您选择的模型决定了运行时的隐私级别：

* **Private** 模型使用零数据保留的基础设施。
* **Anonymized** 模型会向上游提供商隐藏您的身份，但该提供商可以处理您的代码。
* **TEE** 模型（模型 ID 以 `e2ee-` 开头）在硬件隔离区（enclave）内运行。Xcode 无法在您的 Mac 上加密提示词，因此从 Xcode 使用这些模型时，它们以 TEE 模式运行，而非端到端加密模式。

在发送专有代码之前，请在[文本模型目录](https://docs.venice.ai/zh/models/text.md)中查看每个模型的隐私标签，并阅读 [Venice 隐私](https://docs.venice.ai/zh/overview/privacy.md)。

***

## 故障排除

> **401 或身份验证错误**
>
> 确认 **API Key** 的值为 `Bearer ` 后接来自 [venice.ai/settings/api](https://venice.ai/settings/api?utm_source=venice-api-documentation) 的 Venice 密钥，且没有多余的空格。由于模型列表是公开的，即使密钥错误，Xcode 也能加载模型列表，因此身份验证错误只会在您发送消息时出现。请使用[验证设置](#验证设置)中的命令测试密钥。

> **Xcode 无法加载模型或拒绝该提供商**
>
> 检查 URL 是否完全为 `https://api.venice.ai/api`。以 `/v1` 结尾的 URL 会使 Xcode 请求 `/api/v1/v1/models`，而末尾斜杠会生成 `/api//v1/models`。对于这两种情况，Venice 都会返回 `404`。请使用更正后的 URL 重新添加提供商。

> **发送消息时出现 endpoint 错误**
>
> 检查对话所使用的模型是否支持工具调用，并且最好具有 200K token 或以上的上下文窗口。Xcode 会在每个请求中发送工具定义和项目上下文：不支持工具调用的模型无法处理它们，而大型项目可能会超出较小的上下文窗口。请启用满足[模型要求](#模型要求)的模型，然后用它开始新的对话。

> **402 或需要付款错误**
>
> Venice 在以下两种情况下返回 `402`：
>
> * 请求到达 Venice 时没有 `Authorization` 标头。Venice 会忽略其他标头（例如 `x-api-key`），并以 x402 付款质询作为响应。请将 **API Key Header** 设置为 `Authorization`。
> * 密钥已达到其花费限额，或您的余额已用完。请参阅[花费限额错误故障排除](https://docs.venice.ai/zh/guides/getting-started/generating-api-key.md#排查支出限额错误)。

> **找不到模型**
>
> Venice 可能已下线该模型。请查看[弃用说明](https://docs.venice.ai/zh/overview/deprecations.md)，从提供商的模型列表中选择一个当前可用的模型，然后开始新的对话。

***

## 资源

> **[设置编码智能](https://developer.apple.com/documentation/xcode/setting-up-coding-intelligence)**
>
> Apple 关于 Xcode 中智能体和聊天提供商的指南

> **[使用智能编写代码](https://developer.apple.com/documentation/xcode/writing-code-with-intelligence-in-xcode)**
>
> 使用编码助手、项目上下文和历史记录

> **[Venice 文本模型](https://docs.venice.ai/zh/models/text.md)**
>
> 浏览当前的模型 ID、能力和隐私级别

> **[生成 API 密钥](https://docs.venice.ai/zh/guides/getting-started/generating-api-key.md)**
>
> 创建带有花费限额的专用密钥


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.