本文档详细介绍了OpenCode的JSON配置文件系统，包括配置格式、位置、完整schema以及变量替换功能，涵盖了TUI、服务器、工具、模型、主题、代理、命令等关键配置选项。
OpenCode 配置文档
概述
OpenCode使用JSON配置文件进行配置，支持JSON和JSONC（带注释的JSON）格式。
配置格式
支持格式：
- JSON - 标准JSON格式
- JSONC - JSON with Comments（带注释的JSON）
示例配置：
{
"$schema": "https://opencode.ai/config.json",
// 主题配置
"theme": "opencode",
"model": "anthropic/claude-sonnet-4-5",
"autoupdate": true,
}
配置位置
配置文件按优先级顺序合并，而非替换：
全局配置
位置：~/.config/opencode/opencode.json 用途：主题、提供商、快捷键等全局设置
项目配置
位置：项目根目录下的 opencode.json 用途：项目特定的提供商或模式配置
自定义路径
通过环境变量指定：
export OPENCODE_CONFIG=/path/to/my/custom-config.json
自定义目录
通过环境变量指定：
export OPENCODE_CONFIG_DIR=/path/to/my/config-directory
配置Schema
TUI配置
{
"tui": {
"scroll_speed": 3,
"scroll_acceleration": {
"enabled": true
},
"diff_style": "auto"
}
}
可用选项：
scroll_acceleration.enabled- 启用macOS风格滚动加速（优先于scroll_speed）scroll_speed- 自定义滚动速度乘数（默认：1，最小值：1）diff_style- 控制差异渲染："auto"适应终端宽度，"stacked"始终显示单列
服务器配置
{
"server": {
"port": 4096,
"hostname": "0.0.0.0",
"mdns": true,
"cors": ["http://localhost:5173"]
}
}
可用选项：
port- 监听端口hostname- 监听主机名mdns- 启用mDNS服务发现cors- 允许的CORS来源
工具管理
{
"tools": {
"write": false,
"bash": false
}
}
模型配置
{
"provider": {},
"model": "anthropic/claude-sonnet-4-5",
"small_model": "anthropic/claude-haiku-4-5"
}
small_model用于轻量级任务（如标题生成），默认尝试使用更便宜的模型。
提供商选项：
{
"provider": {
"anthropic": {
"options": {
"timeout": 600000,
"setCacheKey": true
}
}
}
}
timeout- 请求超时（毫秒，默认：300000）setCacheKey- 确保为指定提供商设置缓存键
Amazon Bedrock特定配置
{
"provider": {
"amazon-bedrock": {
"options": {
"region": "us-east-1",
"profile": "my-aws-profile",
"endpoint": "https://bedrock-runtime.us-east-1.vpce-xxxxx.amazonaws.com"
}
}
}
}
region- AWS区域（默认：AWS_REGION环境变量或us-east-1）profile- AWS命名配置文件endpoint- VPC端点的自定义端点URL
主题配置
{
"theme": ""
}
代理配置
{
"agent": {
"code-reviewer": {
"description": "Reviews code for best practices and potential issues",
"model": "anthropic/claude-sonnet-4-5",
"prompt": "You are a code reviewer. Focus on security, performance, and maintainability.",
"tools": {
// 为仅审查代理禁用文件修改工具
"write": false,
"edit": false,
},
},
},
}
默认代理
{
"default_agent": "plan"
}
必须是主代理（非子代理），适用于所有接口：TUI、CLI、桌面应用和GitHub Action。
分享配置
{
"share": "manual"
}
选项：
"manual"- 允许通过命令手动分享（默认）"auto"- 自动分享新对话"disabled"- 完全禁用分享
命令配置
{
"command": {
"test": {
"template": "Run the full test suite with coverage report and show any failures.\nFocus on the failing tests and suggest fixes.",
"description": "Run tests with coverage",
"agent": "build",
"model": "anthropic/claude-haiku-4-5",
},
"component": {
"template": "Create a new React component named $ARGUMENTS with TypeScript support.\nInclude proper typing and basic structure.",
"description": "Create a new component",
},
},
}
快捷键配置
{
"keybinds": {}
}
自动更新
{
"autoupdate": false
}
设置为"notify"可在新版本可用时收到通知。
格式化器配置
{
"formatter": {
"prettier": {
"disabled": true
},
"custom-prettier": {
"command": ["npx", "prettier", "--write", "$FILE"],
"environment": {
"NODE_ENV": "development"
},
"extensions": [".js", ".ts", ".jsx", ".tsx"]
}
}
}
权限配置
{
"permission": {
"edit": "ask",
"bash": "ask"
}
}
压缩配置
{
"compaction": {
"auto": true,
"prune": true
}
}
auto- 上下文满时自动压缩会话（默认：true）prune- 删除旧工具输出以节省token（默认：true）
文件监视器配置
{
"watcher": {
"ignore": ["node_modules/**", "dist/**", ".git/**"]
}
}
MCP服务器配置
{
"mcp": {}
}
插件配置
{
"plugin": ["opencode-helicone-session", "@my-org/custom-plugin"]
}
指令配置
{
"instructions": ["CONTRIBUTING.md", "docs/guidelines.md", ".cursor/rules/*.md"]
}
禁用提供商
{
"disabled_providers": ["openai", "gemini"]
}
disabled_providers优先级高于enabled_providers。
启用提供商
{
"enabled_providers": ["anthropic", "openai"]
}
实验性功能
{
"experimental": {}
}
变量替换
环境变量
使用{env:VARIABLE_NAME}替换环境变量：
{
"model": "{env:OPENCODE_MODEL}",
"provider": {
"anthropic": {
"options": {
"apiKey": "{env:ANTHROPIC_API_KEY}"
}
}
}
}
文件内容
使用{file:path/to/file}替换文件内容：
{
"instructions": ["./custom-instructions.md"],
"provider": {
"openai": {
"options": {
"apiKey": "{file:~/.secrets/openai-key}"
}
}
}
}
文件路径可以是：
- 相对于配置文件目录的相对路径
- 以
/或~开头的绝对路径
用途：
- 将敏感数据（如API密钥）保存在单独文件中
- 包含大型指令文件而不使配置混乱
- 在多个配置文件中共享通用配置片段
目前正在使用的配置
{
"$schema": "https://opencode.ai/config.json",
"autoupdate": false,
"share": "disabled",
"default_agent": "plan",
"permission": {
"edit": "ask",
"bash": "ask"
},
"compaction": {
"auto": false,
"prune": true
},
"watcher": {
"ignore": [
"node_modules/**",
"dist/**",
".git/**"
]
},
"mcp": {},
"provider": {
"anthropic": {
"models": {
"glm-4.7": {
"id": "glm-4.7",
"name": "glm-4.7"
}
},
"options": {
"apiKey": "sk-kQKMTKyEQA7X6eZ_K3oV1NyiQdjeppL9XZbNz5r3xBJnOju9j49dchfpTFk",
"baseURL": "http://localhost:3030/claude/v1"
}
},
"local": {
"npm": "@ai-sdk/openai-compatible",
"name": "local",
"options": {
"baseURL": "http://localhost:3030/v1",
"apiKey": "sk-kQKMTKyEQA7X6eZ_K3oV1NyiQdjeppL9XZbNz5r3xBJnOju9j49dchfpTFk",
"headers": {
"Authorization": "Bearer sk-kQKMTKyEQA7X6eZ_K3oV1NyiQdjeppL9XZbNz5r3xBJnOju9j49dchfpTFk"
}
},
"models": {
"glm-4.7": {
"name": "glm-4.7",
"limit": {
"context": 200000,
"output": 65536
}
}
}
}
}
}
