OpenCode 配置文件（opencode.json）完全指南：用统一配置管理 AI 编程助手的全部行为

OpenCode 是一个功能强大的 AI 编程助手，其高度可配置的特性让它能适应各种开发场景和团队需求。而所有这些配置的核心，就是 opencode.json 配置文件。本文将全面解析 OpenCode 的配置系统，帮助你掌握从基础到高级的所有配置技巧。

配置文件格式与位置

JSON 与 JSONC

OpenCode 同时支持标准的 JSON 和带注释的 JSONC 格式。JSONC 允许你在配置文件中添加注释，非常适合团队分享配置文件时说明各配置项的用途：

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

推荐始终添加 $schema 字段，这样编辑器可以自动提供校验和自动补全。

配置文件的层级与优先级

OpenCode 的配置文件系统采用分层设计，支持从组织级到项目级的精细控制。所有配置文件会被合并而非替换，非冲突的设置会共存：

Remote 配置（.well-known/opencode）— 组织默认配置，如统一的 MCP 服务器

全局配置（~/.config/opencode/opencode.json）— 个人偏好设置

自定义路径（OPENCODE_CONFIG 环境变量）

项目配置（项目根目录的 opencode.json）— 项目专属设置

.opencode 目录配置 — agent、command、plugin 等子配置

内联配置（OPENCODE_CONFIG_CONTENT 环境变量）— 运行时覆盖

托管配置（系统级目录）— 管理员强制配置

这种层级设计非常灵活：组织可以设置默认策略，开发者可以覆盖个人偏好，项目可以定义专属规则。

核心配置项详解

模型与提供商配置

模型配置是 OpenCode 的核心。通过 provider、model 和 small_model 三个选项管理：

{
  "model": "anthropic/claude-sonnet-4-5",
  "small_model": "anthropic/claude-haiku-4-5",
  "provider": {
    "anthropic": {
      "options": {
        "timeout": 600000,
        "chunkTimeout": 30000,
        "setCacheKey": true
      }
    }
  }
}

small_model 用于标题生成等轻量任务，OpenCode 会优先使用更经济的模型。你还可以通过 disabled_providers 和 enabled_providers 精确控制可用的提供商列表。

TUI 界面配置

TUI 相关的设置放入独立的 tui.json 文件中，与服务端配置分离，职责更清晰：

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

attention 模块特别实用——开启后，当 AI 完成长时间任务时会发送桌面通知并播放提示音，让你无需一直盯着终端。

安全与权限控制

OpenCode 默认允许所有操作，但你可以通过 permission 选项开启审批流程：

{
  "permission": {
    "edit": "ask",
    "bash": "ask"
  }
}

对于企业环境，还可以通过 experimental.policies 实现更精细的策略控制，比如禁止使用某些 AI 提供商：

{
  "experimental": {
    "policies": [
      {
        "effect": "deny",
        "action": "provider.use",
        "resource": "openai"
      }
    ]
  }
}

快照与撤销

OpenCode 使用快照系统追踪文件变更，让你可以随时撤销 AI 的操作：

{
  "snapshot": true
}

对于大型项目，快照可能消耗较多磁盘空间和索引时间，此时可以选择关闭。但请注意，关闭后将无法通过 UI 回滚变更。

上下文压缩

长时间会话中，上下文窗口可能会被填满。compaction 选项控制自动压缩行为：

{
  "compaction": {
    "auto": true,
    "prune": false,
    "reserved": 10000
  }
}

auto：上下文满时自动压缩（默认开启）
prune：移除旧的工具输出以节省 token（默认关闭）
reserved：保留的 token 缓冲，避免压缩过程中溢出

自动更新

{
  "autoupdate": true
}

设为 false 可禁用自动更新。设为 "notify" 则仅在有新版本时通知你，但不自动下载。

Agent 与子 Agent 深度

{
  "default_agent": "plan",
  "subagent_depth": 2
}

