Перейти к содержимому
OpenCode
app.header.homeapp.header.docs

Агенты

Настройте и используйте специализированные агенты.

Агенты — это специализированные ИИ-помощники, которых можно настроить для конкретных задач и рабочих процессов. Они позволяют создавать специализированные инструменты с настраиваемыми подсказками, моделями и доступом к инструментам.

Вы можете переключаться между агентами во время сеанса или вызывать их с помощью упоминания @.

Типы

В opencode есть два типа агентов; Первичные агенты и субагенты.

Первичные агенты

Первичные агенты — это основные помощники, с которыми вы взаимодействуете напрямую. Вы можете переключаться между ними, используя клавишу Tab или настроенную привязку клавиш switch_agent. Эти агенты ведут ваш основной разговор. Доступ к инструментам настраивается с помощью разрешений — например, при сборке все инструменты включены, а при планировании — ограничены.

opencode поставляется с двумя встроенными основными агентами: Build и Plan. Хорошо посмотрите на это ниже.

Субагенты

Субагенты — это специализированные помощники, которых основные агенты могут вызывать для выполнения определенных задач. Вы также можете вызвать их вручную, @ упомянув их в своих сообщениях.

opencode поставляется с двумя встроенными субагентами: General и Explore. Мы рассмотрим это ниже.

Встроенный

opencode поставляется с двумя встроенными основными агентами и двумя встроенными субагентами.

Use Build

Режим: primary

Build — основной агент по умолчанию со всеми включенными инструментами. Это стандартный агент для разработки, где вам необходим полный доступ к файловым операциям и системным командам.

Use Plan

Режим: primary

Агент с ограниченным доступом, предназначенный для планирования и анализа. Мы используем систему разрешений, чтобы предоставить вам больше контроля и предотвратить непреднамеренные изменения. По умолчанию для всех следующих параметров установлено значение ask:

  • file edits: Все записи, исправления и изменения.
  • bash: все команды bash.

Этот агент полезен, если вы хотите, чтобы LLM анализировал код, предлагал изменения или создавал планы без внесения каких-либо фактических изменений в вашу кодовую базу.

Use General

Режим: subagent

Универсальный агент для исследования сложных вопросов и выполнения многоэтапных задач. Имеет полный доступ к инструментам (кроме задач), поэтому при необходимости может вносить изменения в файлы. Используйте это для параллельного выполнения нескольких единиц работы.

Use Explore

Режим: subagent

Быстрый агент только для чтения для изучения кодовых баз. Невозможно изменить файлы. Используйте это, когда вам нужно быстро найти файлы по шаблонам, выполнить поиск кода по ключевым словам или ответить на вопросы о кодовой базе.

Use Compact

Режим: primary

Скрытый системный агент, который сжимает длинный контекст в меньшее резюме. Он запускается автоматически при необходимости и не может быть выбран в пользовательском интерфейсе.

Use Title

Режим: primary

Скрытый системный агент, генерирующий короткие заголовки сессий. Он запускается автоматически и не может быть выбран в пользовательском интерфейсе.

Use Summary

Режим: primary

Скрытый системный агент, создающий сводки сеансов. Он запускается автоматически и не может быть выбран в пользовательском интерфейсе.

Использование

  1. Для основных агентов используйте клавишу Tab для переключения между ними во время сеанса. Вы также можете использовать настроенную привязку клавиш switch_agent.

  2. Субагенты могут быть вызваны:

    • Автоматически основными агентами для выполнения специализированных задач на основе их описаний.

    • Вручную, @ упомянув субагента в своем сообщении. Например.

      @general help me search for this function

  3. Навигация между сеансами. Когда субагенты создают свои собственные дочерние сеансы, вы можете перемещаться между родительским сеансом и всеми дочерними сеансами, используя:

    • <Leader>+Right (или настроенная вами комбинация клавиш session_child_cycle) для перехода вперед через родительский элемент → дочерний элемент1 → дочерний элемент2 → … → родительский элемент.
    • <Leader>+Left (или настроенная вами комбинация клавиш session_child_cycle_reverse) для перехода назад по родительскому элементу ← дочерний элемент1 ← дочерний элемент2 ← … ← родительский элемент

    Это позволяет плавно переключаться между основным разговором и работой специализированного субагента.

