OpenCode 环境变量配置涉及 API 密钥设置、优先级机制及性能参数调整。支持 OpenAI、Anthropic、Azure 等主流 AI 服务，通过环境变量或配置文件实现。需关注上下文窗口、推理能力优化及安全实践，避免密钥泄露与成本失控。
OpenCode 采用三级配置优先级机制，确保灵活性与安全性：
配置加载流程在 internal/config/config.go 中实现，系统会依次检查环境变量、用户主目录下的 .opencode.json 和项目根目录配置，最终合并生成运行时参数。这种设计既保证了全局设置的统一性，又允许项目级别的个性化配置。
| 变量名 | 用途 | 示例值 | 必须 |
|---|
| ANTHROPIC_API_KEY | Anthropic Claude 密钥 | sk-ant-xxxxx | 否 |
| OPENAI_API_KEY | OpenAI API 密钥 | sk-xxxxx | 否 |
| GEMINI_API_KEY | Google Gemini 密钥 | AIzaSyxxxxx | 否 |
| GROQ_API_KEY | Groq API 密钥 | gsk_xxxxx | 否 |
| OPENROUTER_API_KEY | OpenRouter API 密钥 | or_xxxxx | 否 |
| XAI_API_KEY | XAI API 密钥 | xai_xxxxx | 否 |
| AZURE_OPENAI_ENDPOINT | Azure API 端点 | https://xxx.openai.azure.com | 否 |
| OPENCODE_DEV_DEBUG | 调试模式开关 | true | 否 |
提示：所有 AI 提供商至少需要配置一个，系统会根据优先级自动选择可用的服务。优先级顺序在 internal/config/config.go#L288-386 中定义。
作为最常用的 AI 服务，OpenAI 配置只需两步：
export OPENAI_API_KEY="sk-你的密钥"
系统会自动应用 GPT-4o 模型，如需调整可修改配置文件中的 agents 设置：
{ "agents": { "coder": { "model": "gpt-4o", "maxTokens": 8192 } } }
Claude 系列模型以长文本处理见长，配置方式如下：
export ANTHROPIC_API_KEY="sk-ant-api03-你的密钥"
默认会使用 Claude 3.7 Sonnet 模型，该模型在代码生成场景下表现优异。配置后可在 internal/config/config.go#L309 查看详细参数。
对于国内用户，Azure OpenAI 是稳定选择：
export AZURE_OPENAI_ENDPOINT="https://你的资源名.openai.azure.com/"
export AZURE_OPENAI_API_KEY="你的密钥"
需要注意的是 Azure 还需要在配置文件中指定部署名称：
{ "providers": { "azure": { "apiKey": "你的密钥" } }, "agents": { "coder": { "model": "azure-gpt-4o" } } }
不同模型有不同的上下文窗口限制，合理设置可避免 token 超限错误：
{ "agents": { "coder": { "maxTokens": 8192 }, "summarizer": { "maxTokens": 4096 } } }
系统会自动检查 maxTokens 是否超过模型上下文窗口的一半，并在 internal/config/config.go#L552-563 中进行调整。建议设置为模型最大上下文的 40-50%，预留足够空间给响应内容。
OpenAI 模型支持推理能力调整，影响输出质量和速度：
{ "agents": { "coder": { "reasoningEffort": "high" } } }
可选值为 "low"、"medium"和"high"，在 internal/config/config.go#L566-593 中定义。代码复杂场景建议使用 "high"，简单任务可设为 "low" 以提高响应速度。
以下是一个兼顾开发效率和成本控制的配置模板：
{ "data": { "directory": "~/.opencode" }, "tui": { "theme": "dracula" }, "providers": { "anthropic": { "apiKey": "sk-ant-你的密钥" }, "openai": { "disabled": true } }, "agents": { "coder": { "model": "claude-3-70b-sonnet", "maxTokens": 10000, "reasoningEffort": "medium" }, "summarizer": { "model": "claude-3-70b-sonnet", "maxTokens": 4000 }, "task": { "model": "claude-3-70b-sonnet", "maxTokens": 2000 }, "title": { "model": "claude-3-70b-sonnet", "maxTokens": 80 } }, "contextPaths": [ ".github/copilot-instructions.md", "opencode.md" ], "autoCompact": true }
将以上内容保存为 ~/.opencode.json，即可实现 Claude 优先的配置方案，同时禁用 OpenAI 服务以避免误消费。
如果遇到 "API key is invalid" 错误，请按以下步骤排查：
echo $OPENAI_API_KEY # 应显示你的密钥
密钥验证逻辑在 internal/config/config.go#L622-628 中实现，系统会自动标记无 API 密钥的提供商为禁用状态。
当配置了不支持的模型时，系统会自动回退到默认值。查看支持的模型列表可参考：
// 支持的模型定义在 models 包中
// 示例：github.com/opencode-ai/opencode/internal/llm/models
常见的有效模型 ID 包括：gpt-4o、claude-3-70b-sonnet、gemini-1.5-pro 等。
通过 MCP（Model Control Protocol）服务器配置，可实现多模型协同工作：
{ "mcpServers": { "local-llm": { "type": "stdio", "command": "/path/to/llm/server", "args": ["--model", "qwen2-7b"] } }, "agents": { "coder": { "model": "local-qwen2-7b" } } }
MCP 服务器配置在 internal/config/config.go#L27-35 中定义，支持标准输入输出和 SSE 两种通信方式，为本地部署的大模型提供了集成方案。
定期备份配置文件可避免重装系统时重复配置：
# 备份配置
cp ~/.opencode.json ~/opencode-config-backup.json
# 迁移到新系统
scp user@old-system:~/opencode-config-backup.json ~/.opencode.json
配置文件采用 JSON 格式，可轻松编辑和版本控制。建议将常用配置提交到个人知识库，方便在不同设备间同步。
通过本文介绍的配置技巧，你已经掌握了 OpenCode 环境变量的全部要点。无论是个人开发者还是企业团队，合理的配置都能显著提升 AI 辅助开发的效率，同时控制成本和保障安全。
提示：完整的配置参数定义可在 internal/config/config.go 中查看，定期查看源码更新可获取最新的配置选项。
微信公众号「极客日志」，在微信中扫描左侧二维码关注。展示文案：极客日志 zeeklog
生成新的随机RSA私钥和公钥pem证书。 在线工具，RSA密钥对生成器在线工具，online
基于 Mermaid.js 实时预览流程图、时序图等图表，支持源码编辑与即时渲染。 在线工具，Mermaid 预览与可视化编辑在线工具，online
将字符串编码和解码为其 Base64 格式表示形式即可。 在线工具，Base64 字符串编码/解码在线工具，online
将字符串、文件或图像转换为其 Base64 表示形式。 在线工具，Base64 文件转换器在线工具，online
将 Markdown（GFM）转为 HTML 片段，浏览器内 marked 解析；与 HTML转Markdown 互为补充。 在线工具，Markdown转HTML在线工具，online
将 HTML 片段转为 GitHub Flavored Markdown，支持标题、列表、链接、代码块与表格等；浏览器内处理，可链接预填。 在线工具，HTML转Markdown在线工具，online