OpenCode 配置文件完全指南：从基础到高级的 opencode.json 实战手册

OpenCode 配置文件完全指南：从基础到高级的 opencode.json 实战手册

引言

当你开始使用 OpenCode 这款 AI 编程助手时，最核心的配置工作就是编辑 opencode.json 配置文件。它就像是 OpenCode 的"大脑"，控制着从模型选择、工具权限到界面主题的方方面面。无论你是刚入门的新手还是深度用户，掌握这个配置文件都能让你更高效地驾驭 AI 编程工作流。

本文将从配置文件的基础格式讲起，逐步深入到多环境配置、变量替换和高级运维场景，帮助你全面掌握 OpenCode 的配置体系。

配置文件的格式与位置

JSON vs JSONC

OpenCode 支持两种配置文件格式：标准的 .json 和带注释的 .jsonc。推荐使用 JSONC 格式，因为它允许你在配置中添加注释说明，方便团队协作：

{
  "$schema": "https://opencode.ai/config.json",
  // 默认模型
  "model": "anthropic/claude-sonnet-4-5",
  // 自动更新开关
  "autoupdate": true,
}

$schema 字段指向官方 JSON Schema 地址，配置了它之后，支持 Schema 验证的编辑器（VS Code、WebStorm 等）会自动提供补全和校验功能。

配置文件的加载顺序

OpenCode 的配置文件有严格的优先级顺序，后面的配置会覆盖前面的同名配置，但不同源的配置会被合并而非替换。理解这一点对于排查配置问题至关重要：

远程配置 - 组织通过 .well-known/opencode 下发的默认配置，首次认证时自动获取

全局配置 - ~/.config/opencode/opencode.json，用户级别的偏好设置

自定义路径配置 - OPENCODE_CONFIG 环境变量指定的配置文件

项目配置 - 项目根目录下的 opencode.json，最高优先级的普通配置文件

.opencode 目录 - 项目中的 agent、command、plugin 等子目录

内联配置 - OPENCODE_CONFIG_CONTENT 环境变量，运行时覆盖

托管配置 - 系统级托管目录（如 macOS 的 /Library/Application Support/opencode/）

MDM 托管配置 - macOS 通过 .mobileconfig 下发的强制配置，不可被用户覆盖

这意味着你可以在全局配置中设定个人偏好，在项目配置中覆盖特定项目的设置，而组织管理员则可以通过远程配置或 MDM 强制安全策略。

配置文件查找机制

当你在项目目录中启动 opencode 时，它会先在当前目录查找 opencode.json，然后逐级向上查找直到找到 Git 仓库根目录。这种设计让你可以为不同仓库设置不同的配置，而不必担心配置泄漏到无关目录。

核心配置详解

模型与提供商配置

{
  "$schema": "https://opencode.ai/config.json",
  // 主力模型
  "model": "anthropic/claude-sonnet-4-5",
  // 轻量模型（用于标题生成等简单任务）
  "small_model": "anthropic/claude-haiku-4-5",
  // 提供商选项
  "provider": {
    "anthropic": {
      "options": {
        "timeout": 600000,         // 超时时间（毫秒）
        "chunkTimeout": 30000,     // 流式响应块超时
        "setCacheKey": true        // 始终设置缓存键
      }
    }
  }
}

model 字段使用 提供商/模型名 格式。small_model 用于处理轻量级任务，如果未指定，OpenCode 会尝试使用当前提供商下更便宜的模型，否则回退到主模型。

服务器配置

如果你需要以服务模式运行 OpenCode（团队协作或远程调用），server 配置段非常关键：

{
  "server": {
    "port": 4096,
    "hostname": "0.0.0.0",
    "mdns": true,
    "mdnsDomain": "myproject.local",
    "cors": ["http://localhost:5173"]
  }
}
  • mdns 启用局域网服务发现，同网络下的设备可以直接发现你的 OpenCode 服务
  • mdnsDomain 支持自定义域名，适用于同一网络下运行多个实例的场景
  • cors 配置浏览器的跨域白名单，让 Web 客户端也能调用服务

工具权限管理

控制 AI 可以使用哪些工具是安全实践的第一步：