Настроить

Вы можете настроить встроенные агенты или создать свои собственные посредством настройки. Агенты можно настроить двумя способами:

JSON

Настройте агентов в файле конфигурации opencode.json:

opencode.json
{
  "$schema": "https://opencode.ai/config.json",
  "agent": {
    "build": {
      "mode": "primary",
      "model": "anthropic/claude-sonnet-4-20250514",
      "prompt": "{file:./prompts/build.txt}",
      "tools": {
        "write": true,
        "edit": true,
        "bash": true
      }
    },
    "plan": {
      "mode": "primary",
      "model": "anthropic/claude-haiku-4-20250514",
      "tools": {
        "write": false,
        "edit": false,
        "bash": false
      }
    },
    "code-reviewer": {
      "description": "Reviews code for best practices and potential issues",
      "mode": "subagent",
      "model": "anthropic/claude-sonnet-4-20250514",
      "prompt": "You are a code reviewer. Focus on security, performance, and maintainability.",
      "tools": {
        "write": false,
        "edit": false
      }
    }
  }
}

Markdown

Вы также можете определить агентов, используя файлы Markdown. Поместите их в:

  • Глобальный: ~/.config/opencode/agents/
  • Для каждого проекта: .opencode/agents/
~/.config/opencode/agents/review.md
---
description: Reviews code for quality and best practices
mode: subagent
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.

Параметры

Давайте рассмотрим эти параметры конфигурации подробно.

Описание

Используйте опцию description, чтобы предоставить краткое описание того, что делает агент и когда его использовать.

opencode.json
{
  "agent": {
    "review": {
      "description": "Reviews code for best practices and potential issues"
    }
  }
}

Это обязательный параметр конфигурации.

Температура

Контролируйте случайность и креативность ответов LLM с помощью конфигурации temperature.

Более низкие значения делают ответы более целенаправленными и детерминированными, а более высокие значения повышают креативность и вариативность.

opencode.json
{
  "agent": {
    "plan": {
      "temperature": 0.1
    },
    "creative": {
      "temperature": 0.8
    }
  }
}

Значения температуры обычно находятся в диапазоне от 0,0 до 1,0:

  • 0,0–0,2: очень целенаправленные и детерминированные ответы, идеальные для анализа кода и планирования.
  • 0,3–0,5: сбалансированные ответы с некоторой креативностью, подходят для общих задач развития.
  • 0,6–1,0: более творческие и разнообразные ответы, полезные для мозгового штурма и исследования.
opencode.json
{
  "agent": {
    "analyze": {
      "temperature": 0.1,
      "prompt": "{file:./prompts/analysis.txt}"
    },
    "build": {
      "temperature": 0.3
    },
    "brainstorm": {
      "temperature": 0.7,
      "prompt": "{file:./prompts/creative.txt}"
    }
  }
}

Если температура не указана, opencode использует значения по умолчанию, специфичные для модели; обычно 0 для большинства моделей, 0,55 для моделей Qwen.

Максимальное количество шагов

Управляйте максимальным количеством агентных итераций, которые агент может выполнить, прежде чем ему придется отвечать только текстом. Это позволяет пользователям, желающим контролировать расходы, устанавливать лимит на агентские действия.

Если этот параметр не установлен, агент будет продолжать выполнять итерацию до тех пор, пока модель не решит остановиться или пока пользователь не прервет сеанс.

opencode.json
{
  "agent": {
    "quick-thinker": {
      "description": "Fast reasoning with limited iterations",
      "prompt": "You are a quick thinker. Solve problems with minimal steps.",
      "steps": 5
    }
  }
}

При достижении лимита агент получает специальную системную подсказку с указанием в ответ краткой информации о своей работе и рекомендуемых оставшихся задачах.

Запрещать

Установите true, чтобы отключить агент.

opencode.json
{
  "agent": {
    "review": {
      "disable": true
    }
  }
}

Prompt

Укажите собственный файл системных приглашений для этого агента с помощью конфигурации prompt. Файл подсказки должен содержать инструкции, специфичные для целей агента.

