配置详解

OpenCode 使用 JSON/JSONC 格式的配置文件，支持 JSON Schema 验证和 IDE 自动补全。本文档详细介绍配置文件的结构和各选项的含义。

配置文件位置

OpenCode 支持多级配置，按优先级从低到高：

优先级	位置	说明
1	远程配置	组织级默认配置（`.well-known/opencode`）
2	全局配置	`~/.config/opencode/opencode.json`
3	自定义配置	`OPENCODE_CONFIG` 环境变量指定
4	项目配置	项目根目录 `opencode.json`
5	`.opencode` 目录	代理、命令、插件配置
6	内联配置	`OPENCODE_CONFIG_CONTENT` 环境变量

配置合并规则：后加载的配置与先加载的配置深度合并，相同字段会被覆盖。

基本配置结构

json

{
  "$schema": "https://opencode.ai/config.json",
  "model": "anthropic/claude-sonnet-4-5",
  "small_model": "anthropic/claude-haiku-4-5",
  "theme": "opencode",
  "default_agent": "build",
  "provider": { ... },
  "agent": { ... },
  "tools": { ... },
  "mcp": { ... },
  "lsp": { ... },
  "permission": "ask"
}

核心配置选项

模型配置

json

{
  "model": "anthropic/claude-sonnet-4-5",
  "small_model": "anthropic/claude-haiku-4-5"
}

选项	说明
`model`	主要 LLM 模型，用于复杂任务
`small_model`	轻量级模型，用于简单任务和快速响应

主题配置

json

{
  "theme": "opencode"
}

默认代理

json

{
  "default_agent": "build"
}

可选值："build" 或 "plan"

权限配置

json

{
  "permission": "ask"
}

值	说明
`"allow"`	允许所有工具调用
`"ask"`	每次工具调用前询问确认
`"deny"`	拒绝所有工具调用

工具配置

启用或禁用特定工具：

json

{
  "tools": {
    "write": true,
    "edit": true,
    "bash": true,
    "fetch": false,
    "mcp-server-name*": false
  }
}

支持通配符匹配 MCP 工具："mcp-*": false 禁用所有 MCP 工具。

完整配置示例

以下是一个包含 MCP 服务、LSP 配置、多代理和多 Provider 的推荐完整配置：

json

{
    "$schema": "https://opencode.ai/config.json",
    "mcp": {
        "context7": {
            "type": "local",
            "command": [
                "pnpx",
                "@upstash/context7-mcp"
            ],
            "enabled": true
        },
        "grep_app": {
            "type": "local",
            "command": [
                "pnpx",
                "grep-mcp",
                "--transport",
                "stdio"
            ],
            "enabled": true
        },
        "websearch_exa": {
            "type": "local",
            "command": [
                "pnpx",
                "exa-mcp-server",
                "tools=web_search_exa"
            ],
            "enabled": true
        }
    },
    "lsp": {
        "cpp": {
            "command": ["clangd"],
            "extensions": [".c", ".cc", ".cpp", ".cxx", ".h", ".hpp", ".hh", ".hxx"]
        },
        "go": {
            "command": ["gopls"],
            "extensions": [".go", ".mod", ".sum", ".work"]
        },
        "python": {
            "command": ["pyright-langserver", "--stdio"],
            "extensions": [".py", ".pyi"]
        },
        "typescript": {
            "command": ["typescript-language-server", "--stdio"],
            "extensions": [".ts", ".tsx", ".js", ".jsx"]
        }
    },
    "permission": "allow",
    "agent": {
        "code-review": {
            "mode": "subagent",
            "model": "openai/gpt-5.2-codex",
            "description": "代码审查与修复",
            "prompt": "请专注于 bug、安全和性能问题",
            "color": "#4B8BFF",
            "steps": 8
        },
        "doc-writer": {
            "mode": "subagent",
            "model": "openai/gpt-5.2",
            "description": "文档编写与润色",
            "prompt": "请输出结构清晰、可直接使用的文档",
            "color": "#22A06B",
            "steps": 6
        },
        "code-dev-expert": {
            "mode": "subagent",
            "model": "openai/gpt-5.2-codex",
            "description": "代码开发与架构实现",
            "prompt": "请专注于需求实现、可维护性与性能",
            "color": "#8A63D2",
            "steps": 10
        },
        "arch-designer": {
            "mode": "subagent",
            "model": "openai/gpt-5.2",
            "description": "架构设计与技术选型",
            "prompt": "请给出清晰的系统分层、边界与技术选型建议",
            "color": "#D97706",
            "steps": 8
        },
        "frontend-expert": {
            "mode": "subagent",
            "model": "google/gemini-3-pro-preview",
            "description": "前端专家与体验优化",
            "prompt": "请关注界面设计、交互体验与可访问性",
            "color": "#0F766E",
            "steps": 8
        }
    },
    "provider": {
        "google": {
            "options": {
                "baseURL": "https://api.leagsoft.ai/v1beta",
                "apiKey": "{env:GOOGLE_API_KEY}"
            },
            "models": {
                "gemini-3-pro-preview": {
                    "id": "gemini-3-pro-preview"
                },
                "gemini-3-flash-preview": {
                    "id": "gemini-3-flash-preview"
                }
            }
        },
        "openai": {
            "options": {
                "baseURL": "https://api.leagsoft.ai/v1",
                "apiKey": "{env:OPENAI_API_KEY}"
            },
            "models": {
                "gpt-5.2": {
                    "tool_call": true,
                    "options": {
                        "include": ["reasoning.encrypted_content"],
                        "store": false,
                        "reasoningEffort": "high",
                        "textVerbosity": "high",
                        "reasoningSummary": "auto"
                    }
                },
                "gpt-5.2-codex": {
                    "tool_call": true,
                    "options": {
                        "include": ["reasoning.encrypted_content"],
                        "store": false,
                        "reasoningEffort": "high",
                        "textVerbosity": "medium",
                        "reasoningSummary": "auto"
                    }
                }
            }
        }
    }
}