{
  "permission": {
    "edit": "ask",      // 编辑文件时需确认
    "bash": "ask",      // 执行命令时需确认
    "write": "allow"    // 写入新文件直接允许
  }
}

权限值有三种：allow（直接允许）、ask（询问用户）、deny（禁止）。你可以针对特定命令做更精细的控制：

{
  "permission": {
    "bash": {
      "*": "ask",
      "rm -rf *": "deny"  // 永远禁止危险命令
    }
  }
}

自定义 Agent 配置

OpenCode 的 Agent 系统是它最强大的特性之一。通过配置自定义 Agent，你可以为不同的任务分配不同的模型和行为规则：

{
  "agent": {
    "code-reviewer": {
      "description": "审查代码质量与安全",
      "model": "anthropic/claude-sonnet-4-5",
      "prompt": "你是一名资深代码审查员，请重点关注安全漏洞、性能问题和代码可维护性。",
      "tools": {
        "write": false,    // 审查只需要读，不需要写
        "edit": false,
        "bash": true       // 允许运行测试
      }
    },
    "junior-dev": {
      "description": "处理简单的重复性任务",
      "model": "anthropic/claude-haiku-4-5",
      "prompt": "你是一名初级开发者，擅长处理格式化、重构等标准化任务。不确定时请向用户确认。"
    }
  },
  "default_agent": "build"
}

default_agent 指定默认使用的 Agent，默认为 build。你可以切换到 plan 模式让 AI 先制定计划再执行，或者使用自己定义的自定义 Agent。

自定义命令

对于频繁执行的固定任务，自定义命令能节省大量时间：

{
  "command": {
    "test": {
      "template": "运行全量测试并生成覆盖率报告，列出所有失败用例及其原因。",
      "description": "运行测试 + 覆盖率",
      "agent": "build"
    },
    "component": {
      "template": "创建一个名为 $ARGUMENTS 的 React 组件，包含 TypeScript 类型定义、基础样式和单元测试。",
      "description": "创建新组件",
      "agent": "junior-dev"
    },
    "lint-fix": {
      "template": "运行 linter 并自动修复所有可修复的问题，列出不能自动修复的问题。",
      "description": "自动修复代码格式"
    }
  }
}

命令中可以引用 $ARGUMENTS 变量，用户在输入 /component Button 时，模板中的 $ARGUMENTS 会被替换为 Button。还可以指定 agent 让特定命令使用特定 Agent。

表单格式化与 LSP

{
  "formatter": true,
  "lsp": true
}

简单设置为 true 即可开启所有内置支持。你也可以精细控制：

{
  "formatter": {
    "prettier": {
      "disabled": true     // 禁用内置 Prettier
    },
    "custom-prettier": {
      "command": ["npx", "prettier", "--write", "$FILE"],
      "extensions": [".js", ".ts", ".jsx", ".tsx"]
    }
  },
  "lsp": {
    "typescript": {
      "disabled": true     // 禁用内置 TypeScript LSP
    },
    "rust-analyzer": {}    // 启用 Rust LSP
  }
}

高级配置技巧

变量替换

OpenCode 配置支持两种变量替换方式，让你的配置更灵活：

环境变量替换：

{
  "model": "{env:OPENCODE_MODEL}",
  "provider": {
    "anthropic": {
      "options": {
        "apiKey": "{env:ANTHROPIC_API_KEY}"
      }
    }
  }
}

文件内容替换：

{
  "provider": {
    "openai": {
      "options": {
        "apiKey": "{file:~/.secrets/openai-key}"
      }
    }
  }
}

文件路径可以是相对路径（相对于配置文件所在目录），也可以是绝对路径或 ~ 开头的路径。这种方式特别适合将密钥与配置文件分离，方便在版本控制中共享配置文件而不暴露密钥。

多环境配置策略

一个实用的配置方案是利用配置文件的合并机制，构建分层配置：

全局配置 ~/.config/opencode/opencode.json — 存放个人偏好：

{
  "model": "anthropic/claude-sonnet-4-5",
  "autoupdate": true,
  "compaction": {
    "auto": true,
    "prune": true
  }
}

项目配置 opencode.json — 存放项目特定设置：

