Modes - OpenCode Docs | OpenCode Tutorial

:::caution 现在通过 opencode 配置中的 agent 选项配置模式。 mode 选项现已弃用。了解更多。 :::

opencode 中的模式允许您自定义不同用例的行为、工具和提示。

它带有两个内置模式：build 和 plan。您可以通过 opencode 配置自定义这些模式或配置您自己的模式。

您可以在会话期间切换模式，也可以在配置文件中配置它们。

##内置模式

opencode 带有两个内置模式。

###Build

Build 是默认模式，启用了所有工具。这是开发工作的标准模式，您需要完全访问文件操作和系统命令。

###Plan

一种受限模式，专为规划和分析而设计。在 plan 模式下，默认情况下禁用以下工具：

write - 无法创建新文件
edit - 无法修改现有文件，除了位于 .opencode/plans/*.md 的文件，用于详细说明计划本身
patch - 无法应用补丁
bash - 无法执行 shell 命令

当您希望 AI 分析代码、建议更改或创建计划而不对代码库进行任何实际修改时，此模式非常有用。

##切换

您可以使用 Tab 键在会话期间切换模式。或者您配置的 switch_mode 快捷键。

另请参阅：格式化程序，了解有关代码格式配置的信息。

##配置

您可以通过配置自定义内置模式或创建自己的模式。可以通过两种方式配置模式：

###JSON 配置

在您的 opencode.json 配置文件中配置模式：

bash

{
  "$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/

bash

---
model: anthropic/claude-sonnet-4-20250514
temperature: 0.1
tools:
  write: false
  edit: false
  bash: false
---

You are in code review mode. Focus on:

- Code quality and best practices
- Potential bugs and edge cases
- Performance implications
- Security considerations

Provide constructive feedback without making direct changes.

markdown 文件名将成为模式名称（例如，review.md 创建一个 review 模式）。

让我们详细了解这些配置选项。

###Model

使用 model 配置覆盖此模式的默认模型。适用于使用针对不同任务优化的不同模型。例如，用于规划的更快模型，用于实施的更强大的模型。

bash

{
  "mode": {
    "plan": {
      "model": "anthropic/claude-haiku-4-20250514"
    }
  }
}

###Temperature

使用 temperature 配置控制 AI 响应的随机性和创造力。较低的值使响应更加集中和确定，而较高的值会增加创造力和可变性。

bash

{
  "mode": {
    "plan": {
      "temperature": 0.1
    },
    "creative": {
      "temperature": 0.8
    }
  }
}

温度值通常在 0.0 到 1.0 之间：

0.0-0.2：非常集中和确定的响应，非常适合代码分析和规划
0.3-0.5：平衡的响应，具有一定的创造力，适用于一般开发任务
0.6-1.0：更具创造性和多样性的响应，可用于集思广益和探索

bash

{
  "mode": {
    "analyze": {
      "temperature": 0.1,
      "prompt": "{file:./prompts/analysis.txt}"
    },
    "build": {
      "temperature": 0.3
    },
    "brainstorm": {
      "temperature": 0.7,
      "prompt": "{file:./prompts/creative.txt}"
    }
  }
}

如果未指定温度，opencode 将使用特定于模型的默认值（对于大多数模型通常为 0，对于 Qwen 模型为 0.55）。

###Prompt

使用 prompt 配置为此模式指定自定义系统提示文件。提示文件应包含特定于模式用途的说明。

bash

{
  "mode": {
    "review": {
      "prompt": "{file:./prompts/code-review.txt}"
    }
  }
}

此路径相对于配置文件所在的位置。因此，这适用于全局 opencode 配置和项目特定配置。

###Tools

使用 tools 配置控制此模式下可用的工具。您可以通过将特定工具设置为 true 或 false 来启用或禁用它们。

bash

{
  "mode": {
    "readonly": {
      "tools": {
        "write": false,
        "edit": false,
        "bash": false,
        "read": true,
        "grep": true,
        "glob": true
      }
    }
  }
}

如果未指定任何工具，则默认情况下启用所有工具。

可用工具

以下是可以通过模式配置控制的所有工具。

| 工具 | 描述 | | ----------- | ----------------------- | | bash | 执行 shell 命令 | | edit | 修改现有文件 | | write | 创建新文件 | | read | 读取文件内容 | | grep | 搜索文件内容 | | glob | 按模式查找文件 | | list | 列出目录内容 | | patch | 将补丁应用于文件 | | todowrite | 管理 todo 列表 | | todoread | 读取 todo 列表 | | webfetch | 获取 Web 内容 |

##自定义模式

您可以通过将自定义模式添加到配置来创建它们。以下是使用两种方法的示例：

###使用 JSON 配置

bash

{
  "$schema": "https://opencode.ai/config.json",
  "mode": {
    "docs": {
      "prompt": "{file:./prompts/documentation.txt}",
      "tools": {
        "write": true,
        "edit": true,
        "bash": false,
        "read": true,
        "grep": true,
        "glob": true
      }
    }
  }
}

###使用 markdown 文件

在 .opencode/modes/ 中创建模式文件以用于项目特定模式，或在 ~/.config/opencode/modes/ 中创建模式文件以用于全局模式：

bash

---
temperature: 0.1
tools:
  bash: true
  read: true
  grep: true
  write: false
  edit: false
---

You are in debug mode. Your primary goal is to help investigate and diagnose issues.

Focus on:

- Understanding the problem through careful analysis
- Using bash commands to inspect system state
- Reading relevant files and logs
- Searching for patterns and anomalies
- Providing clear explanations of findings

Do not make any changes to files. Only investigate and report.

bash

---
model: anthropic/claude-sonnet-4-20250514
temperature: 0.2
tools:
  edit: true
  read: true
  grep: true
  glob: true
---

You are in refactoring mode. Focus on improving code quality without changing functionality.

Priorities:

- Improve code readability and maintainability
- Apply consistent naming conventions
- Reduce code duplication
- Optimize performance where appropriate
- Ensure all tests continue to pass

###用例

以下是不同模式的一些常见用例。

Build 模式：启用所有工具的完整开发工作
Plan 模式：分析和规划，无需进行任何更改
Review 模式：代码审查，具有只读访问权限以及文档工具
Debug 模式：专注于使用 bash 和读取工具进行调查
Docs 模式：文档编写，具有文件操作权限，但没有系统命令

您可能还会发现不同的模型适用于不同的用例。