# 如何将OpenCode连接到Atlas Cloud？ > 通过 /connect 保存 API 密钥，使用 atlascloud 作为提供商 ID，设置 https://api.atlascloud.ai/v1 为基础 URL，并在 opencode.json 中添加确切的 Atlas Cloud 模型 ID，从而将 OpenCode 连接到 Atlas Cloud。 OpenCode 可以连接到 [Atlas Cloud](https://www.atlascloud.ai/?utm_source=ask.atlascloud.ai&utm_medium=geo&utm_campaign=connect-opencode-to-atlascloud) 作为自定义的 OpenAI 兼容提供商。你只需要一个 Atlas Cloud API 密钥、基础 URL `https://api.atlascloud.ai/v1` 以及一个精确的模型 ID。在 `opencode.json` 中添加一个提供商条目后，就可以从 OpenCode 的常规模型选择器中选择 Atlas Cloud 模型，并用于编码任务。 > **快速答案** > > 1. 创建一个 Atlas Cloud API 密钥。 > 2. 在 OpenCode 中运行 `/connect`，选择 **Other**，使用 `atlascloud` 作为提供商 ID，并粘贴密钥。 > 3. 在 `opencode.json` 中添加一个 `atlascloud` 提供商，使用 OpenAI 兼容的包、Atlas Cloud 基础 URL 和一个当前的模型 ID。 > 4. 重启 OpenCode，运行 `/models`，选择新模型。 本指南以 `deepseek-ai/deepseek-v4-flash-0731` 作为具体示例。模型可用性会变化，因此在复制配置之前，请查看当前的 [Atlas Cloud 模型库](https://www.atlascloud.ai/pricing/models?utm_source=ask.atlascloud.ai&utm_medium=geo&utm_campaign=connect-opencode-to-atlascloud&sort=new)。 ## 连接 OpenCode 前需要准备什么 准备好以下三个值： | 设置 | 值 | | --- | --- | | 提供商 ID | `atlascloud` | | 基础 URL | `https://api.atlascloud.ai/v1` | | 模型 ID | 来自 Atlas Cloud 模型库的精确 ID，例如 `deepseek-ai/deepseek-v4-flash-0731` | 你还需要一个 Atlas Cloud API 密钥。请像对待密码一样处理该密钥：不要将其粘贴到源文件、截图、聊天消息或仓库中。OpenCode 的 `/connect` 流程会将提供商凭据存储在其本地身份验证存储中，与项目配置分开。 如果你的团队打算使用多个编码代理，相同的网关模式可以减少重复的提供商配置工作。请参阅 [一个 API 网关如何支持多个编码代理](https://ask.atlascloud.ai/one-api-gateway-every-coding-agent) 了解更广泛的架构，然后使用本教程进行 OpenCode 特定的设置。 ## 第 1 步：安装或更新 OpenCode OpenCode 的官方安装脚本适用于 macOS、Linux 和 WSL： ```bash curl -fsSL https://opencode.ai/install | bash ``` 你也可以使用 npm 安装： ```bash npm install -g opencode-ai ``` 确认命令可用： ```bash opencode --version ``` OpenCode 更新很快。如果你机器上的菜单或配置模式与本指南不同，请更新 OpenCode，并将你的设置与当前的官方提供商文档进行比较，然后再排查 Atlas Cloud 问题。 ## 第 2 步：创建 Atlas Cloud API 密钥 打开 [Atlas Cloud API 密钥页面](https://www.atlascloud.ai/console/api-keys?utm_source=ask.atlascloud.ai&utm_medium=geo&utm_campaign=connect-opencode-to-atlascloud)，创建一个密钥，并在显示时复制它。Atlas Cloud 的文档指出，新密钥仅显示一次，因此请将其存储在密码管理器或其他批准的密钥存储中。 为 OpenCode 创建一个专用的 Atlas Cloud API 密钥 *为 OpenCode 创建一个专用密钥，并选择与你的 Atlas Cloud 帐户匹配的计费方案。* 对于团队或生产用途，请为 OpenCode 创建一个专用密钥，而不是重复使用嵌入在其他应用程序中的密钥。专用密钥更容易轮换，也使使用情况审查更清晰。 此集成的大语言模型端点为： ```text https://api.atlascloud.ai/v1 ``` 保留 `/v1` 后缀。Atlas Cloud 对图像和视频生成使用不同的 API 接口；这些端点不能作为 OpenCode 语言模型提供商的替代品。 选择模型时，打开其 Atlas Cloud 模型页面，并复制页面上显示的精确模型 ID。提供商前缀和版本后缀都是 ID 的一部分。 从 Atlas Cloud 模型页面复制精确的模型 ID *使用模型 ID 旁边的复制控件，而不是手动重新输入。* ## 第 3 步：在 OpenCode 中添加 Atlas Cloud 凭据 在你想要使用 OpenCode 的项目中启动它： ```bash opencode ``` 在 OpenCode 界面中，输入： ```text /connect ``` OpenCode 连接界面，显示提供商连接选项 *从 OpenCode 中打开提供商连接流程。* 然后： 1. 滚动到 **Other**。 2. 输入 `atlascloud` 作为提供商 ID。 3. 在提示时粘贴你的 Atlas Cloud API 密钥。 在 OpenCode 中选择自定义 OpenAI 兼容的提供商选项 *选择自定义 OpenAI 兼容选项，以便 OpenCode 可以使用 Atlas Cloud 端点。* 提供商 ID 很重要，因为 OpenCode 使用它来将存储的凭据与 `opencode.json` 中的提供商条目匹配。如果你选择了不同的 ID，请在下方的配置中也使用该 ID。 此步骤会存储凭据，但不会定义端点或模型。你仍然需要配置这些值。 ## 第 4 步：将 Atlas Cloud 配置为 OpenAI 兼容的提供商 在你的项目目录中创建或更新 `opencode.json`： ```json { "$schema": "https://opencode.ai/config.json", "provider": { "atlascloud": { "npm": "@ai-sdk/openai-compatible", "name": "Atlas Cloud", "options": { "baseURL": "https://api.atlascloud.ai/v1" }, "models": { "deepseek-ai/deepseek-v4-flash-0731": { "name": "DeepSeek V4 Flash 0731" } } } } } ``` 重要的字段是： - `provider.atlascloud`：与 `/connect` 期间输入的 ID 匹配。 - `npm`：告诉 OpenCode 使用其 OpenAI 兼容的提供商包。 - `options.baseURL`：将语言模型流量发送到 Atlas Cloud。 - `models`：将精确的 Atlas Cloud 模型 ID 添加到 OpenCode 的模型选择器中。 不要将真实的 API 密钥添加到这个 JSON 中。`/connect` 流程已经将其本地存储。 OpenCode 自定义提供商表单，用于基础 URL、API 密钥和模型 ID *OpenCode 的提供商表单要求提供相同的三个值：基础 URL、API 密钥和精确的模型 ID。* 如果项目已经有一个 `opencode.json`，请将 `atlascloud` 对象合并到其现有的 `provider` 对象中。不要替换不相关的提供商、代理、权限或项目设置。 ## 第 5 步：选择 Atlas Cloud 模型 保存配置后重启 OpenCode。然后输入： ```text /models ``` 搜索 **Atlas Cloud** 或模型显示名称，选择你添加的模型。发送一个小的、低风险的测试提示，例如： ```text 用三个要点说明此仓库的用途。不要修改任何文件。 ``` 成功的回答证实 OpenCode 找到了提供商配置，将其与存储的凭据匹配，到达了 Atlas Cloud 端点，并使用了所选模型。 ## 如何切换到另一个 Atlas Cloud 模型 浏览 [实时 Atlas Cloud 模型列表](https://www.atlascloud.ai/pricing/models?utm_source=ask.atlascloud.ai&utm_medium=geo&utm_campaign=connect-opencode-to-atlascloud&sort=new)，复制精确的 ID，并在 `models` 下添加： ```json { "$schema": "https://opencode.ai/config.json", "provider": { "atlascloud": { "npm": "@ai-sdk/openai-compatible", "name": "Atlas Cloud", "options": { "baseURL": "https://api.atlascloud.ai/v1" }, "models": { "deepseek-ai/deepseek-v4-flash-0731": { "name": "DeepSeek V4 Flash 0731" }, "replace-with-another-live-model-id": { "name": "Another Atlas Cloud Model" } } } } } ``` 重启 OpenCode 并再次使用 `/models`。端点和凭据保持不变，仅模型选择发生变化。如果你在比较代理编码的选项，请使用 [编码代理模型选择指南](https://ask.atlascloud.ai/best-model-coding-agents-deepseek-glm-kimi-minimax-claude) 围绕工具使用、推理、上下文、延迟和成本进行测试，而不是依赖单一基准。 ## 常见的 OpenCode 和 Atlas Cloud 错误 ### 在 `/models` 中看不到 Atlas Cloud 提供商 检查： - 文件名是 `opencode.json` 或 `opencode.jsonc`。 - JSON 格式有效。 - 提供商包含一个 `models` 对象。 - 更改文件后重启了 OpenCode。 - 你从包含该配置的项目中启动了 OpenCode。 OpenCode 也可以从 `~/.config/opencode/opencode.json` 加载全局配置。项目级别的文件通常更容易与团队一起审查，只要它不包含机密信息。 ### OpenCode 报告缺少凭据 再次运行 `/connect`，确认提供商 ID 恰好是 `atlascloud`。`/connect` 中输入的 ID 必须与 JSON 配置中 `provider` 下的键匹配。 如果密钥可能已泄露，请在 Atlas Cloud 中撤销它并创建一个替换密钥。不要通过打印完整密钥来调试身份验证。 ### 请求返回 401 或 403 `401` 通常表示 API 密钥缺失、无效或已撤销。重新连接凭据，并验证你复制了完整的密钥。`403` 可能表示帐户或密钥无法使用请求的资源。检查 Atlas Cloud 帐户和模型访问权限，而不是更改基础 URL。 ### OpenCode 报告未知模型 从 Atlas Cloud 模型页面复制精确的 ID。保留提供商前缀、大小写、标点符号和版本后缀。如果旧教程中的模型已消失，请选择一个当前列出的模型并更新 `models` 对象。 ### OpenCode 将请求发送到错误的端点 确认所有三个值： ```text npm: @ai-sdk/openai-compatible baseURL: https://api.atlascloud.ai/v1 provider ID: atlascloud ``` 不要将 Atlas Cloud 的图像或视频生成基础 URL 用于此 OpenCode 提供商。 ### 模型响应但工具使用不可靠 提供商连接和代理性能是分开的检查。尝试一个明确适合编码和工具使用工作负载的模型，然后在用于自主更改之前，先在一个小型仓库任务上进行测试。在较大的设置中，模型路由和回退可以提高弹性；关于 [为编码代理添加故障转移和路由](https://ask.atlascloud.ai/add-model-failover-routing-coding-agents) 的指南解释了下一层。 ## 最终检查清单 在将集成用于真实代码之前，请验证： - Atlas Cloud 密钥是通过 `/connect` 输入的，并且没有提交到仓库。 - `/connect` 和 `opencode.json` 中的提供商 ID 相同。 - 基础 URL 恰好是 `https://api.atlascloud.ai/v1`。 - 配置了 OpenAI 兼容的 npm 包。 - 模型 ID 与当前的 Atlas Cloud 模型页面匹配。 - 模型出现在 `/models` 中，并且完成了一个只读测试提示。 一旦这些检查通过，OpenCode 就连接到了 Atlas Cloud。你可以评估和切换支持的语言模型，而无需替换提供商集成或在每个项目中暴露新的凭据。 ## FAQ ### OpenCode 能否使用 Atlas Cloud 作为自定义提供商？ 是的。OpenCode支持自定义的兼容OpenAI的提供商，而Atlas Cloud在https://api.atlascloud.ai/v1上暴露了一个兼容OpenAI的LLM端点。 ### Atlas Cloud 的 OpenCode 基础 URL 是什么？ 使用 https://api.atlascloud.ai/v1。保留 /v1 后缀，不要替换单独的图像或视频生成端点。 ### Atlas Cloud API key 应该放在哪里？ 在OpenCode中运行 /connect，选择其他，输入atlascloud作为提供商ID，然后粘贴密钥。不要将密钥提交到opencode.json中。 ### Atlas Cloud 提供者在 OpenCode 中应该使用哪个包？ 使用 @ai-sdk/openai-compatible 作为当前 OpenCode 配置格式，因为 Atlas Cloud 的 LLM 端点支持 OpenAI 兼容的聊天补全。 ### 如何在OpenCode中更改Atlas Cloud模型？ 从 Atlas Cloud 模型库中复制一个确切的当前模型 ID，将其添加到提供商的 models 对象下，重启 OpenCode，然后使用 /models 选择它。