{
  "formatter": true,
  "lsp": {
    "typescript": {},
    "rust-analyzer": {}
  },
  "instructions": ["CONTRIBUTING.md", ".opencode/rules/*.md"]
}

两个配置文件会被合并：全局配置提供模型和更新策略，项目配置提供格式化、LSP 和项目指令。互不冲突的设置会被保留，同名设置以项目配置为准。

上下文管理配置

对于大型项目，上下文窗口管理尤为重要：

{
  "compaction": {
    "auto": true,       // 上下文满时自动压缩
    "prune": false,     // 不裁剪旧的工具输出
    "reserved": 10000   // 保留 10000 token 缓冲
  },
  "subagent_depth": 1,  // 子 Agent 最大嵌套深度
  "snapshot": true       // 启用快照以便撤销操作
}

subagent_depth 控制子 Agent 的嵌套层级。默认值 1 允许主 Agent 调用子 Agent，但子 Agent 不能再调用其他子 Agent。设为 2 可以增加一层嵌套，设为 0 则完全禁止子 Agent。

图像附件优化

如果你经常拖拽截图给 AI，可以调整图像附件的处理参数：

{
  "attachment": {
    "image": {
      "auto_resize": true,
      "max_width": 2000,
      "max_height": 2000,
      "max_base64_bytes": 5242880
    }
  }
}

自动缩放功能会在发送前将超大图片压缩到限制范围内，既保证 AI 能看清内容，又避免浪费 token。

TUI 界面配置

OpenCode 的终端界面配置独立存放在 tui.json 中：

{
  "$schema": "https://opencode.ai/tui.json",
  "theme": "tokyonight",
  "scroll_speed": 3,
  "scroll_acceleration": {
    "enabled": true
  },
  "diff_style": "auto",
  "mouse": true,
  "attention": {
    "enabled": true,
    "notifications": true,
    "sound": true,
    "volume": 0.4
  }
}
  • theme 支持多种内置主题，也可以通过 .opencode/themes/ 目录自定义
  • diff_style 控制代码变更的展示风格，可选 auto、compact 或 full
  • attention 启用后，AI 完成任务时会发送桌面通知并播放提示音

TUI 配置可以通过 OPENCODE_TUI_CONFIG 环境变量指定自定义路径。

企业级配置

对于团队和组织，OpenCode 提供了多层配置策略：

远程配置（.well-known）

组织可以在认证服务上提供 .well-known/opencode 端点，自动下发基础配置。例如，预配置 MCP 服务器但默认禁用，让用户按需启用：

// 远程配置：默认禁用组织 MCP 服务器
{
  "mcp": {
    "jira": {
      "type": "remote",
      "url": "https://jira.example.com/mcp",
      "enabled": false
    }
  }
}

// 用户本地配置：按需启用
{
  "mcp": {
    "jira": {
      "type": "remote",
      "url": "https://jira.example.com/mcp",
      "enabled": true
    }
  }
}

托管配置与 MDM

在 macOS 环境中，管理员可以通过 MDM 方案（Jamf、FleetDM 等）部署强制配置。托管配置使用 ai.opencode.managed 偏好域，通过 .mobileconfig 文件下发，用户无法修改。常见场景包括：

  • 强制禁用共享功能（"share": "disabled"）
  • 锁定服务器地址和端口
  • 强制执行权限策略（所有写操作必须确认）
  • 限制可用的 AI 提供商

验证托管配置是否生效，可以运行 opencode debug config，所有托管设置会出现在解析后的配置中且不可覆盖。

总结

OpenCode 的配置文件体系设计精巧，兼顾了灵活性、安全性和易用性。从单个 JSON 文件起步，到多层级配置合并、变量替换、MDM 托管，它能够满足从个人开发者到大型企业的各种需求。

掌握 opencode.json 的配置技巧，意味着你不再只是被动使用 AI 编程助手，而是能够根据项目特点、团队规范和个人习惯，打造真正属于自己的 AI 编程工作流。

建议下手的第一个配置是模型选择和权限管理，这是安全高效的基石。随着使用深入，再逐步探索自定义 Agent、命令和工作流优化。OpenCode 的配置体系潜力巨大，值得花时间细细打磨。

叶云梦天

叶云梦天，专注微信，小程序，服务器管理，数据分析的信息博客