配置说明

这个配置包含：

MCP 服务：Context7 上下文管理、Grep 代码搜索、Exa 网络搜索
LSP 服务器：C/C++、Go、Python、TypeScript 四种语言支持
五个专业代理：代码审查、文档编写、代码开发、架构设计、前端专家
双 Provider 配置：Google Gemini 和 OpenAI，使用自定义 API 代理服务

变量替换

配置文件支持两种变量替换语法：

环境变量

json

{
  "provider": {
    "openai": {
      "options": {
        "apiKey": "{env:OPENAI_API_KEY}",
        "baseURL": "{env:OPENAI_BASE_URL}"
      }
    }
  }
}

文件内容

json

{
  "agent": {
    "custom": {
      "prompt": "{file:./prompts/custom-agent.md}"
    }
  }
}

支持相对路径和绝对路径。

高级配置选项

TUI 界面配置

json

{
  "tui": {
    "scroll_speed": 3,
    "scroll_acceleration": 1.5,
    "diff_style": "unified"
  }
}

服务器配置

json

{
  "server": {
    "port": 8080,
    "hostname": "localhost",
    "mdns": true,
    "cors": ["http://localhost:3000"]
  }
}

快捷键配置

json

{
  "keybinds": {
    "switch_agent": "tab",
    "submit": "enter",
    "cancel": "escape"
  }
}

文件监控配置

json

{
  "watcher": {
    "patterns": ["**/*.ts", "**/*.js"],
    "ignore": ["node_modules", "dist"]
  }
}

代码格式化配置

json

{
  "formatters": {
    "typescript": "prettier --write",
    "python": "black",
    "go": "gofmt -w"
  }
}

自动更新配置

json

{
  "autoupdate": true
}

或通过环境变量禁用：

bash

export OPENCODE_DISABLE_AUTOUPDATE=true

环境变量

变量	说明
`OPENCODE_CONFIG`	自定义配置文件路径
`OPENCODE_CONFIG_CONTENT`	内联配置内容（JSON 字符串）
`OPENCODE_SERVER_PASSWORD`	启用服务器基本认证
`OPENCODE_DISABLE_AUTOUPDATE`	禁用自动更新检查
`OPENCODE_EXPERIMENTAL_*`	实验性功能开关

实验性功能

bash

# 启用 LSP 工具
export OPENCODE_EXPERIMENTAL_LSP_TOOL=true

最佳实践

1. 使用 JSON Schema

始终添加 $schema 字段获得 IDE 自动补全和验证：

json

{
  "$schema": "https://opencode.ai/config.json"
}

2. 敏感信息使用环境变量

不要在配置文件中硬编码 API Key：

json

{
  "provider": {
    "anthropic": {
      "options": {
        "apiKey": "{env:ANTHROPIC_API_KEY}"
      }
    }
  }
}

3. 项目级配置

将 opencode.json 放在项目根目录，并考虑是否添加到 .gitignore：

gitignore

# 如果包含敏感信息，添加到 gitignore
opencode.json

# 或只忽略认证文件
~/.local/share/opencode/auth.json

4. 按需启用功能

只启用需要的 MCP 服务和 LSP 服务器，避免资源浪费：

json

{
  "mcp": {
    "context7": { "enabled": true },
    "unused_service": { "enabled": false }
  },
  "lsp": {
    "unused_language": { "disabled": true }
  }
}

5. 禁用不需要的提供商

json

{
  "disabled_providers": ["provider-name"]
}

下一步

Provider 配置 - 配置 LLM 提供商
MCP 服务 - 配置 MCP 服务扩展
LSP 配置 - 配置语言服务器
Agents 代理系统 - 配置自定义代理

配置详解 ​

配置文件位置 ​

基本配置结构 ​

核心配置选项 ​

模型配置 ​

主题配置 ​

默认代理 ​

权限配置 ​

工具配置 ​

完整配置示例 ​

配置说明 ​

变量替换 ​

环境变量 ​

文件内容 ​

高级配置选项 ​

TUI 界面配置 ​

服务器配置 ​

快捷键配置 ​

文件监控配置 ​

代码格式化配置 ​

自动更新配置 ​

环境变量 ​

实验性功能 ​

最佳实践 ​

1. 使用 JSON Schema ​

2. 敏感信息使用环境变量 ​

3. 项目级配置 ​

4. 按需启用功能 ​

5. 禁用不需要的提供商 ​

下一步 ​

配置详解

配置文件位置

基本配置结构

核心配置选项

模型配置

主题配置

默认代理

权限配置

工具配置

完整配置示例

配置说明

变量替换

环境变量

文件内容

高级配置选项

TUI 界面配置

服务器配置

快捷键配置

文件监控配置

代码格式化配置

自动更新配置

环境变量

实验性功能

最佳实践

1. 使用 JSON Schema

2. 敏感信息使用环境变量

3. 项目级配置

4. 按需启用功能

5. 禁用不需要的提供商

下一步