OpenCode 配置文件 (opencode.json) 完全指南

opencode.json 是 OpenCode 的核心配置文件，掌控着 AI 编程助手从模型选择、工具权限到界面定制的所有行为。本文将从配置文件层级、完整配置项解析到高级实战技巧，带你彻底掌握 opencode.json 的全部能力。

配置文件层级

OpenCode 使用多层级配置合并机制，优先级从高到低为：

| 优先级 | 位置 | 作用范围 |
|--------|------|----------|
| 1（最高） | <项目>/.opencode/opencode.json | 仅当前项目 |
| 2 | <项目>/opencode.json | 当前项目（不推荐，会提交到 Git） |
| 3 | ~/.config/opencode/opencode.json | 全局，所有项目 |
| 4（最低） | 内置默认值 | 系统级 |

合并策略：高层级配置会覆盖低层级的同名配置项，但数组类配置通常为替换而非合并。

最佳实践

  • 全局配置放在 ~/.config/opencode/opencode.json，包含 API Key、默认模型等个人信息
  • 项目配置放在 <项目>/.opencode/opencode.json，包含项目特定的 Agent、命令、权限等
  • 将 .opencode/ 加入 .gitignore，避免团队成员的个性化配置互相覆盖

完整配置项解析

1. 模型与提供商配置

{
  "model": "claude-sonnet-4-20250514",
  "provider": {
    "id": "anthropic",
    "apiKey": "${ANTHROPIC_API_KEY}",
    "baseUrl": "https://api.anthropic.com"
  }
}
  • model：默认使用的模型名称，支持 provider/model 格式
  • provider.id：提供商名称（anthropic、openai、deepseek、ollama 等）
  • provider.apiKey：API 密钥，推荐使用环境变量 ${VAR} 语法
  • provider.baseUrl：API 端点地址，用于自定义代理或兼容接口
  • provider.options：传递给模型的额外参数

2. 多模型与备用策略

{
  "model": "claude-sonnet-4-20250514",
  "models": {
    "deepseek": {
      "provider": "deepseek",
      "model": "deepseek-chat",
      "options": {
        "temperature": 0.3,
        "maxOutputTokens": 8192
      }
    }
  },
  "lazy": true
}
  • models：预定义多个模型配置，可在对话中通过 --model 参数切换
  • lazy：延迟加载模型配置，仅在首次使用时连接提供商

3. Agent 系统配置

{
  "agent": "build",
  "agents": {
    "build": {
      "description": "全权限开发 Agent",
      "tools": ["*"],
      "permissions": {
        "edit": true,
        "bash": true,
        "network": true
      }
    },
    "reviewer": {
      "description": "专注于代码审查的只读 Agent",
      "tools": ["read", "grep", "glob"],
      "permissions": {
        "edit": false,
        "bash": false
      }
    }
  }
}
  • agent：默认启动的 Agent 名称
  • agents：自定义 Agent 定义，可配置名称、描述、可用工具和权限
  • permissions：细粒度权限控制（详见权限系统篇）

4. MCP 服务器配置

{
  "mcp": {
    "filesystem": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/data"]
    },
    "github": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "${GITHUB_TOKEN}"
      }
    },
    "remote-server": {
      "type": "sse",
      "url": "https://example.com/mcp/sse"
    }
  }
}
  • type：stdio（本地进程）或 sse（远程 SSE 服务）
  • command / args：stdio 类型的启动命令
  • url：sse 类型的远程地址
  • env：传递给 MCP 进程的环境变量

5. 权限与安全配置

{
  "permissions": {
    "edit": true,
    "bash": true,
    "network": true,
    "allow": [
      "src/**/*.ts",
      "!src/secrets/**"
    ],
    "deny": [
      ".env",
      "**/credentials.json"
    ],
    "ask": [
      "production/**"
    ]
  }
}
  • edit：是否允许编辑文件
  • bash：是否允许执行 Shell 命令
  • network：是否允许网络访问
  • allow：明确允许的路径模式
  • deny：明确拒绝的路径模式
  • ask：需要每次确认的模式

6. LSP 服务器配置

{
  "lsp": {
    "typescript": {
      "command": "typescript-language-server",
      "args": ["--stdio"]
    },
    "rust": {
      "command": "rust-analyzer"
    }
  }
}

配置 LSP 服务器后，OpenCode 可以获得语言级的代码理解能力，包括类型信息、引用跳转、诊断等。

7. 网络与代理配置

{
  "network": {
    "proxy": "http://127.0.0.1:7890",
    "proxyExclusions": ["localhost", "127.0.0.1", "*.internal.com"],
    "timeout": 60000
  }
}
  • proxy：HTTP 代理地址
  • proxyExclusions：不经过代理的地址列表
  • timeout：网络请求超时时间（毫秒）

8. 格式化器配置

