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 中的配置。

快速配置步骤

1. 配置供应商

2. 配置 API Key

3. 配置模型

API Key 管理

优先级机制

覆盖机制

配置示例

完整配置示例

安全建议

提示词配置

提示词类型

提示词文件位置

优先级机制

提示词内容示例

提示词配置建议

如何创建提示词文件

提示词生效时机

常见问题

如何添加新的 API 供应商?

如何切换不同的模型?

如何验证配置是否正确?

支持哪些 API 供应商?

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

更多帮助

发送评论 编辑评论

推荐文章

发送评论编辑评论