OpenCode 配置指南

配置文件位置

主配置文件: ~/.config/opencode/opencode.json (供应商和模型配置)
认证文件: ~/.local/share/opencode/auth.json (API Key 存储)
全局提示词: ~/.config/opencode/AGENTS.md (全局行为规范)
项目提示词: <项目根目录>/AGENTS.md (项目特定规范)

快速配置步骤

1. 配置供应商

在 ~/.config/opencode/opencode.json 中添加供应商配置:

{ "$schema": "https://opencode.ai/config.json", "provider": { "供应商名称": { "options": { "baseURL": "https://api.供应商域名.com/v1" }, "models": {} } } }

参数说明:

供应商名称: 自定义供应商名称 (如 claude、openai、智谱 ai、xxx 中转站 `)
baseURL: API 服务的基础 URL

2. 配置 API Key

方式一：使用命令行 (推荐)

# 登录或更新某个供应商的 Key
opencode auth login

# 查看当前已配置的所有供应商和 Key 状态
opencode auth list

# 删除指定供应商的 Key
opencode auth logout <供应商名称>

方式二：手动编辑配置文件

在 ~/.local/share/opencode/auth.json 中添加对应供应商的 API Key:

{ "供应商名称": { "type": "api", "key": "你的API密钥" } }

注意: auth.json 中的供应商名称必须与 opencode.json 中的供应商名称完全一致。

3. 配置模型

在供应商下添加模型配置:

{ "provider": { "供应商名称": { "options": { "baseURL": "https://api.供应商域名.com/v1" }, "models": { "claude-sonnet-4-5-20250929": { "id": "claude-sonnet-4-5-20250929", "name": "Claude Sonnet 4.5", "cost": { "input": 3, "output": 15 }, "limit": { "context": 200000, "output": 64000 }, "reasoning": true, "temperature": true, "tool_call": true, "attachment": true } } } } }

模型参数说明:

参数	类型	说明
`id`	string	模型的唯一标识符，用于 API 调用
`name`	string	模型的显示名称
`cost.input`	number	输入 token 成本 (每百万 token 美元)
`cost.output`	number	输出 token 成本 (每百万 token 美元)
`limit.context`	number	最大上下文长度 (token 数)
`limit.output`	number	最大输出长度 (token 数)
`reasoning`	boolean	是否支持推理模式
`temperature`	boolean	是否支持温度参数调节
`tool_call`	boolean	是否支持函数 / 工具调用
`attachment`	boolean	是否支持文件附件

API Key 管理

优先级机制

OpenCode 选择 API Key 的优先级如下:

环境变量 (最高优先级)
- 例如: ANTHROPIC_API_KEY、OPENAI_API_KEY 或 OPENCODE_<供应商名称>_APIKEY
- 只要设置了环境变量，优先使用环境变量中的值
本地配置文件 (备选)
- 如果没有设置环境变量，才使用 ~/.local/share/opencode/auth.json 中的 Key
- 此时使用的是该供应商最后一次执行 auth login 时输入的 Key

覆盖机制

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

配置示例

完整配置示例

opencode.json:

{ "$schema": "https://opencode.ai/config.json", "provider": { "供应商1": { "options": { "baseURL": "https://api.供应商1域名.com/v1" }, "models": { "claude-sonnet-4-5-20250929": { "id": "claude-sonnet-4-5-20250929", "name": "Claude Sonnet 4.5", "cost": { "input": 3, "output": 15 }, "limit": { "context": 200000, "output": 64000 }, "reasoning": true, "temperature": true, "tool_call": true, "attachment": true } } }, "供应商2": { "options": { "baseURL": "https://api.供应商2域名.com/v1" }, "models": { "claude-haiku-4-5-20251001": { "id": "claude-haiku-4-5-20251001", "name": "Claude Haiku 4.5", "cost": { "input": 1, "output": 5 }, "limit": { "context": 200000, "output": 64000 }, "reasoning": true, "temperature": true, "tool_call": true, "attachment": true } } } } }

auth.json:

{ "供应商1": { "type": "api", "key": "你的API密钥1" }, "供应商2": { "type": "api", "key": "你的API密钥2" } }

安全建议

文件权限
- 设置 auth.json 为仅当前用户可读: chmod 600 ~/.local/share/opencode/auth.json
- 不要将 auth.json 提交到版本控制系统
环境隔离
- 开发环境和生产环境使用不同的 API Key
- 推荐使用环境变量或项目根目录下的 .env 文件管理 Key
- 确保 .env 已加入 .gitignore
Key 管理
- 定期轮换 API Key
- 使用具有适当权限限制的 API Key
- auth.json 目前为明文存储，请勿随意分享
备份
- 建议定期备份配置文件
- auth.json 备份时注意安全存储

提示词配置

OpenCode 支持通过 AGENTS.md 文件自定义 AI 助手的行为规范和工作流程。

提示词类型

OpenCode 提供两种级别的提示词配置:

全局提示词 - 对所有项目生效
项目提示词 - 仅对当前项目生效

提示词文件位置

类型	文件路径	作用范围
全局提示词	`~/.config/opencode/AGENTS.md`	所有项目
项目提示词	`<项目根目录>/AGENTS.md`	当前项目

优先级机制

当同时存在全局和项目提示词时:

项目提示词优先级更高，会覆盖全局提示词中的相同配置
两者会合并使用，项目提示词补充项目特定的规范

提示词内容示例

全局提示词 (~/.config/opencode/AGENTS.md):

# OpenCode 全局提示词 ## 核心原则 - 严谨工作态度，保证完美质量标准
- 直接输出代码或方案，禁止客套话
- 回复简洁明了，使用中文

## 代码规范 - 遵循项目现有代码风格
- 优先编写直观的线性逻辑
- 考虑边界条件和极端情况

## Git 工作流 - 仅在明确要求时提交
- 遵循约定式提交消息格式
- 提交前检查 git status 和 git diff

项目提示词 (<项目根目录>/AGENTS.md):

# 项目名称 - 项目特定提示词 ## 项目概述
这是一个 XXX 项目，使用 XXX 技术栈。

## 目录结构

project/
├── src/ # 源代码
├── tests/ # 测试文件
└── docs/ # 文档

 ## 项目规范 - 使用 TypeScript 严格模式
- 测试覆盖率要求 80% 以上
- 所有 API 必须有 JSDoc 注释

## 工作流程 1. 修改代码前先运行测试
2. 完成后运行 `npm run lint` 和 `npm test` 3. 提交信息格式: `<type>(<scope>): <subject>`

提示词配置建议

全局提示词
- 定义通用的代码规范和工作原则
- 设置统一的命名规范和注释风格
- 配置 Git 提交规范
项目提示词
- 说明项目的技术栈和架构
- 描述项目特定的目录结构
- 定义项目特有的工作流程和规范
- 列出项目常用的命令和工具
最佳实践
- 保持提示词简洁明确，避免冗长描述
- 使用 Markdown 格式，便于阅读和维护
- 定期更新提示词，与项目演进保持同步
- 将敏感信息（如密码、密钥）排除在提示词之外

如何创建提示词文件

创建全局提示词:

# 创建配置目录（如果不存在） mkdir -p ~/.config/opencode

# 创建全局提示词文件 touch ~/.config/opencode/AGENTS.md

# 编辑文件
vim ~/.config/opencode/AGENTS.md

创建项目提示词:

# 在项目根目录创建 cd /path/to/项目目录
touch AGENTS.md

# 编辑文件
vim AGENTS.md

# 建议将 AGENTS.md 加入版本控制
git add AGENTS.md
git commit -m "docs: add project-specific agent instructions"

提示词生效时机

全局提示词: OpenCode 启动时自动加载
项目提示词: 打开项目目录时自动加载
修改后: 需要重启 OpenCode 或重新打开项目才能生效

常见问题

如何添加新的 API 供应商？

在 opencode.json 中添加供应商配置 (baseURL 和 models)
在 auth.json 中添加对应的 API Key 或使用 opencode auth login
重启 OpenCode

如何切换不同的模型？

在 OpenCode 界面中按 Ctrl+P，选择 “Switch Model” 即可切换已配置的模型。

如何验证配置是否正确？

启动 OpenCode 后，尝试发送一条消息。如果配置正确，模型会正常响应。如果出错，检查:

供应商名称是否在两个文件中一致
API Key 是否正确
baseURL 是否可访问

支持哪些 API 供应商？

OpenCode 支持所有兼容 OpenAI API 格式的供应商，包括:

Anthropic Claude
OpenAI GPT
Azure OpenAI
智谱 AI
各类第三方 API 代理服务

环境变量和配置文件同时存在时使用哪个？

环境变量优先级更高。如果设置了环境变量 (如 ANTHROPIC_API_KEY)，OpenCode 会优先使用环境变量中的 Key，忽略 auth.json 中的配置。

标签配置指南下的文章

免费 1T s3存储