default_agent 设置默认使用的 Agent（内置的 build、plan 或自定义 Agent）。subagent_depth 控制子 Agent 的嵌套层级，默认 1 表示主 Agent 可启动子 Agent，但子 Agent 不能再启动其他子 Agent。

格式化和 LSP

OpenCode 内置了代码格式化器和 LSP 服务器的支持，通过简单配置即可开启：

{
  "formatter": {
    "prettier": {
      "disabled": true
    },
    "custom-prettier": {
      "command": ["npx", "prettier", "--write", "$FILE"],
      "environment": { "NODE_ENV": "development" },
      "extensions": [".js", ".ts", ".jsx", ".tsx"]
    }
  },
  "lsp": true
}

可以禁用内置的格式化器，替换为自定义版本。LSP 设为 true 即可启用所有内置的语言服务器。

高级配置技巧

环境变量与文件引用

OpenCode 的变量替换机制让你可以在配置中引用环境变量或文件内容：

{
  "model": "{env:OPENCODE_MODEL}",
  "provider": {
    "openai": {
      "options": {
        "apiKey": "{file:~/.secrets/openai-key}"
      }
    }
  }
}

这对管理 API Key 等敏感信息特别有用——密钥存放在独立文件中，不会被意外提交到版本控制。

指令文件引入

通过 instructions 字段，你可以引入外部文件作为 AI 的系统指令：

{
  "instructions": ["CONTRIBUTING.md", "docs/guidelines.md", ".cursor/rules/*.md"]
}

支持 glob 模式匹配，可以一次性引入多个文件。这在遵循团队编码规范时非常实用。

Shell 配置

{
  "shell": "pwsh"
}

指定交互式终端和 Agent 工具调用使用的 Shell。OpenCode 会自动检测系统默认 Shell，但你也可以显式指定。

自定义命令与快捷键

{
  "command": {
    "test": {
      "template": "Run the full test suite with coverage report and show any failures.",
      "description": "Run tests with coverage",
      "agent": "build",
      "model": "anthropic/claude-haiku-4-5"
    }
  }
}

命令和快捷键也可以直接在配置中定义，无需额外文件。

企业级配置管理

对于组织部署，OpenCode 提供了托管配置机制。在 macOS 上可以通过 MDM 推送 .mobileconfig 配置，Linux 和 Windows 也有对应的系统级配置目录。托管配置具有最高优先级，用户无法覆盖，确保企业安全策略的强制执行。

在 macOS 上部署受管配置后，可以通过以下命令验证：

opencode debug config

所有受管配置项会显示在解析后的配置中，且无法被用户或项目配置覆盖。

配置实战示例

以下是一个完整的项目级配置文件示例：

{
  "$schema": "https://opencode.ai/config.json",
  "model": "anthropic/claude-sonnet-4-5",
  "small_model": "anthropic/claude-haiku-4-5",
  "autoupdate": "notify",
  "snapshot": true,
  "default_agent": "build",
  "subagent_depth": 1,
  "permission": {
    "bash": "ask"
  },
  "formatter": true,
  "lsp": true,
  "instructions": ["CONTRIBUTING.md"],
  "compaction": {
    "auto": true,
    "prune": false,
    "reserved": 10000
  },
  "command": {
    "lint": {
      "template": "Run the linter and fix all auto-fixable issues.",
      "description": "Lint and fix code"
    },
    "deploy": {
      "template": "Build the project and deploy to staging environment.",
      "description": "Deploy to staging"
    }
  },
  "provider": {
    "anthropic": {
      "options": {
        "timeout": 600000,
        "chunkTimeout": 30000
      }
    }
  }
}

这个配置涵盖了模型选择、安全策略、代码质量工具、常用命令等核心功能，适合大多数前端/全栈项目使用。

总结

OpenCode 的配置文件系统设计精良，从个人开发者到大型企业都能找到合适的配置策略。掌握 opencode.json 的配置技巧，可以让你更好地控制 AI 编程助手的行为，提升开发效率。建议从项目级配置入手，逐步探索全局配置和高级选项，找到最适合你和团队的配置组合。