OpenCode 环境变量配置与 AI 密钥管理指南

Anthropic Claude 配置

Claude 系列模型以长文本处理见长，配置方式如下：

export ANTHROPIC_API_KEY="sk-ant-api03-你的密钥"

默认会使用 Claude 3.7 Sonnet 模型，该模型在代码生成场景下表现优异。

国内可用方案：Azure OpenAI

对于国内用户，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 是否超过模型上下文窗口的一半。建议设置为模型最大上下文的 40-50%，预留足够空间给响应内容。

推理能力配置

OpenAI 模型支持推理能力调整，影响输出质量和速度：

{ "agents": { "coder": { "reasoningEffort": "high" } } }

可选值为 "low"、"medium" 和 "high"。代码复杂场景建议使用 "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 密钥无效

如果遇到 "API key is invalid" 错误，请按以下步骤排查：

1. 验证密钥是否正确复制，特别注意前后是否有空格
2. 检查密钥是否过期或被吊销
3. 确认环境变量是否正确设置：

echo $OPENAI_API_KEY # 应显示你的密钥

系统会自动标记无 API 密钥的提供商为禁用状态。

模型不支持

当配置了不支持的模型时，系统会自动回退到默认值。常见的有效模型 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 服务器配置支持标准输入输出和 SSE 两种通信方式，为本地部署的大模型提供了集成方案。

配置备份与迁移

定期备份配置文件可避免重装系统时重复配置：

# 备份配置
cp ~/.opencode.json ~/opencode-config-backup.json
# 迁移到新系统
scp user@old-system:~/opencode-config-backup.json ~/.opencode.json

配置文件采用 JSON 格式，可轻松编辑和版本控制。建议将常用配置提交到个人知识库，方便在不同设备间同步。

总结与最佳实践

1. 安全第一：避免在代码仓库中提交包含 API 密钥的配置文件
2. 分层配置：全局配置通用参数，项目配置特定需求
3. 定期轮换：API 密钥应定期更新，特别是团队共享环境
4. 监控用量：关注各 AI 提供商的使用量统计，避免意外支出
5. 本地优先：开发环境优先使用本地模型，降低 API 调用成本

合理的配置都能显著提升 AI 辅助开发的效率，同时控制成本和保障安全。