opencode.json
{
  "agent": {
    "review": {
      "prompt": "{file:./prompts/code-review.txt}"
    }
  }
}

Этот путь указан относительно того, где находится файл конфигурации. Таким образом, это работает как для глобальной конфигурации opencode, так и для конфигурации конкретного проекта.

Модель

Используйте конфигурацию model, чтобы переопределить модель этого агента. Полезно для использования разных моделей, оптимизированных под разные задачи. Например, более быстрая модель планирования и более эффективная модель реализации.

opencode.json
{
  "agent": {
    "plan": {
      "model": "anthropic/claude-haiku-4-20250514"
    }
  }
}

Идентификатор модели в вашей конфигурации opencode использует формат provider/model-id. Например, если вы используете OpenCode Zen, вы должны использовать opencode/gpt-5.1-codex для кодекса GPT 5.1.

Инструменты

Контролируйте, какие инструменты доступны в этом агенте, с помощью конфигурации tools. Вы можете включить или отключить определенные инструменты, установив для них значение true или false.

opencode.json
{
  "$schema": "https://opencode.ai/config.json",
  "tools": {
    "write": true,
    "bash": true
  },
  "agent": {
    "plan": {
      "tools": {
        "write": false,
        "bash": false
      }
    }
  }
}

Вы также можете использовать подстановочные знаки для одновременного управления несколькими инструментами. Например, чтобы отключить все инструменты с сервера MCP:

opencode.json
{
  "$schema": "https://opencode.ai/config.json",
  "agent": {
    "readonly": {
      "tools": {
        "mymcp_*": false,
        "write": false,
        "edit": false
      }
    }
  }
}

Подробнее об инструментах.

Разрешения

Вы можете настроить разрешения, чтобы управлять действиями, которые может выполнять агент. В настоящее время разрешения для инструментов edit, bash и webfetch можно настроить на:

  • "ask" — Запросить подтверждение перед запуском инструмента.
  • "allow" — Разрешить все операции без одобрения.
  • "deny" — отключить инструмент
opencode.json
{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
    "edit": "deny"
  }
}

Вы можете переопределить эти разрешения для каждого агента.

opencode.json
{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
    "edit": "deny"
  },
  "agent": {
    "build": {
      "permission": {
        "edit": "ask"
      }
    }
  }
}

Вы также можете установить разрешения в агентах Markdown.

~/.config/opencode/agents/review.md
---
description: Code review without edits
mode: subagent
permission:
  edit: deny
  bash:
    "*": ask
    "git diff": allow
    "git log*": allow
    "grep *": allow
  webfetch: deny
---


Only analyze code and suggest changes.

Вы можете установить разрешения для определенных команд bash.

opencode.json
{
  "$schema": "https://opencode.ai/config.json",
  "agent": {
    "build": {
      "permission": {
        "bash": {
          "git push": "ask",
          "grep *": "allow"
        }
      }
    }
  }
}

Это может использовать glob pattern.

opencode.json
{
  "$schema": "https://opencode.ai/config.json",
  "agent": {
    "build": {
      "permission": {
        "bash": {
          "git *": "ask"
        }
      }
    }
  }
}

Вы также можете использовать подстановочный знак * для управления разрешениями для всех команд. Поскольку последнее правило сопоставления имеет приоритет, сначала поместите подстановочный знак *, а затем конкретные правила.

opencode.json
{
  "$schema": "https://opencode.ai/config.json",
  "agent": {
    "build": {
      "permission": {
        "bash": {
          "*": "ask",
          "git status *": "allow"
        }
      }
    }
  }
}

Подробнее о разрешениях.

Режим

Управляйте режимом агента с помощью конфигурации mode. Опция mode используется для определения того, как можно использовать агент.

opencode.json
{
  "agent": {
    "review": {
      "mode": "subagent"
    }
  }
}

Опция mode может быть установлена ​​на primary, subagent или all. Если mode не указан, по умолчанию используется all.

Скрытый

Скройте субагент из меню автозаполнения @ с помощью hidden: true. Полезно для внутренних субагентов, которые другие агенты должны вызывать только программно с помощью инструмента Task.