{
  "formatters": {
    "prettier": {
      "command": "npx",
      "args": ["prettier", "--write"],
      "extensions": [".js", ".ts", ".jsx", ".tsx", ".json", ".md", ".css"]
    },
    "rustfmt": {
      "command": "rustfmt",
      "extensions": [".rs"]
    }
  },
  "formatOnSave": true
}
  • formatters：按编程语言指定格式化命令
  • formatOnSave：是否在 AI 修改文件后自动格式化

9. 快捷键配置

{
  "keybinds": {
    "submit": "Enter",
    "newline": "Alt+Enter",
    "switchAgent": "Tab",
    "toggleFiles": "Ctrl+O",
    "clearChat": "Ctrl+L",
    "cancel": "Escape"
  }
}

自定义终端 UI 的快捷键绑定。

10. 通知与提示配置

{
  "notifications": {
    "enabled": true,
    "sound": false,
    "onCompletion": true
  },
  "tips": {
    "enabled": true,
    "frequency": "low"
  }
}

控制 AI 任务完成后的通知和操作提示。

11. 会话与上下文配置

{
  "session": {
    "maxContextTokens": 200000,
    "autoSummarize": true,
    "summarizeThreshold": 0.8,
    "restore": true
  },
  "context": {
    "maxFiles": 50,
    "indexOnStart": true,
    "exclude": ["node_modules", "dist", ".git"]
  }
}
  • maxContextTokens：最大上下文 Token 数
  • autoSummarize：上下文超出时自动总结
  • restore：是否恢复上次会话
  • indexOnStart：启动时自动索引项目

12. 主题与界面配置

{
  "theme": "dracula",
  "themes": {
    "my-theme": {
      "colors": {
        "primary": "#6C5CE7",
        "background": "#1a1b26",
        "foreground": "#a9b1d6",
        "accent": "#7aa2f7",
        "error": "#f7768e",
        "warning": "#e0af68",
        "success": "#9ece6a"
      }
    }
  }
}
  • theme：使用的主题名称，内置主题包括 tokyo-night、dracula、nord、catppuccin 等
  • themes：自定义主题配色

13. 插件配置

{
  "plugins": {
    "my-plugin": {
      "path": "~/.config/opencode/plugins/my-plugin",
      "config": {
        "option1": "value"
      }
    }
  }
}

配置自定义插件路径和参数。

14. 高级选项

{
  "advanced": {
    "debug": false,
    "logLevel": "info",
    "tmpDir": "/tmp/opencode",
    "sandbox": false,
    "maxConcurrency": 4
  }
}
  • debug：启用调试模式，输出更详细的日志
  • logLevel：日志级别（debug、info、warn、error）
  • sandbox：沙盒模式，限制文件操作范围
  • maxConcurrency：最大并发任务数

环境变量引用

opencode.json 中支持使用 ${VAR} 或 ${VAR:-default} 语法引用环境变量，避免敏感信息直接写入配置文件：

{
  "provider": {
    "apiKey": "${ANTHROPIC_API_KEY}"
  },
  "mcp": {
    "github": {
      "env": {
        "GITHUB_TOKEN": "${GITHUB_TOKEN:-fallback_token}"
      }
    }
  }
}

完整配置示例

以下是一个生产级别的 opencode.json 配置示例：

{
  "model": "claude-sonnet-4-20250514",
  "agent": "build",
  "provider": {
    "id": "anthropic",
    "apiKey": "${ANTHROPIC_API_KEY}",
    "baseUrl": "https://api.anthropic.com"
  },
  "models": {
    "deepseek": {
      "provider": "deepseek",
      "model": "deepseek-chat",
      "options": { "temperature": 0.3 }
    },
    "local": {
      "provider": "ollama",
      "model": "qwen2.5-coder:14b"
    }
  },
  "permissions": {
    "deny": [".env", "**/secrets/**", "*.key"]
  },
  "formatters": {
    "prettier": {
      "command": "npx",
      "args": ["prettier", "--write"],
      "extensions": [".js", ".ts", ".json", ".md"]
    }
  },
  "formatOnSave": true,
  "session": {
    "maxContextTokens": 180000,
    "autoSummarize": true
  },
  "context": {
    "exclude": ["node_modules", "dist", ".git", "vendor"]
  },
  "theme": "tokyo-night",
  "advanced": {
    "logLevel": "info",
    "debug": false
  }
}

配置验证

你可以通过以下命令验证配置文件的语法正确性：

opencode config validate

如果配置有问题，OpenCode 会在启动时给出明确的错误提示。

小结

opencode.json 是 OpenCode 的中枢神经，几乎所有的行为都可以通过它来定制。掌握本文中的配置项，你就能将 OpenCode 调教成最适合自己工作流的 AI 编程助手。下一篇我们将深入 OpenCode 的主题、界面与快捷键定制，打造专属的终端编程美学体验。

叶云梦天

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