OpenCode: OpenCode配置文件
最后更新：2026-08-31
OpenCode 通过 opencode.json 配置文件管理所有设置，包括模型、代理、工具、主题等。
1. 你将学到
- 配置文件的位置与优先级
- opencode.json 完整结构
- 常用配置项详解
- 环境变量配置
2. 配置文件位置
OpenCode 按以下优先级加载配置（后者覆盖前者）：
| 优先级 | 路径 | 作用范围 |
|---|---|---|
| 1 | ~/.config/opencode/opencode.json |
全局配置 |
| 2 | <project>/.opencode/opencode.json |
项目配置 |
| 3 | 环境变量 | 运行时覆盖 |
3. 完整配置结构
JSON
{
"$schema": "https://opencode.ai/config.json",
"provider": {},
"model": {},
"agent": {},
"tools": {},
"permission": {},
"theme": {},
"tui": {}
}
(1) provider（提供商配置）
配置自定义模型提供商：
JSON
{
"provider": {
"my-provider": {
"name": "My Custom Provider",
"baseURL": "https://api.example.com/v1",
"apiKey": "sk-xxx"
}
}
}
(2) model（模型配置）
设置默认使用的模型：
JSON
{
"model": {
"default": "anthropic/claude-sonnet-4-20250514"
}
}
(3) agent（代理配置）
配置自定义代理（详见第 13 课）：
JSON
{
"agent": {
"build": {
"mode": "primary",
"model": "anthropic/claude-sonnet-4-20250514"
}
}
}
(4) tools（工具配置）
全局工具开关：
JSON
{
"tools": {
"write": true,
"edit": true,
"bash": true
}
}
(5) permission（权限配置）
细粒度权限控制：
JSON
{
"permission": {
"edit": "ask",
"bash": {
"*": "ask",
"git status *": "allow",
"grep *": "allow"
}
}
}
权限值说明：
| 值 | 说明 |
|---|---|
allow |
直接允许 |
ask |
需要用户确认 |
deny |
直接拒绝 |
(6) tui（TUI 配置）
终端界面设置：
JSON
{
"tui": {
"scroll_speed": 3,
"scroll_acceleration": {
"enabled": true
}
}
}
4. AGENTS.md（项目规则）
AGENTS.md 是 OpenCode 的项目级规则文件，放置在项目根目录，用于定义 AI 的行为约束。
(1) 创建方式
在 TUI 中输入：
TEXT
📖 仅展示
/init
或手动创建 AGENTS.md 文件。
(2) 内容示例
MARKDOWN
# Project Rules
- Always use TypeScript for new files
- Follow ESLint configuration
- Write unit tests for all new functions
- Use conventional commits format
(3) 作用范围
- AI 在当前项目中会自动读取并遵循 AGENTS.md 的规则
- 不影响其他项目
- 可与 opencode.json 配合使用
5. 环境变量
| 变量 | 类型 | 作用 |
|---|---|---|
OPENCODE_AUTO_SHARE |
boolean | 自动分享会话 |
OPENCODE_CONFIG |
string | 自定义配置路径 |
OPENCODE_TUI_CONFIG |
string | TUI 配置路径 |
OPENCODE_DISABLE_AUTOUPDATE |
boolean | 禁用自动更新 |
OPENCODE_SERVER_PASSWORD |
string | API 服务认证密码 |
OPENCODE_MODELS_URL |
string | 自定义模型源 |
实验性环境变量
| 变量 | 类型 | 作用 |
|---|---|---|
OPENCODE_EXPERIMENTAL |
boolean | 启用全部实验功能 |
OPENCODE_EXPERIMENTAL_LSP_TOOL |
boolean | LSP 工具 |
OPENCODE_EXPERIMENTAL_PLAN_MODE |
boolean | 规划模式 |
OPENCODE_EXPERIMENTAL_FILEWATCHER |
boolean | 文件监听 |
❓ 常见问题
Q 全局配置和项目配置冲突时以谁为准？
A 项目配置优先。OpenCode 按优先级加载，后者覆盖前者，确保项目级设置能覆盖全局默认值。
Q AGENTS.md 和 opencode.json 有什么区别？
A AGENTS.md 用自然语言描述规则，AI 会读取并遵循；opencode.json 用结构化 JSON 定义配置，OpenCode 程序读取执行。两者互补，不冲突。
Q Alice 的团队有 10 个项目，每个项目配置都不同，怎么管理？
A 全局配置设置通用默认值，每个项目目录下的 .opencode/opencode.json 设置项目特定配置。这样 Alice 只需维护一份全局配置 + 各项目的差异配置。
📖 小节
- 配置文件按优先级加载：全局 < 项目 < 环境变量
- opencode.json 是核心配置，涵盖模型、代理、工具、权限
- AGENTS.md 用自然语言定义项目规则
- 环境变量适合临时覆盖和 CI/CD 场景
📝 作业
-
基础题：创建全局 opencode.json，配置你常用的模型提供商。
-
进阶题：为你的项目创建 .opencode/opencode.json，设置项目级的工具权限。
-
挑战题：编写一份 AGENTS.md，定义你项目的编码规范和 AI 行为约束，然后让 OpenCode 遵循它执行一个任务。
