OpenCode 配置指南：详解供应商、模型与 API Key 设置

背景

随着大语言模型与编码助手的深度融合，开发者越来越需要一套灵活、可控的工具来管理多个 AI 供应商和模型。OpenCode 作为一款开源编码智能体，允许用户自定义 AI 助手的供应源、模型参数和行为规范。然而，其配置流程涉及供应商、 API 密钥、模型参数、提示词等多个维度，操作不当容易造成配置错误或安全隐患。LINUX DO 社区分享的《OpenCode 配置指南》为开发者提供了一份完整、可操作的配置说明书，帮助用户快速上手并规避常见问题。

核心内容

OpenCode 的配置体系由三个主要文件构成：

• 主配置文件 ~/.config/opencode/opencode.json：存储供应商和模型配置。
• 认证文件 ~/.local/share/opencode/auth.json：存储 API Key。
• 提示词文件：全局提示词位于 ~/.config/opencode/AGENTS.md，项目提示词位于 <项目根目录>/AGENTS.md。

快速配置步骤

1. 配置供应商
   在 opencode.json 的 provider 对象中添加供应商条目，需指定 baseURL（例如 https://api.供应商域名.com/v1）和空模型列表。供应商名称可自定义，如 claude、openai、智谱ai、xxx中转站。

2. 配置 API Key

   • 推荐方式：使用命令行 opencode auth login 登录或更新某个供应商的 Key；opencode auth list 查看所有已配置供应商和 Key 状态；opencode auth logout <供应商名称> 删除指定供应商的 Key。
   • 手动方式：在 auth.json 中添加 { "供应商名称": { "type": "api", "key": "你的API密钥" } }。注意 auth.json 中的供应商名称必须与 opencode.json 中的完全一致。

3. 配置模型
   在供应商下的 models 对象中为每个模型添加详细参数，包括：

   • id：模型的唯一标识符（用于 API 调用）。
   • name：显示名称。
   • cost.input / cost.output：每百万 token 的输入/输出成本（美元）。
   • limit.context / limit.output：最大上下文长度和输出长度（token 数）。
   • reasoning：是否支持推理模式。
   • temperature：是否支持温度参数调节。
   • tool_call：是否支持函数/工具调用。
   • attachment：是否支持文件附件。

API Key 管理

OpenCode 的 API Key 选择遵循优先级机制：

• 环境变量（最高优先级）：如 ANTHROPIC_API_KEY、OPENAI_API_KEY 或 OPENCODE_<供应商名称>_APIKEY。只要设置了环境变量，就优先使用。
• 本地配置文件（备选）：当未设置环境变量时，使用 auth.json 中的 Key（即最后一次 auth login 时输入的值）。

多次对同一供应商执行 auth login，后一次会覆盖前一次。环境变量始终优先于配置文件。

提示词配置

OpenCode 支持通过 AGENTS.md 文件自定义 AI 助手的行为规范：

• 全局提示词（~/.config/opencode/AGENTS.md）：对所有项目生效，适合定义通用代码规范、风格、Git 提交规则等。
• 项目提示词（<项目根目录>/AGENTS.md）：仅对当前项目生效，适合说明技术栈、目录结构、测试要求等。
• 当两者同时存在时，项目提示词优先级更高，会覆盖全局提示词中的相同配置，且两者会合并生效。

安全建议

• 将 auth.json 权限设置为仅当前用户可读：chmod 600 ~/.local/share/opencode/auth.json。
• 勿将 auth.json 提交到版本控制系统；推荐使用环境变量或项目 .env 文件管理 Key，并确保 .env 已加入 .gitignore。
• 定期轮换 API Key，使用具有适当权限限制的 Key。
• 建议定期备份配置文件，备份时注意安全存储。

常见问题

• 添加新供应商：在 opencode.json 中添加供应商和模型，在 auth.json 中添加对应 Key 或运行 auth login，然后重启 OpenCode。
• 切换模型：在 OpenCode 界面按 Ctrl+P，选择 “Switch Model”。
• 验证配置：发送一条消息，若响应正常则配置正确。若出错，检查供应商名称前后是否一致、API Key 是否正确、baseURL 是否可访问。
• 支持的供应商：所有兼容 OpenAI API 格式的供应商，包括 Anthropic Claude、OpenAI GPT、Azure OpenAI、智谱 AI 等。
• 环境变量与配置文件并存：环境变量优先级更高，忽略 auth.json 中对应 Key。

关键要点

• OpenCode 的配置分为三个独立文件：主配置文件、认证文件、提示词文件，各有明确分工。
• 供应商名称必须在 opencode.json 和 auth.json 中完全一致，否则无法匹配。
• API Key 优先级：环境变量 > 配置文件，且多次 auth login 会覆盖前一次 Key。
• 模型配置包含成本、上下文限制、功能开关（推理、温度、工具调用、附件），这些参数直接影响调用行为和计费。
• 提示词分全局和项目两级，项目提示词覆盖全局提示词中的相同设置，两者合并生效。
• 修改提示词后需重启 OpenCode 或重新打开项目才能生效。
• 安全方面强调文件权限、版本控制排除、环境隔离和定期轮换 Key。

意义与影响

该指南解决了一个实际痛点：当开发者需要同时接入多个 AI 供应商（如 Anthropic、OpenAI、智谱 AI）并为其配置不同模型时，OpenCode 提供了一种统一、可编程的配置框架。通过明确定义配置文件的格式、API Key 的优先级机制以及提示词的分层体系，用户既能享受多供应商带来的灵活性和成本优化，又能确保敏感信息的安全管理。特别是提示词的分层设计，使得团队可以在全局统一规范的基础上，为每个项目定制专属的 AI 行为，这有利于提升编码助手在复杂项目中的协作效率。整体而言，该指南不仅是一份操作手册，更展现了现代 AI 编码工具迈向工程化、可维护配置的趋势。