---
title: "配置 OpenCode"
description: "理解 opencode.json、配置合并、加载优先级和新手最小配置策略。"
verifiedAt: "2026-05-09"
---

OpenCode 使用 JSON 或 JSONC（JSON with Comments，比标准 JSON 多了 `//` 行注释和尾随逗号支持，调试团队配置时方便很多）配置。新手不需要先复制完整官方示例，先理解配置文件如何合并、哪个位置适合放什么、哪些设置不该一开始就改。

> [!NOTE]
> **这一篇用 8 分钟换什么**：你会知道全局配置和项目配置怎么分工，为什么配置会互相合并，哪些覆盖入口优先级更高，以及出问题时怎么回到最小配置。

## 先给结论：配置越少，越容易排错

OpenCode 配置的目标是让行为可预测，不是把所有能力一次性打开。第一次只需要让 provider、模型和项目规则可用；server、tools、provider options、MCP、formatter、Agent、Plugin 都应该按需要逐步加。

```mermaid
flowchart LR
  Connect["/connect 保存凭据"] --> Models["/models 确认可用模型"]
  Models --> Global["全局配置：个人偏好"]
  Models --> Project["项目配置：团队共享默认值"]
  Project --> Validate["Schema / 类型检查"]
  Validate --> Minimal["出错时回到最小配置重测"]

  style Connect fill:#dbeafe,stroke:#3b82f6
  style Project fill:#dcfce7,stroke:#22c55e,stroke-width:2px
  style Minimal fill:#fee2e2,stroke:#ef4444
```

> [!IMPORTANT]
> 真实 API key、个人路径、本机实验配置和临时代理不要进项目仓库。项目配置应该能被团队 review、提交和回滚。

## 配置是合并，不是只读一个文件

OpenCode 的配置不是简单替换，而是多层合并。后加载的配置在键冲突时覆盖前面的配置，非冲突设置会保留。

这意味着：你在全局配置里设置主题，在项目配置里设置模型，最终两者都会生效。排错时不要只看一个文件，要看所有配置来源。

## 加载优先级怎么记

官方配置会从多个来源加载，后面的来源优先级更高：

1. 远程组织配置（通过 `.well-known/opencode` 端点）。
2. 全局配置（`~/.config/opencode/opencode.json`）。
3. `OPENCODE_CONFIG` 指定的自定义配置。
4. 项目根目录 `opencode.json`。
5. `.opencode` 目录里的 agents、commands、plugins 等结构化扩展。
6. `OPENCODE_CONFIG_CONTENT` 内联配置。
7. **托管配置文件**（macOS `/Library/Application Support/opencode/`、Linux `/etc/opencode/`、Windows `%ProgramData%\opencode`）——管理员级别，需 root/admin 权限写入。
8. **macOS 托管偏好**（通过 MDM 推送的 `.mobileconfig`）——优先级最高，**用户无法覆盖**。

新手最常用的是全局配置和项目配置，其他入口先不要碰。`OPENCODE_CONFIG_CONTENT` 这类内联覆盖适合临时或自动化场景，不适合长期靠记忆维护。最后两层（托管配置 + MDM）一般只在企业部署里出现：如果你发现某些设置改不动，先用 `opencode debug config` 看实际生效值，确认是不是被托管配置接管了。

## 新手应该把配置放哪里

| 位置 | 适合放什么 | 不适合放什么 |
| --- | --- | --- |
| 全局配置 | 主题、个人偏好、个人默认模型 | 团队必须一致的规则 |
| 项目 `opencode.json` | 项目模型、tools、instructions、团队默认值 | 个人密钥、本机路径 |
| `.opencode/` | agents、commands、plugins、skills、themes | 杂乱临时笔记 |
| 环境变量 | 临时测试、CI、一次性覆盖 | 长期团队规范 |

如果一个设置只服务你自己，放全局；如果团队成员都应该遵守，放项目；如果只是临时试验，用环境变量，试完清理。

## 最小配置策略

第一次配置只需要解决一个问题：让 OpenCode 在当前项目里可控可用。

优先顺序：

1. 通过 `/connect` 配 provider 凭据。
2. 用 `/models` 确认模型可用。
3. 只在需要时写默认 `model`。
4. 只在团队需要共享时写项目 `opencode.json`。
5. 使用 schema 做校验。

不要为了“完整”一次性配置 TUI、server、tools、provider、theme、agent、MCP、formatter。改得越多，排错越难。

## tools 和 server 先保守

`tools` 会影响 Agent 能做什么，例如是否能写文件、运行 bash、访问外部工具。`server` 会影响 `opencode serve` 和 `opencode web` 的网络暴露方式。

新手原则：

- 不需要 Web 或远程访问，就不要改 server。
- 不理解风险前，不要放宽 tools。
- 需要浏览器客户端访问 server 时，才考虑 CORS（跨源资源共享白名单）。
- 共享配置里不要写只适合你本机的端口和 hostname。
- 如果要绑定 `0.0.0.0`，先处理认证和网络边界。

## 配置排错顺序

配置出问题时，先回到最小可用状态：

```text
确认 /connect 凭据
  ↓
确认 /models 能看到模型
  ↓
临时移除项目级复杂配置
  ↓
检查环境变量覆盖
  ↓
再逐项恢复 server / tools / provider options
```

不要一边改 provider、一边改 tools、一边改 server。一次只改一个变量，才能知道问题是谁引入的。

## 新手常见坑

- 全量复制官方 config 示例。
- 不知道配置会合并，误判某个旧设置已经失效。
- 把项目配置当个人配置用。
- 用环境变量覆盖后忘记清理。
- 不看 schema 提示，靠试错改 JSON。
- 一次改很多项，无法定位问题。

## 怎么判断配置健康

健康标准：

- 全局配置和项目配置职责分开。
- 项目 `opencode.json` 可以提交给团队。
- 本机私有信息没有进仓库。
- 当前模型、tools 和 instructions 来源可解释。
- 配置能通过 schema 校验。
- 出问题时可以回到最小配置重测。

## 接下来去哪

<Cards>
  <Card title="配置 Rules" description="把项目长期约束写清楚，不要靠每次临时提醒。" href="/docs/opencode/official/02-agents-skills/rules" />
  <Card title="选择模型" description="配置默认模型前，先确认 provider/model/variant 的官方边界。" href="/docs/opencode/official/03-models/models" />
  <Card title="工具总览" description="放宽工具能力前，先理解内置工具和 permission 的关系。" href="/docs/opencode/official/04-tools-mcp/tools" />
  <Card title="快捷键" description="TUI 体验类偏好放到 `tui.json`，不要和 OpenCode runtime 配置混在一起。" href="/docs/opencode/official/01-customization/keybinds" />
</Cards>

## 官方资料

- OpenCode Config：[https://opencode.ai/docs/config](https://opencode.ai/docs/config)
- OpenCode Models：[https://opencode.ai/docs/models](https://opencode.ai/docs/models)
- OpenCode Tools：[https://opencode.ai/docs/tools](https://opencode.ai/docs/tools)
- OpenCode Server：[https://opencode.ai/docs/server](https://opencode.ai/docs/server)
