配置

使用 OpenCode JSON 配置。

你可以使用 JSON 配置文件配置 OpenCode。

格式

OpenCode 支持 JSON 和 JSONC（带注释的 JSON）格式。

{
  "$schema": "https://opencode.ai/config.json",
  "model": "anthropic/claude-sonnet-4-5",
  "autoupdate": true,
  "server": {
    "port": 4096,
  },
}

位置

你可以将配置放在几个不同的位置，它们具有不同的优先级。

[!NOTE] 配置文件是合并在一起的，不是替换的。

配置源按此顺序加载（后面的源覆盖前面的）：

远程配置（来自 .well-known/opencode）- 组织默认设置
全局配置（~/.config/opencode/opencode.json）- 用户偏好
自定义配置（OPENCODE_CONFIG 环境变量）- 自定义覆盖
项目配置（项目中的 opencode.json）- 项目特定设置
.opencode 目录 - 智能体、命令、插件
内联配置（OPENCODE_CONFIG_CONTENT 环境变量）- 运行时覆盖
托管配置文件（macOS 上为 /Library/Application Support/opencode/）- 管理员控制
macOS 托管偏好（通过 MDM 的 .mobileconfig）- 最高优先级，用户无法覆盖

远程

组织可以通过 .well-known/opencode 端点提供默认配置。

{
  "mcp": {
    "jira": {
      "type": "remote",
      "url": "https://jira.example.com/mcp",
      "enabled": true
    }
  }
}

全局

将你的全局 OpenCode 配置放在 ~/.config/opencode/opencode.json。

每个项目

在项目根目录添加 opencode.json。

[!TIP] 将项目特定配置放在项目的根目录。

自定义路径

使用 OPENCODE_CONFIG 环境变量指定自定义配置文件路径。

export OPENCODE_CONFIG=/path/to/my/custom-config.json
opencode run "Hello world"

自定义目录

使用 OPENCODE_CONFIG_DIR 环境变量指定自定义配置目录。

export OPENCODE_CONFIG_DIR=/path/to/my/config-directory
opencode run "Hello world"

托管设置

组织可以强制用户无法覆盖的配置。

平台	路径
macOS	`/Library/Application Support/opencode/`
Linux	`/etc/opencode/`
Windows	`%ProgramData%\opencode`

Schema

服务器/运行时配置 schema 定义在 opencode.ai/config.json 中。

你的编辑器应该能够根据 schema 进行验证和自动补全。

TUI

使用专用的 tui.json（或 tui.jsonc）文件进行 TUI 特定设置。

{
  "$schema": "https://opencode.ai/tui.json",
  "scroll_speed": 3,
  "diff_style": "auto",
  "mouse": true,
  "attention": {
    "enabled": true,
    "notifications": true,
    "sound": true,
    "volume": 0.4
  }
}

服务器

{
  "$schema": "https://opencode.ai/config.json",
  "server": {
    "port": 4096,
    "hostname": "0.0.0.0",
    "mdns": true,
    "mdnsDomain": "myproject.local",
    "cors": ["http://localhost:5173"]
  }
}

可用选项：

port - 监听端口
hostname - 监听主机名，启用 mdns 时默认为 0.0.0.0
mdns - 启用 mDNS 服务发现，允许局域网内其他设备发现 OpenCode 服务器
mdnsDomain - 自定义 mDNS 域名，默认为 opencode.local
cors - 额外的 CORS 允许源，值必须是完整来源（scheme + host + optional port）

Shell

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

Tools

{
  "$schema": "https://opencode.ai/config.json",
  "tools": {
    "write": false,
    "bash": false
  }
}

Models

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {},
  "model": "anthropic/claude-sonnet-4-5",
  "small_model": "anthropic/claude-haiku-4-5"
}

Provider 选项：

timeout - 请求超时时间（毫秒），默认 300000
chunkTimeout - 流式响应块之间的超时时间
setCacheKey - 确保始终为指定 provider 设置缓存键

Policies

{
  "$schema": "https://opencode.ai/config.json",
  "experimental": {
    "policies": [
      {
        "effect": "deny",
        "action": "provider.use",
        "resource": "openai"
      }
    ]
  }
}

图片附件

{
  "$schema": "https://opencode.ai/config.json",
  "attachment": {
    "image": {
      "auto_resize": true,
      "max_width": 2000,
      "max_height": 2000,
      "max_base64_bytes": 5242880
    }
  }
}

主题

{
  "$schema": "https://opencode.ai/tui.json",
  "theme": "tokyonight"
}

智能体

{
  "$schema": "https://opencode.ai/config.json",
  "agent": {
    "code-reviewer": {
      "description": "Reviews code for best practices and potential issues",
      "model": "anthropic/claude-sonnet-4-5",
      "prompt": "You are a code reviewer.",
      "tools": {
        "write": false,
        "edit": false,
      },
    },
  },
}

默认智能体

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

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

"manual" - 允许通过命令手动分享（默认）
"auto" - 自动分享新对话
"disabled" - 完全禁用分享

命令

{
  "$schema": "https://opencode.ai/config.json",
  "command": {
    "test": {
      "template": "Run the full test suite with coverage report.",
      "description": "Run tests with coverage",
      "agent": "build",
      "model": "anthropic/claude-haiku-4-5",
    },
  },
}

键盘快捷键

{
  "$schema": "https://opencode.ai/tui.json",
  "keybinds": {
    "command_list": "ctrl+p"
  }
}

快照

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

自动更新

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

false - 禁用自动更新
"notify" - 不自动更新但有新版本时通知

格式化器

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

LSP 服务器

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

权限

{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
    "edit": "ask",
    "bash": "ask"
  }
}

压缩

{
  "$schema": "https://opencode.ai/config.json",
  "compaction": {
    "auto": true,
    "prune": false,
    "reserved": 10000
  }
}

auto - 上下文满时自动压缩（默认 true）
prune - 删除旧的工具输出来节省 token（默认 false）
reserved - 压缩时保留的 token 缓冲区

监视器

{
  "$schema": "https://opencode.ai/config.json",
  "watcher": {
    "ignore": ["node_modules/**", "dist/**", ".git/**"]
  }
}

MCP 服务器

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

插件

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": ["opencode-helicone-session", "@my-org/custom-plugin"]
}

指令

{
  "$schema": "https://opencode.ai/config.json",
  "instructions": ["CONTRIBUTING.md", "docs/guidelines.md", ".cursor/rules/*.md"]
}

禁用的 providers

{
  "$schema": "https://opencode.ai/config.json",
  "disabled_providers": ["openai", "gemini"]
}

启用的 providers

{
  "$schema": "https://opencode.ai/config.json",
  "enabled_providers": ["anthropic", "openai"]
}

[!NOTE] disabled_providers 优先级高于 enabled_providers

实验性

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

变量

环境变量

使用 {env:VARIABLE_NAME} 引用环境变量：

{
  "$schema": "https://opencode.ai/config.json",
  "model": "{env:OPENCODE_MODEL}",
  "provider": {
    "anthropic": {
      "models": {},
      "options": {
        "apiKey": "{env:ANTHROPIC_API_KEY}"
      }
    }
  }
}

文件

使用 {file:path/to/file} 引用文件内容：

{
  "$schema": "https://opencode.ai/config.json",
  "instructions": ["./custom-instructions.md"],
  "provider": {
    "openai": {
      "options": {
        "apiKey": "{file:~/.secrets/openai-key}"
      }
    }
  }
}

配置

配置

格式

位置

远程

全局