Configuración detallada del agente de OpenCode (Agent)

Un agente es un asistente de IA especializado dentro de OpenCode. Cada agente puede configurarse con un mensaje de sistema independiente, modelo, permisos de acceso a herramientas y restricciones de comportamiento, para manejar tipos específicos de tareas y flujos de trabajo. Puedes cambiar de agente en cualquier momento durante una sesión, o mediante@nombre del agentela forma de invocar directamente a un agente específico.

Tipos de agentes

Los agentes en OpenCode se dividen en dos tipos, con diferentes formas de invocación y responsabilidades:

Tipo Descripción Método de cambio
Agente principal (primary) El asistente principal con el que interactúas directamente, gestiona el flujo principal de la conversación. El acceso a las herramientas se realiza mediantepermissionconfiguración segúnTabde la tecla para cambiar cíclicamente, o usar laagent_cycletecla de acceso rápido configurada.
Subagente (subagent) Asistente invocado por el agente principal para realizar tareas especializadas; se ejecuta en una subsesión independiente y no afecta el contexto de la sesión principal. El agente principal lo invoca automáticamente, o en un mensaje se usa@nombre del agentela invocación manual.

Agentes integrados

OpenCode incluye 4 agentes listos para usar y 3 agentes de sistema que se ejecutan automáticamente:

1. Build (agente principal)

El agente principal predeterminado, con todas las herramientas habilitadas, adecuado para el trabajo de desarrollo diario que requiere acceso completo a operaciones de archivos y comandos del sistema. Es el agente que usarás con más frecuencia.

2. Plan (agente principal)

Un agente restringido diseñado para análisis de código y planificación. De forma predeterminada, las siguientes acciones activan una solicitud de aprobación (configúralo enask）：

  • file edits: todas las operaciones de escritura, parches y edición
  • bash: todos los comandos bash

Cuando quieras que el LLM analice el código, haga sugerencias o cree un plan de ejecución, pero no quieras que realice modificaciones reales en el código, cambia al agente Plan.

3. General (subagente)

Subagente general con acceso completo a las herramientas (excepto la herramienta todo); puede modificar archivos. Es adecuado para investigar problemas complejos y ejecutar tareas de varios pasos, y también puede ejecutar varias unidades de trabajo independientes en paralelo.

4. Explore (subagente)

Subagente de solo lectura, no puede modificar ningún archivo. Adecuado para encontrar archivos rápidamente, buscar palabras clave en el código o responder preguntas sobre la estructura del repositorio; es rápido y no tiene efectos secundarios.

5. Agente de sistema (oculto)

Los siguientes tres agentes son gestionados automáticamente por OpenCode,no aparecen en la lista de cambio de agentes, no es necesario ni es posible seleccionarlos manualmente:

Nombre del agente Responsabilidad Momento de activación
Compaction Comprime contextos demasiado largos en resúmenes más pequeños para evitar superar el límite de contexto del modelo. Se ejecuta automáticamente cuando la longitud del contexto alcanza el umbral.
Title Genera un título breve para la sesión. Se ejecuta automáticamente después de que comienza una nueva sesión.
Summary Crea un resumen de la sesión. Se ejecuta automáticamente cuando se necesita un resumen de la sesión.

Cómo usar los agentes

1. Cambiar de agente principal

Durante una sesión, presionaTabla tecla para cambiar cíclicamente entre todos los agentes principales; presionaShift+Tabpara cambiar en sentido inverso. También puedes usar<Leader>apara abrir la lista de agentes y seleccionar directamente.

2. Invocar subagentes

Hay dos formas de invocar subagentes:

  • Invocación automática: Cuando el agente principal determina que necesita un subagente según la naturaleza de la tarea, lo invoca automáticamente y le delega la tarea.
  • Invocación manual con @: En un mensaje, usa@nombre del agentepara especificar directamente qué subagente debe encargarse.
@general help me search for this function across the codebase

3. Navegar entre sesiones padre e hijo

Cuando se ejecuta un subagente, se crea una subsesión independiente. Puedes usar atajos de teclado para navegar entre la sesión padre y las subsesiones:

Atajo de teclado Acción
<Leader>+→（session_child_cycle） Ciclo hacia adelante: sesión padre → subsesión 1 → subsesión 2 → … → sesión padre
<Leader>+←（session_child_cycle_reverse） Ciclo hacia atrás: sesión padre ← subsesión 1 ← subsesión 2 ← … ← sesión padre
<Leader>+↑（session_parent） Volver directamente a la sesión padre

Dos formas de configuración

Los agentes se pueden definir mediante configuración JSON o archivos Markdown, con el mismo efecto; elige la que necesites:

Forma 1: Configurar en opencode.json

Ejemplo

{
  "$schema": "https://opencode.ai/config.json",
  "agent": {
    "build": {                                           // Sobrescribe la configuración del agente integrado build
      "mode": "primary",
      "model": "anthropic/claude-sonnet-4-20250514",
      "prompt": "{file:./prompts/build.txt}",           // Carga el mensaje de sistema desde un archivo
      "tools": {
        "write": true,
        "edit": true,
        "bash": true
      }
    },
    "code-reviewer": {                                   // Subagente personalizado
      "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
      }
    }
  }
}