opencode.json
{
  "agent": {
    "internal-helper": {
      "mode": "subagent",
      "hidden": true
    }
  }
}

Это влияет только на видимость пользователя в меню автозаполнения. Скрытые агенты по-прежнему могут быть вызваны моделью с помощью инструмента «Задачи», если разрешения позволяют.

Разрешения задач

Управляйте тем, какие субагенты агент может вызывать с помощью инструмента задач с помощью permission.task. Использует шаблоны glob для гибкого сопоставления.

opencode.json
{
  "agent": {
    "orchestrator": {
      "mode": "primary",
      "permission": {
        "task": {
          "*": "deny",
          "orchestrator-*": "allow",
          "code-reviewer": "ask"
        }
      }
    }
  }
}

Если установлено значение deny, субагент полностью удаляется из описания инструмента «Задача», поэтому модель не будет пытаться его вызвать.

Цвет

Настройте внешний вид агента в пользовательском интерфейсе с помощью параметра color. Это влияет на то, как агент будет отображаться в интерфейсе.

Используйте допустимый шестнадцатеричный цвет (например, #FF5733) или цвет темы: primary, secondary, accent, success, warning, error, info.

opencode.json
{
  "agent": {
    "creative": {
      "color": "#ff6b6b"
    },
    "code-reviewer": {
      "color": "accent"
    }
  }
}

Top P

Управляйте разнообразием ответов с помощью опции top_p. Альтернатива температуре для контроля случайности.

opencode.json
{
  "agent": {
    "brainstorm": {
      "top_p": 0.9
    }
  }
}

Значения варьируются от 0,0 до 1,0. Низкие ценности более целенаправленны, высшие ценности более разнообразны.

Extra

Любые другие параметры, указанные вами в конфигурации вашего агента, будут передаваться напрямую поставщику в качестве параметров модели. Это позволяет использовать функции и параметры, специфичные для поставщика.

Например, с помощью моделей рассуждения OpenAI вы можете контролировать усилия по рассуждению:

opencode.json
{
  "agent": {
    "deep-thinker": {
      "description": "Agent that uses high reasoning effort for complex problems",
      "model": "openai/gpt-5",
      "reasoningEffort": "high",
      "textVerbosity": "low"
    }
  }
}

Эти дополнительные параметры зависят от модели и поставщика. Проверьте документацию вашего провайдера на наличие доступных параметров.

Создание агентов

Вы можете создать новых агентов, используя следующую команду:

Окно терминала
opencode agent create

Эта интерактивная команда:

  1. Спросить, где сохранить агента; глобальный или специфичный для проекта.
  2. Описание того, что должен делать агент.
  3. Создайте соответствующее системное приглашение и идентификатор.
  4. Позволяет вам выбрать, к каким инструментам может получить доступ агент.
  5. Наконец, создайте файл Markdown с конфигурацией агента.

Варианты использования

Вот несколько распространенных случаев использования различных агентов.

  • Агент сборки: полная работа по разработке со всеми включенными инструментами.
  • Агент планирования: анализ и планирование без внесения изменений.
  • Агент проверки: проверка кода с доступом только для чтения и инструментами документирования.
  • Агент отладки: сосредоточен на исследовании с включенными инструментами bash и чтения.
  • Агент документов: запись документации с помощью файловых операций, но без системных команд.

Примеры

Вот несколько примеров агентов, которые могут оказаться вам полезными.

Агент документации

~/.config/opencode/agents/docs-writer.md
---
description: Writes and maintains project documentation
mode: subagent
tools:
  bash: false
---


You are a technical writer. Create clear, comprehensive documentation.


Focus on:


- Clear explanations
- Proper structure
- Code examples
- User-friendly language

Аудитор безопасности

~/.config/opencode/agents/security-auditor.md
---
description: Performs security audits and identifies vulnerabilities
mode: subagent
tools:
  write: false
  edit: false
---


You are a security expert. Focus on identifying potential security issues.


Look for:


- Input validation vulnerabilities
- Authentication and authorization flaws
- Data exposure risks
- Dependency vulnerabilities
- Configuration security issues