Appearance
OpenCode 的 Modes 功能让你为不同场景配置不同的 AI 行为。内置 Build（全功能开发）和 Plan（只读分析规划）两种模式，也可以通过配置文件创建自定义模式，指定模型、temperature、系统 Prompt 和可用工具。
注意：Modes 功能目前通过
agent选项在 opencode 配置中进行设置，mode选项已废弃。详见 Agents 文档。
OpenCode 的模式系统让你根据任务类型定制 AI 的行为——使用什么模型、开放哪些工具权限、遵循什么系统提示。
内置模式
Build（默认）
全功能开发模式，所有工具均可用。这是标准的开发模式，适合需要文件操作和命令执行的场景。
Plan
规划分析模式，以下工具默认禁用：
| 工具 | 说明 |
|---|---|
write | 不能创建新文件 |
edit | 不能修改现有文件（.opencode/plans/*.md 除外） |
patch | 不能应用 patch |
bash | 不能执行 Shell 命令 |
Plan 模式适合需要 AI 分析代码、提出建议或制定计划，但不希望它直接修改代码库的场景。
切换模式
在会话中按 Tab 键（或配置的 switch_mode 快捷键）可以在模式之间切换。
配置
JSON 配置
在 opencode.json 中配置：
json
{
"$schema": "https://opencode.ai/config.json",
"mode": {
"build": {
"model": "anthropic/claude-sonnet-4-20250514",
"prompt": "{file:./prompts/build.txt}",
"tools": {
"write": true,
"edit": true,
"bash": true
}
},
"plan": {
"model": "anthropic/claude-haiku-4-20250514",
"tools": {
"write": false,
"edit": false,
"bash": false
}
}
}
}Markdown 配置
也可以用 Markdown 文件定义模式，文件名即模式名：
- 全局：
~/.config/opencode/modes/ - 项目级：
.opencode/modes/
markdown
---
model: anthropic/claude-sonnet-4-20250514
temperature: 0.1
tools:
write: false
edit: false
bash: false
---
你处于代码审查模式。请关注：
- 代码质量和最佳实践
- 潜在 Bug 和边界情况
- 性能影响
- 安全考量
提供建设性反馈，不要直接修改代码。上面的文件命名为 review.md 即创建了 review 模式。
Model
为特定模式覆盖默认模型，不同任务使用不同能力的模型：
json
{
"mode": {
"plan": {
"model": "anthropic/claude-haiku-4-20250514"
}
}
}Temperature
控制 AI 响应的随机性和创造性（通常 0.0 ~ 1.0）：
| 范围 | 特点 | 适用场景 |
|---|---|---|
| 0.0-0.2 | 专注确定性强 | 代码分析、规划 |
| 0.3-0.5 | 平衡适中 | 通用开发任务 |
| 0.6-1.0 | 更有创意 | 头脑风暴、探索 |
json
{
"mode": {
"analyze": { "temperature": 0.1 },
"build": { "temperature": 0.3 },
"brainstorm": { "temperature": 0.7 }
}
}未指定时使用模型默认值（大多数模型为 0，Qwen 系列为 0.55）。
Prompt
为模式指定系统 Prompt 文件（相对于配置文件位置）：
json
{
"mode": {
"review": {
"prompt": "{file:./prompts/code-review.txt}"
}
}
}Tools
控制模式下可用的工具：
json
{
"mode": {
"readonly": {
"tools": {
"write": false,
"edit": false,
"bash": false,
"read": true,
"grep": true,
"glob": true
}
}
}
}可控制的内置工具：
| 工具 | 功能 |
|---|---|
bash | 执行 Shell 命令 |
edit | 修改现有文件 |
write | 创建新文件 |
read | 读取文件内容 |
grep | 搜索文件内容 |
glob | 按模式查找文件 |
patch | 应用 patch |
todowrite | 管理待办列表 |
webfetch | 抓取网页内容 |
未指定时默认开启所有工具。
自定义模式示例
调试模式（只读 + 可运行命令）
markdown
---
temperature: 0.1
tools:
bash: true
read: true
grep: true
write: false
edit: false
---
你处于调试模式。通过仔细分析来调查和诊断问题。
使用 bash 命令检查系统状态，读取相关文件和日志。
不要修改任何文件，只调查并报告发现。重构模式
markdown
---
model: anthropic/claude-sonnet-4-20250514
temperature: 0.2
tools:
edit: true
read: true
grep: true
glob: true
---
你处于重构模式。在不改变功能的前提下提升代码质量。
优先改善可读性和可维护性，减少代码重复，确保所有测试继续通过。常见问题
Q: Modes 和 Agents 有什么区别？
A: 两者功能类似，但 Agents 是推荐的新方式（Modes 已废弃）。Agents 支持更丰富的配置，包括子 Agent 编排。如果你正在新建配置，直接用 Agents 即可。
Q: 会话中途切换模式会影响已有的对话历史吗？
A: 不会，切换模式只影响后续 AI 响应的工具权限和模型，已有对话历史保持不变。
Q: 可以给同一个项目配置多个自定义模式吗？
A: 可以。在 .opencode/modes/ 目录下创建多个 Markdown 文件，或在 opencode.json 的 mode 对象中添加多个条目即可。