Forma 2: Archivo Markdown

Crea en la siguiente ruta.mdun archivo,el nombre del archivo es el nombre del agente(por ejemplo,review.mdcorresponde al nombre del agentereview）：

  • Global:~/.config/opencode/agents/(válido para todos los proyectos)
  • A nivel de proyecto:.opencode/agents/(válido solo para el proyecto actual)

Ejemplo

# Ruta del archivo: ~/.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.

Explicación detallada de las opciones de configuración

description (descripción)

Descripción de la función del agente; se muestra en la lista de agentes y en el@menú de autocompletado. Ayuda a los usuarios y al agente principal a decidir cuándo invocar este agente. Para agentes personalizados, este campo esobligatorio：

Ejemplo

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

mode (modo)

Controla la forma de uso del agente. Se puede establecer en uno de los siguientes tres valores:

Valor Descripción
"primary" Agente principal, aparece en la lista de alternancia con Tab, se usa para la conversación principal.
"subagent" Subagente, no aparece en la lista de alternancia con Tab, es invocado por el agente principal o manualmente mediante @.
"all" Se usa tanto como agente principal como subagente (valor predeterminado cuando no se especifica mode).

Ejemplo

{
  "agent": {
    "review": {
      "mode": "subagent"    // Se usa solo como subagente, no aparece en la lista de cambio de agentes principales
    }
  }
}

model (modelo)

Especifica un modelo concreto para el agente, sobrescribiendo el modelo predeterminado de la configuración global. El formato esprovider/model-id. Es adecuado para usar diferentes modelos según la tarea; por ejemplo, modelos pequeños más rápidos para tareas de planificación y modelos grandes más potentes para generación de código:

Ejemplo

{
  "agent": {
    "plan": {
      "model": "anthropic/claude-haiku-4-20250514"    // Usa el modelo Haiku, más rápido, para tareas de planificación
    },
    "build": {
      "model": "anthropic/claude-sonnet-4-20250514"   // Usa el modelo Sonnet, más capaz, para tareas de desarrollo
    }
  }
}

Si no se especificamodel, el agente principal usará el modelo predeterminado de la configuración global, y el subagente heredará el modelo del agente principal que lo invocó. Ejecutaropencode modelsPuedes ver la lista de todos los modelos disponibles.

prompt (mensaje del sistema)

Especifica un prompt de sistema personalizado para el agente; puedes escribir una cadena directamente, o también puedes usar{file:./路径}la sintaxis para cargar desde un archivo externo. La ruta es relativa a la ubicación del archivo de configuración:

Ejemplo

{
  "agent": {
    "review": {
      "prompt": "{file:./prompts/code-review.txt}"
      // Lee el prompt desde prompts/code-review.txt en el mismo directorio que opencode.json
      // Adecuado cuando el contenido del prompt es largo; mantenlo por separado en un archivo de texto.
    }
  }
}

temperature (temperatura)

Controla la aleatoriedad de la salida del modelo. Cuanto más bajo sea el valor, más determinista es la salida, adecuado para tareas que requieren resultados precisos; cuanto más alto, más diversa es la salida, adecuado para tareas creativas:

Rango de temperatura Característica de salida Escenario de aplicación
0.0 – 0.2 Muy enfocado y determinista Análisis de código, planificación, depuración, revisión
0.3 – 0.5 Equilibrado, combina precisión y flexibilidad Tareas generales de desarrollo, redacción de documentación
0.6 – 1.0 Más creativo y diverso Lluvia de ideas, exploración de soluciones, escritura creativa

Ejemplo

{
  "agent": {
    "analyze": {
      "temperature": 0.1,                          // Tarea de análisis: alta determinación
      "prompt": "{file:./prompts/analysis.txt}"
    },
    "build": {
      "temperature": 0.3                           // Tarea de desarrollo: equilibrado
    },
    "brainstorm": {
      "temperature": 0.7,                          // Lluvia de ideas: más creativo
      "prompt": "{file:./prompts/creative.txt}"
    }
  }
}

No especificadotemperatureCuando no se especifica, OpenCode usa el valor predeterminado del modelo: la mayoría de los modelos tienen un valor predeterminado de0, los modelos de la serie Qwen tienen un valor predeterminado de0.55。

steps (pasos máximos)

Controla el número máximo de iteraciones (es decir, rondas de llamadas a herramientas) que el agente puede ejecutar antes de verse obligado a responder en texto plano. Adecuado para escenarios en los que necesitas controlar costos o evitar que el agente entre en bucles infinitos:

Ejemplo

{
  "agent": {
    "quick-thinker": {
      "description": "Fast reasoning with limited iterations",
      "prompt": "You are a quick thinker. Solve problems with minimal steps.",
      "steps": 5    // Ejecuta como máximo 5 iteraciones; después de eso, el agente genera un resumen del progreso actual y las tareas sugeridas restantes.
    }
  }
}

No establecidostepsCuando no se establece, el agente seguirá iterando hasta que el modelo se detenga por sí mismo o el usuario lo interrumpa manualmente.

Versión anteriormaxStepsEl campo está obsoleto; utiliza de manera uniformesteps。

tools (acceso a herramientas)

Controla qué herramientas puede usar este agente. Establece el nombre de la herramienta entrueofalse. La configuración a nivel de agentesobrescribe la configuración global.：

Ejemplo

{
  "$schema": "https://opencode.ai/config.json",
  "tools": {
    "write": true,     // Global: permitir escritura de archivos
    "bash": true       // Global: permitir comandos bash
  },
  "agent": {
    "plan": {
      "tools": {
        "write": false,    // Agente plan: sobrescribir la configuración global, deshabilitar escritura de archivos
        "bash": false      // Agente plan: sobrescribir la configuración global, deshabilitar bash
      }
    }
  }
}

También puedes usar comodines para controlar herramientas en lote, por ejemplo, deshabilitar todas las herramientas de un servidor MCP:

Ejemplo

{
  "agent": {
    "readonly": {
      "tools": {
        "mymcp_*": false,    // Deshabilita todas las herramientas del servidor mymcp (coincidencia Glob)
        "write": false,
        "edit": false
      }
    }
  }
}

permission (permiso)

Configura un control de permisos más fino para el agente. Para cada tipo de operación puedes establecer"allow"(permitir),"ask"(preguntar) o"deny"(denegar):

Ejemplo

{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
    "edit": "deny"         // Global: denegar todas las ediciones de archivos por defecto
  },
  "agent": {
    "build": {
      "permission": {
        "edit": "ask"      // Agente build: sobrescribir la configuración global, requiere aprobación antes de editar
      }
    }
  }
}

Parabashherramientas, también puedes afinar hasta comandos específicos, con soporte para comodines Glob, yla última regla que coincida tiene prioridad(Se recomienda poner*las reglas comodín al principio y las reglas específicas al final):

Ejemplo

{
  "agent": {
    "build": {
      "permission": {
        "bash": {
          "*": "ask",             // Regla por defecto: todos los comandos bash requieren aprobación por defecto
          "git status *": "allow",// Los comandos relacionados con git status se permiten directamente (más específicos, coinciden primero)
          "grep *": "allow"       // Los comandos de búsqueda grep se permiten directamente
        }
      }
    }
  }
}

En los archivos de agente en Markdown, también puedes configurar permisos en el frontmatter:

Ejemplo

# Ruta del archivo: ~/.config/opencode/agents/review.md
---
description: Code review without edits
mode: subagent
permission:
  edit: deny          # Prohíbe todas las ediciones de archivos
  bash:
    "*": ask          # Los comandos bash requieren aprobación por defecto
    "git diff": allow # Permite git diff
    "git log*": allow # Permite git log y sus variantes
    "grep *": allow   # Permite búsquedas con grep
  webfetch: deny      # Prohíbe el acceso a URLs externas
---

Only analyze code and suggest changes.

permission.task (permiso de tarea)

Controla qué subagentes puede invocar este agente mediante la herramienta Task, con soporte para coincidencia Glob. Si se establece en"deny", el subagente se elimina por completo de la descripción de la herramienta Task y el modelo no intentará invocarlo:

Ejemplo

{
  "agent": {
    "orchestrator": {
      "mode": "primary",
      "permission": {
        "task": {
          "*": "deny",                  // Regla por defecto: se deniega la invocación de todos los subagentes por defecto
          "orchestrator-*": "allow",   // Permite invocar subagentes que comiencen con orchestrator-
          "code-reviewer": "ask"        // Invocar code-reviewer requiere confirmación del usuario
          // La última regla que coincida tiene prioridad: orchestrator-planner coincide tanto con * como con orchestrator-*,
          // como orchestrator-* está después, el resultado es allow
        }
      }
    }
  }
}

hidden (oculto)

Oculta el subagente del@menú de autocompletado; solo se permite invocarlo programáticamente mediante la herramienta Task. Adecuado para subagentes de utilidad que solo deben ser llamados internamente por otros agentes:

Ejemplo

{
  "agent": {
    "internal-helper": {
      "mode": "subagent",    // hidden solo es válido para subagentes
      "hidden": true         // Una vez oculto, este agente no aparecerá en el menú de autocompletado @ del usuario,
                             // pero si los permisos lo permiten, el modelo aún puede invocarlo mediante la herramienta Task
    }
  }
}

color (color)

Personaliza el color de visualización del agente en la interfaz de usuario. Admite valores de color hexadecimales o palabras clave de color de tema (primary、secondary、accent、success、warning、error、info）：

Ejemplo

{
  "agent": {
    "creative": {
      "color": "#ff6b6b"      // Usa un color hexadecimal
    },
    "code-reviewer": {
      "color": "accent"       // Usa una palabra clave de color de tema
    }
  }
}

top_p (diversidad de muestreo)

top_pSítemperatureUn parámetro adicional para controlar la diversidad de salida, además de temperature. Rango de valores: 0.0 – 1.0. Cuanto más bajo es el valor, más concentrada es la salida; cuanto más alto, más diversa:

Ejemplo

{
  "agent": {
    "brainstorm": {
      "top_p": 0.9    // Un top_p más alto aumenta la diversidad de la salida
    }
  }
}

disable (deshabilitar)

Establece el agente en estado deshabilitado. Una vez deshabilitado, el agente no aparecerá en la lista de selección:

Ejemplo

{
  "agent": {
    "review": {
      "disable": true    // Deshabilita este agente, sin afectar a otros agentes
    }
  }
}

Otros parámetros del modelo

Cualquier campo no reconocido en la configuración del agente se pasará directamente al proveedor de servicios como parámetro del modelo. Esto te permite usar funciones avanzadas específicas del proveedor:

Ejemplo

{
  "agent": {
    "deep-thinker": {
      "description": "Agent that uses high reasoning effort for complex problems",
      "model": "openai/gpt-5",
      "reasoningEffort": "high",    // Parámetro de esfuerzo de razonamiento de OpenAI, se pasa directamente a la API de OpenAI
      "textVerbosity": "low"        // Parámetro de nivel de detalle de respuesta de OpenAI
    }
  }
}

Los parámetros de paso directo varían según el proveedor de servicios y el modelo. Consulta la documentación de la API del proveedor correspondiente para confirmar los nombres de los parámetros disponibles.

Creación rápida de agentes

Además de escribir manualmente los archivos de configuración, también puedes usar la herramienta de línea de comandos interactiva para generar agentes rápidamente:

opencode agent create

Este comando te guiará paso a paso por los siguientes pasos:

  1. Elegir la ubicación de guardado del agente (global~/.config/opencode/agents/o nivel de proyecto).opencode/agents/）
  2. Describir las responsabilidades y objetivos del agente
  3. Generar automáticamente un prompt de sistema adecuado y un identificador de agente
  4. Elegir las herramientas a las que puede acceder el agente
  5. Generar un archivo Markdown con la configuración completa en la ubicación seleccionada

Ejemplos de agentes

Agente de redacción de documentación

Ejemplo

# Ruta del archivo: ~/.config/opencode/agents/docs-writer.md
---
description: Writes and maintains project documentation
mode: subagent
tools:
  bash: false    # Deshabilita bash; la redacción de documentación no necesita ejecutar comandos
---

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

Focus on:
- Clear explanations
- Proper structure
- Code examples
- User-friendly language

Agente de auditoría de seguridad

Ejemplo

# Ruta del archivo: ~/.config/opencode/agents/security-auditor.md
---
description: Performs security audits and identifies vulnerabilities
mode: subagent
tools:
  write: false    # Solo lectura: no escribir archivos
  edit: false     # Solo lectura: no editar archivos
---

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

Casos de uso comunes

Escenario Configuración de agente recomendada
Desarrollo diario, se requieren permisos completos de herramientas Usa elBuildagente integrado
Analizar código, elaborar planes, sin modificar archivos Cambia alPlanagente integrado
Consultar solo lectura de la estructura del código o palabras clave Mediante@exploreinvocar alExploresubagente integrado
Ejecutar varias tareas independientes en paralelo Mediante@generalinvocar múltiplesGeneralsubagentes para procesar en paralelo
Realizar auditorías de seguridad o calidad del código Subagente personalizado de solo lectura (deshabilitar write/edit), con temperatura baja (0.1)
Controlar costes, limitar los pasos de ejecución de la IA Configura elstepsparámetro para limitar el número máximo de iteraciones
Otras extensiones