Saltar al contenido
Aula en la nube
Guía del curso · OpenCode

OpenCode: tu agente de programación

A partir del proyecto 2 programas de forma agéntica: con OpenCode, un agente que vive en tu terminal, lee tu proyecto, propone cambios y ejecuta órdenes — siempre con tu permiso. Está conectado a los modelos de IA locales del centro: tu código y tus datos no salen del instituto. El chat queda para consultas; el código se construye con el agente.

Esta guía es tu referencia para todo el curso, en presencial y en semipresencial. Vuelve a ella cada vez que aparezca algo nuevo. Y fíjate en el detalle: la herramienta con la que vas a programar tu CLI… es una CLI.

El hilo del proyecto 2

  1. Detectas una tarea que te hace perder tiempo
  2. La automatizas con tu propia CLI, construida con OpenCode
  3. La reutilizas: una orden, cada vez que la necesites

OpenCode 2

la última versión estable

Modelos del centro

nada sale del instituto

Tú decides

permisos y diffs

Todo el curso

del proyecto 2 en adelante

En esta guía

Chat frente a agente

Hasta ahora usabas la IA como un chat: preguntas, te contesta con texto, y tú copias el código y lo pegas. Un agente es el mismo tipo de modelo, pero con herramientas: puede abrir tus ficheros, buscar, editarlos y ejecutar órdenes. Ve el resultado de cada paso y decide el siguiente, en bucle, hasta terminar.

Chat

  • No ve tu proyecto: solo lo que le pegas.
  • Responde una vez; tú haces el trabajo de copiar, pegar y probar.
  • Ideal para preguntar: «¿qué es un decorador?», «¿por qué falla esto?».

Agente (OpenCode)

  • Lee el proyecto entero por su cuenta (lo que necesite).
  • Edita ficheros y ejecuta órdenes, pidiéndote permiso según tus reglas.
  • Comprueba su propio trabajo (ejecuta, ve el error, corrige) antes de darte el turno.

El bucle del agente

Tú pides«añade la orden listar»Planificaqué mirar, qué cambiarUsa una herramientaread · grep · edit · bashTe pide permisosi la regla es asktú: sí / noVe el resultadocontenido, diff, salida¿Ha terminado?compara con lo pedidoTermina y te avisatú revisas y decidesno: otra vueltamuchas vueltassí

Desliza el diagrama de lado para verlo entero

Un chat da una respuesta. Un agente da muchas vueltas a este bucle hasta acabar la tarea.

Las herramientas del agente

Son las que tiene el agente build. Los permisos (más abajo) deciden cuáles usa solo, cuáles te pregunta y cuáles tiene prohibidas.

Para mirar

  • read

    Lee un fichero (o un trozo). Como abrirlo en el editor para mirarlo.

  • glob

    Busca ficheros por nombre o patrón: src/**/*.py. Como el buscador de ficheros.

  • grep

    Busca texto dentro de los ficheros. Como Ctrl+Shift+F en VS Code.

  • webfetch

    Descarga una página web y la lee. En el proyecto, siempre pregunta antes.

Para cambiar

  • edit

    Cambia unas líneas concretas de un fichero que ya existe. Te enseña el diff antes de aplicarlo (si está en ask).

  • write

    Crea un fichero nuevo o lo reescribe entero. Lo controla el mismo permiso que edit.

  • shell

    Ejecuta una orden en la terminal: uv run, git status, ls… La más potente y la más peligrosa: por eso pregunta.

Para organizarse

  • subagent

    Lanza un subagente (general, explore o uno tuyo) para una subtarea. Trabaja en una sesión hija y te devuelve un resumen.

  • todowrite

    Mantiene una lista de pasos pendientes y hechos. Verás la lista tachándose mientras trabaja.

  • skill

    Carga una skill (conocimiento extra) cuando la necesita. Solo carga la que le sirve, no todas.

  • question

    Te hace una pregunta con opciones cuando duda. Respóndela: es mejor que dejarle adivinar.

Qué cambia para ti

Ya no escribes cada línea, pero sigues siendo quien decide qué se hace, quien revisa cada diff y cada orden antes de aceptarla, y quien responde de lo que entrega.

  • Decidesqué se hace
  • Revisascada diff y cada orden
  • Respondesde lo que entregas

Si el agente mete un fallo y tú lo aceptas, el fallo es tuyo. Lo que no sabes explicar, no lo entregas.

Por qué OpenCode

Open source

Código abierto: puedes ver cómo funciona y no depende de una suscripción.

En la terminal

Funciona igual en Linux, Windows y macOS, y dentro de la terminal integrada de VS Code.

Cualquier proveedor

Se conecta a decenas de proveedores… y a un servidor propio como el del centro.

Agentes y permisos a tu medida

Defines qué puede hacer solo, qué te pregunta y qué nunca hará.

El mismo concepto que la industria

Claude Code, Codex o el modo agente de Copilot funcionan igual: lo que aprendes aquí, lo usas allí.

Configuración en ficheros

AGENTS.md, comandos, skills y agentes viven en tu repo y viajan con él.

Por qué modelos del centro

Modelos locales

Privacidad

Tu código, tus ficheros y tus prompts se quedan en el servidor del instituto. No alimentan a ninguna empresa.

Modelos locales

Sin cuentas de pago

No necesitas tarjeta ni suscripción. Te basta la clave que te da el profesor.

Modelos locales

Igual para todos

Todo el grupo usa el mismo modelo con las mismas condiciones: la nota depende de tu trabajo, no de quién paga más.

El camino de tu petición

Red del institutoTu tecladopides la tareaOpenCodeen tu terminalModelo del centroQwen 3.8 Flash-NextTu proyectolee, edita, ejecutaInternetno recibe nadapreguntarespondeherramientas✕tu código y tus datos no salen

Desliza el diagrama de lado para verlo entero

El agente trabaja en tu equipo y piensa en el servidor del centro: nada sale del instituto.

Paso 1 · Instala OpenCode

Usamos la última versión estable de OpenCode 2. El número exacto importa poco: lo que vas a aprender es a trabajar con un agente. En los equipos del aula lo instalas en la primera sesión; en casa (semipresencial), elige tu sistema:

Linux y macOS

El script oficial. Después, abre una terminal nueva. (También vale npm install -g @opencode/cli.)

Terminal
curl -fsSL https://opencode.ai/v2/install | bash

Windows nativo

  1. Instala Git for Windows: OpenCode ejecuta sus órdenes con Git Bash (sin él, con PowerShell) y sin git no hay /undo de ficheros.
  2. Descarga el zip oficial: opencode-windows-x64.zip.
  3. Descomprímelo en una carpeta tuya (por ejemplo C:\opencode) y añade esa carpeta al PATH.
  4. Abre una terminal nueva de PowerShell.

Windows con WSL

Un Linux dentro de Windows. Si ya usas WSL (Ubuntu), dentro de su terminal usa el script de Linux:

Terminal de WSL
curl -fsSL https://opencode.ai/v2/install | bash

Ojo: en WSL las variables de entorno y la config van en el ~ de Linux, no en el de Windows.

Paso 2 · Comprueba que está bien

Si algo falla

  • Sale command not found (o no se reconoce en Windows): cierra la terminal y abre otra. Las terminales abiertas antes de instalar no conocen el PATH nuevo.
  • Dice 1.algo: tienes OpenCode 1 de otro instalador. Mira Errores típicos.
  • Para ponerte al día con la última estable: opencode upgrade.
Terminal
opencode --version # debe decir v2.algo
opencode v2.2.5
opencode debug paths config # dónde busca tu config global
/home/tu-usuario/.config/opencode

Paso 3 · Crea la config global

OpenCode necesita saber a qué servidor hablar y con qué clave. Eso va en tu configuración global (de tu usuario, en tu equipo), nunca en el repositorio. La URL del servidor y la clave te las da el profesor (en clase o en el aula virtual).

Ruta: ~/.config/opencode/opencode.json. Si dudas (Windows, WSL…), opencode debug paths config te dice la carpeta exacta. Créala y abre el fichero con tu editor:

bash / zsh
mkdir -p ~/.config/opencodecode ~/.config/opencode/opencode.json   # o nano
PowerShell
New-Item -ItemType Directory -Force "$env:USERPROFILE\.config\opencode"notepad "$env:USERPROFILE\.config\opencode\opencode.json"

Paso 4 · Pega la configuración

Tal cual. No hay ninguna dirección ni clave escrita: las dos salen de variables de entorno (el paso 5).

~/.config/opencode/opencode.json
{  "$schema": "https://opencode.ai/config.json",  "model": "centro/qwen3.8-flash-next",  "providers": {    "centro": {      "package": "@opencode/ai/providers/openai-compatible",      "env": ["CENTRO_IA_KEY"],      "settings": { "baseURL": "{env:CENTRO_IA_URL}" },      "models": {        "qwen3.8-flash-next": {          "name": "Qwen 3.8 Flash-Next (centro)",          "limit": { "context": 524288, "output": 65536 },          "capabilities": { "tools": true, "input": ["text"], "output": ["text"] }        }      }    }  }}

Qué hace cada clave

  • centro (en providers): el nombre del proveedor; es lo que va antes de la barra en model.
  • package openai-compatible: el servidor del centro habla el mismo «idioma» que la API de OpenAI.
  • "env": ["CENTRO_IA_KEY"]: de qué variable de entorno sale la clave.
  • {env:CENTRO_IA_URL}: la dirección del servidor, leída de otra variable.
  • limit: cuánto contexto y salida admite el modelo. Sin esto OpenCode no sabe cuándo resumir la conversación.
  • "tools": true: el modelo sabe usar herramientas. Sin eso no hay agente, solo chat.
  • model: el modelo que usa por defecto, en formato proveedor/modelo.

Paso 5 · Define las variables de entorno

Sustituye los … por lo que te dé el profesor (la URL termina en /v1).

Antes, descarga el certificado del centro (ca-ies-simarro.crt) desde la página «Certificado del centro» de la plataforma y déjalo en tu carpeta personal. El servidor va por https con un certificado del propio instituto: la tercera variable le dice a OpenCode que se fíe de él.

Linux / macOS / WSL
# Añade al final de ~/.bashrc (o ~/.zshrc en macOS)export CENTRO_IA_URL="…"export CENTRO_IA_KEY="…"export NODE_EXTRA_CA_CERTS="$HOME/ca-ies-simarro.crt"
Windows (PowerShell)
setx CENTRO_IA_URL "…"setx CENTRO_IA_KEY "…"setx NODE_EXTRA_CA_CERTS "$HOME\ca-ies-simarro.crt"

Y después, abre una terminal nueva: las variables solo existen en las terminales que se abren después.

Paso 6 · Comprueba la conexión

Terminal
opencode models # entre ellos, el del centro
centro/qwen3.8-flash-next
opencode run "Responde solo: hola" # prueba real con el modelo
> build · qwen3.8-flash-nextHola

Si se queda esperando

Si opencode run no responde, el servidor no contesta. Sal con Ctrl+C y revisa la URL, el certificado y que estás en la red del centro.

opencodeprograma
runsubcomando
"Responde solo: hola"argumento

¿Por qué variables y no la clave escrita?

Porque así la clave no está en ningún fichero, y por tanto no puede acabar por accidente en un commit, en una captura o en un repo público. Es la misma regla que en tu proyecto: ninguna clave en el repo ni en su historial (es un mínimo del proyecto 2).

En la semana 3, tu propia CLI leerá las mismas variables desde Python.

Semipresencial: OpenCode en casa

Puedes usar OpenCode en casa, también dentro de la terminal integrada de VS Code. Cómo conectarte desde casa a los modelos del centro lo explica el profesor en la tutoría colectiva de arranque.

Paso 7 · Abre OpenCode en tu proyecto

TUI (Text User Interface) es una interfaz completa dentro de la terminal. Se abre entrando en la carpeta del proyecto y escribiendo opencode:

Terminal
cd ~/cli-tareasopencode

La pantalla de OpenCode

  1. Conversación. Tus mensajes, las respuestas y cada herramienta que usa (qué fichero lee, qué orden ejecuta). Léelo: es el «razonamiento en voz alta» del agente.
  2. Petición de permiso. Cuando una regla está en ask, se para y te enseña el diff o la orden. Nada se aplica hasta que respondes.
  3. Caja de entrada. Escribes la petición. Intro envía; para un salto de línea, shift+enter o ctrl+j.
  4. Barra inferior. Agente activo (Build o Plan) y modelo. Míralo antes de escribir: ¿estás en el agente que quieres?
  5. Esquema simplificado: colores y textos exactos cambian según el tema y la versión.

Lo que puedes escribir en la caja

texto normal

Tu petición, en español. Concreta: qué fichero, qué orden, qué criterio de «terminado».

@fichero

Adjunta un fichero (con búsqueda): @src/tareas/cli.py, o solo unas líneas: @src/tareas/cli.py#20-45.

!orden

Con ! al principio de la caja vacía entras en modo shell: la orden se ejecuta en tu proyecto y su salida queda en la sesión. Esc para salir. Con / ves los comandos.

Un ejemplo de primera petición en el agente plan:

Prompt · agente plan
Lee @AGENTS.md y @src/tareas/cli.py. Quiero añadir la orden «version» que muestre la versión de __init__.py. No cambies nada todavía: explícame en 5 líneas qué ficheros tocarías y cómo comprobaré que funciona.

Atajos de teclado

La tecla líder es ctrl+x: la pulsas, sueltas y pulsas la letra (por ejemplo ctrl+x u = deshacer).

  • shift+tabCambia de agente: build ↔ plan
  • ctrl+x a/agentsElegir agente de la lista
  • EscInterrumpe la respuesta en curso
  • ctrl+pPaleta con todos los comandos
  • ctrl+x n/newSesión nueva (una por tarea)
  • ctrl+x l/sessionsLista de sesiones para retomar una
  • ctrl+x m/modelsElegir modelo
  • ctrl+x c/compactCompacta la conversación para liberar contexto
  • ctrl+x u/undoDeshace tu último mensaje y lo que hizo después
  • ctrl+x r/redoRehace lo deshecho
  • ctrl+x x/exportExporta la sesión a tu editor
  • ctrl+x e/editorEscribe la petición en tu editor
  • ctrl+cSalir (también ctrl+d o ctrl+x q)

Comandos de barra sin atajo

Escribe / en la caja y aparece la lista entera.

  • /initConfiguración guiada del AGENTS.md del proyecto
  • /reviewRevisa los cambios sin commit (o un commit, rama o PR)
  • /skillsLas skills que ve el agente
  • /helpAyuda
  • /connectConecta un proveedor de modelos
  • /mcpsServidores MCP: conectar o desconectar
  • /diffRevisa los cambios en una vista de diferencias
  • /btwPregunta al margen: la respuesta no entra en la conversación

Una sesión por tarea

Sesiones

Cada conversación es una sesión y se guarda. Abre una nueva para cada tarea (/new), recupera una anterior con /sessions o continúa la última desde la terminal con opencode -c.

Compactar

ctrl+x c resume la conversación para liberar contexto. OpenCode lo hace solo cuando se llena, pero hacerlo tú al cambiar de fase (o abrir /new) da mejores resultados: un modelo con menos ruido se equivoca menos.

Exportar

ctrl+x x exporta la sesión a tu editor. Útil para guardar el prompt clave y lo que respondió en docs/prompts.md, que forma parte de tu proceso evaluable.

/undo y /redo

/undo deshace tu último mensaje y lo que hizo el agente después; tu mensaje vuelve a la caja para que lo corrijas. Se confirma al enviarlo: /redo antes de enviar lo cancela.

Deshace

  • Tu último mensaje y sus respuestas.
  • Los ficheros que cambió el agente desde entonces.

No deshace efectos externos

  • Un paquete instalado o una orden que tocó cosas fuera.
  • Un git push.
  • Ficheros ignorados por git o de más de 2 MiB.

Funciona con instantáneas internas: no hace commits ni toca tu rama. Pero necesita que el proyecto sea un repositorio git (git init); los commits no hacen falta.

Agentes

Plan frente a build

Un agente es una configuración del modelo: un prompt, unas herramientas y unos permisos. OpenCode trae varios, y puedes crear los tuyos. Los dos primarios son estos:

primario

plan

  • Para pensar: analizar, proponer, revisar un plan.
  • No edita los ficheros del proyecto (solo sus propios planes).
  • Ojo: sus órdenes siguen tus reglas de shell.

primario (por defecto)

build

  • Para hacer: editar, crear, ejecutar.
  • Todas las herramientas, con los permisos de tu config.

shift+tab alterna entre build y plan (mira la barra inferior).

Plan solo bloquea ediciones

El agente plan de fábrica no escribe ficheros, pero sí ejecuta órdenes con tus permisos. Y si tu configuración dice edit · * → ask, esa regla le alcanza también a plan.

Por eso el opencode.json del proyecto le añade a plan (y a explore) su propio edit · * → deny: las reglas de un agente van después de las generales y ganan. Compruébalo con opencode debug agents. Y lo que nunca debe pasar va en policies, que nadie deshace.

Subagentes: general y explore

subagente

general

Investigación y tareas de varios pasos. Puede modificar ficheros, pero no lanzar otros subagentes.

subagente

explore

Solo busca y lee (no edita), aunque puede ejecutar órdenes. «¿Dónde se valida el JSON?»

Cómo se invocan

Pídeselo con palabras: «Usa el subagente explore para buscar dónde se lee acciones.json». El agente también los lanza solo (herramienta subagent).

Tu sesiónagente buildtu contextosolo el resumenSesión hijasubagente exploresu contextotoda la búsquedale encargate devuelve

Desliza el diagrama de lado para verlo entero

La sesión hija lee y busca todo lo que necesita; a la tuya solo vuelve el resumen.

Crea tus agentes

Un fichero Markdown en .opencode/agents/: el nombre del fichero es el id del agente, el frontmatter su configuración (description, mode: subagent, permissions…) y el cuerpo, su prompt. Es el revisor de la semana 2.

Se usa pidiéndoselo: «Usa el subagente revisor para revisar src/tareas/motor.py». No puede editar ni navegar por la web; solo mirar diffs e historial. Ojo: un subagente tuyo solo tiene sus permisos, no hereda los del agente que lo llama.

.opencode/agents/revisor.md
---description: Revisa el código de la CLI tareas sin modificar nada y señala errores, casos feos y problemas multiplataformamode: subagentpermissions:  - { action: edit, resource: "*", effect: deny }  - { action: webfetch, resource: "*", effect: deny }  - { action: shell, resource: "*", effect: deny }  - { action: shell, resource: "git diff *", effect: allow }  - { action: shell, resource: "git log *", effect: allow }  - { action: shell, resource: "git status *", effect: allow }---Eres el revisor de código del proyecto (1º DAM). Revisa lo que te indiquen y responde en español con:1. Errores seguros (con fichero y línea).2. Casos feos sin cubrir: ruta inexistente, carpeta vacía, nombres con tildes o espacios, JSON roto, destino que ya existe.3. Problemas en Windows/macOS (rutas, encoding, shell).4. Una pregunta que el alumno debería saber responder sobre ese código.No reescribas el código: señala y explica.

Permisos

De fábrica, OpenCode lo permite casi todo: edita y ejecuta órdenes sin preguntar. En el curso eso no vale. Cada herramienta (y cada orden de la terminal) acaba en una de tres respuestas:

allow

Lo hace sin preguntar.

ask

Se para, te enseña qué va a hacer y espera.

deny

Bloqueado. Ni lo intenta.

Qué pasa cuando quiere actuar

Quiere actuaredit, shell, read…Mira tus reglasgana la últimaallowlo hace sin másaskte preguntadenyni lo intentaoncevale, esta vezalwaysvale y recuérdalorejectno a lo pendienteninguna coincide → ask

Desliza el diagrama de lado para verlo entero

always guarda la regla como allow del proyecto. Los deny que tú configuras se respetan siempre, también por encima de lo que respondas.

Anatomía de una regla

En OpenCode 2 los permisos son una lista de reglas. Cada regla tiene tres partes:

{ "action": "shell",qué herramienta
"resource": "git diff *",sobre qué
"effect": "allow" }qué pasa

El * significa «cualquier cosa»: git diff * vale para git diff y para git diff src/. Si ninguna regla coincide, OpenCode pregunta.

Gana la última que coincide

Las reglas se leen de arriba abajo y, si varias coinciden, manda la última. Por eso la general (*) va primero y las excepciones después.

Reglas, de arriba abajogit diff src/tareas/cli.pyrm -r build
shell · * → askcoincidecoincide
shell · git diff * → allowcoincide · gana ✓no coincide
shell · rm * → denyno coincidecoincide · gana ✓
Resultado allow deny

El opencode.json del proyecto

Va en la raíz de tu repo (cli-tareas/opencode.json) y se sube a git: no lleva claves, solo reglas. Se fusiona con tu config global.

1 · Ficheros

Qué puede leer y editar, y qué hace con la web y con lo que está fuera del proyecto.

2 · Órdenes

Qué órdenes de terminal ejecuta solo y cuáles te pregunta.

3 · Lo que nunca hará

Las políticas (policies), que solo pueden negar, y el freno de edición del agente plan.

Lo verás en tres trozos; el botón de cada uno copia el fichero entero.

Parte 1: ficheros

cli-tareas/opencode.json · parte 1 de 3
{  "$schema": "https://opencode.ai/config.json",  "permissions": [    { "action": "edit", "resource": "*", "effect": "ask" },    { "action": "webfetch", "resource": "*", "effect": "ask" },    { "action": "external_directory", "resource": "*", "effect": "ask" },    { "action": "read", "resource": "*", "effect": "allow" },    { "action": "read", "resource": "*.env", "effect": "deny" },    { "action": "read", "resource": "*.env.*", "effect": "deny" },    { "action": "read", "resource": "*.env.example", "effect": "allow" },

Reglas para ficheros

  • edit · * → ask

    Cada edición o fichero nuevo te enseña el diff y espera tu sí. En la semana 1 es obligatorio: lees todo lo que entra en tu repo.

  • webfetch · * → ask

    Si quiere leer una web, pregunta. Así sabes de dónde saca la información.

  • external_directory · * → ask

    Nada fuera de la carpeta del proyecto sin preguntar (tu carpeta personal, otras prácticas…). De fábrica no pregunta: por eso la regla.

  • read · * → allow

    Puede leer cualquier fichero del proyecto sin preguntar…

  • read · *.env, *.env.* → deny

    …salvo los .env con claves: esos ni los ve. Van DESPUÉS del «*» porque gana la última que coincide.

  • read · *.env.example → allow

    La plantilla sin claves sí puede leerla (va al final para volver a permitirla).

Parte 2: órdenes

cli-tareas/opencode.json · parte 2 de 3
    { "action": "shell", "resource": "*", "effect": "ask" },    { "action": "shell", "resource": "ls *", "effect": "allow" },    { "action": "shell", "resource": "pwd", "effect": "allow" },    { "action": "shell", "resource": "cat *", "effect": "allow" },    { "action": "shell", "resource": "git status *", "effect": "allow" },    { "action": "shell", "resource": "git diff *", "effect": "allow" },    { "action": "shell", "resource": "git log *", "effect": "allow" },    { "action": "shell", "resource": "uv run tareas --help", "effect": "allow" },    { "action": "shell", "resource": "uv run tareas validar *", "effect": "allow" },    { "action": "shell", "resource": "uv run pytest *", "effect": "allow" },    { "action": "shell", "resource": "git commit *", "effect": "ask" }  ],

Reglas para órdenes

  • shell · * → ask

    Regla general: cualquier orden pregunta. Es la primera para que las demás la puedan matizar.

  • shell · ls *, pwd, cat * → allow

    Mirar carpetas y ficheros no rompe nada.

  • shell · git status *, git diff *, git log * → allow

    Consultar git tampoco. El agente puede ver qué ha cambiado.

  • shell · uv run tareas --help, uv run tareas validar * → allow

    Probar la ayuda y validar acciones.json es inofensivo.

  • shell · uv run pytest * → allow

    Pasar las pruebas (semana 4).

  • shell · git commit * → ask

    Los commits los haces tú; si te lo propone, te pregunta (y normalmente dirás que no).

Parte 3: lo que nunca hará

cli-tareas/opencode.json · parte 3 de 3
  "policies": [    { "action": "tool.use", "resource": "shell:git push *", "effect": "deny" },    { "action": "tool.use", "resource": "shell:git reset *", "effect": "deny" },    { "action": "tool.use", "resource": "shell:rm *", "effect": "deny" },    { "action": "tool.use", "resource": "shell:sudo *", "effect": "deny" }  ],  "agents": {    "plan": { "permissions": [{ "action": "edit", "resource": "*", "effect": "deny" }] },    "explore": { "permissions": [{ "action": "edit", "resource": "*", "effect": "deny" }] }  }}
  • shell:git push *, shell:git reset * → deny

    Subir o reescribir historia: nunca el agente.

  • shell:rm *, shell:sudo * → deny

    Borrar ficheros o usar permisos de administrador: prohibido.

  • agents.plan · edit * → deny

    Al agente plan le quita editar; sus órdenes siguen tus reglas de shell (explicado en Agentes).

  • agents.explore · edit * → deny

    Lo mismo para explore: tu edit · * → ask le devolvería la edición.

¿Por qué ejecutar no está permitido?

Porque uv run tareas ejecutar … mueve, renombra o borra ficheros de verdad. Si el agente se equivoca de carpeta, los daños son reales y /undo no los deshace.

Esa orden siempre te pregunta, y tú la pruebas en ~/pruebas-tareas con --simular. Y git push lo haces tú.

La trampa al fusionar

Las configuraciones (la base de OpenCode, la global, la del proyecto y la de cada agente) se fusionan en ese orden. Si la global dice rm * → deny y otra posterior dice * → allow, gana la última: rm queda permitido. Las políticas lo arreglan: van al final y solo pueden negar.

Basede OpenCodetodo: allowlo permite la baseGlobaltu equipo"rm *": denylo niega la globalProyectotu repo"*": allowlo permite: ganaAgenteplan, build…—sin reglas aquíPolíticassolo nieganshell:rm *lo niega siempreReglas que coinciden con rm -r buildSin políticas: rm queda permitidoCon la política: rm, bloqueado

Desliza el diagrama de lado para verlo entero

Las reglas se leen de izquierda a derecha y gana la última que coincide. Las políticas van al final y solo pueden negar.

Nunca uses --auto

opencode --auto aprueba solo todo lo que no esté denegado expresamente. Es decir: desactiva tu revisión. Y responder always guarda la orden como regla allow del proyecto: úsalo solo con órdenes inofensivas.

Un modelo que entiende mal una petición puede borrar, sobrescribir o ejecutar lo que no debe, y tú ni lo verás. En el curso está prohibido; en tu carpeta personal, también.

AGENTS.md: la memoria del proyecto

El modelo no recuerda nada entre sesiones. AGENTS.md es un fichero Markdown en la raíz del proyecto que OpenCode carga al empezar cada sesión: qué es el proyecto, cómo se ejecuta, qué normas hay que respetar. Es un estándar: lo leen también otros agentes.

cli-tareas/AGENTS.md
# tareas · CLI de tareas con ficheros (proyecto de 1º DAM)## Stack y órdenes- Python 3.12 + Typer + Rich, gestionado con uv (src layout, paquete src/tareas).- Ejecutar: `uv run tareas --help` · Validar config: `uv run tareas validar` · Pruebas (semana 4): `uv run pytest`.## Normas- Mensajes y comentarios en español; código claro antes que listo.- pathlib siempre, encoding="utf-8", nada de os.system ni shell=True: tiene que funcionar en Linux, Windows y macOS.- Nunca ejecutes acciones sobre carpetas reales: solo en ~/pruebas-tareas y con --simular.- No toques .env ni escribas claves en ningún fichero. No hagas git push ni commits: los hace el alumno.- Antes de cambiar un fichero, explica en 2-3 líneas qué vas a hacer.

Dónde vive cada fichero

Tu equipo · solo para tiTu repo · se sube a git~/.config/opencode/opencode.json · proveedor y modeloAGENTS.md · tus preferenciasagents/ · commands/ · skills/Variables de entornoCENTRO_IA_URL · CENTRO_IA_KEYen ningún ficherocli-tareas/AGENTS.md · normas del proyectoopencode.json · permisos.opencode/agents/revisor.md.opencode/commands/nueva-accion.md.opencode/skills/acciones-json/SKILL.mdsrc/tareas/ · tu código

Desliza el diagrama de lado para verlo entero

Lo de la izquierda es tuyo y no se sube a ningún sitio; lo de la derecha viaja con tu repo.

Créalo con /init y mejóralo

Créalo con /init

/init te guía: analiza el repo, puede hacerte alguna pregunta y crea (o mejora) el AGENTS.md. Después lo editas tú: quita lo que sobra, añade tus normas. Corto y concreto: se carga siempre y ocupa contexto.

Cuando el agente repite un error

Cada vez que el agente repita un error («otra vez ha usado os.system»), la solución no es repetírselo en cada sesión: es añadir una línea a AGENTS.md y hacer commit. Los cambios en AGENTS.md cuentan tu proceso.

Comandos personalizados

Si escribes el mismo tipo de prompt muchas veces, conviértelo en un comando: un fichero .opencode/commands/<nombre>.md que se lanza con /nombre.

Piezas de un comando

  • Frontmatter: description (lo que ves en la lista), agent (con qué agente se ejecuta) y, si quieres, model o subagent: true (en una sesión hija).
  • $ARGUMENTS: todo lo que escribes detrás del comando. $1, $2…: cada argumento por separado (entre comillas si lleva espacios).
  • !`orden`: mete la salida de la orden en el prompt. Se ejecuta fuera de tus permisos: solo órdenes de confianza.
  • Un @fichero dentro del comando no se adjunta: adjúntalo en la caja al lanzarlo.
.opencode/commands/nueva-accion.md
---description: Añade una acción nueva a acciones.json y, si hace falta, el código que la soportaagent: build---Quiero añadir la acción: $ARGUMENTS1. Carga la skill acciones-json.2. Propón primero la entrada JSON y espera mi visto bueno.3. Si el tipo ya existe, solo edita acciones.json. Si no, añade la clase en src/tareas/acciones.py siguiendo el patrón de las demás.4. Termina ejecutando `uv run tareas validar` y dime qué orden con --simular debo probar yo.Estado actual del repo:!`git status --short`

Así se usa /nueva-accion

En la semana 2, para añadir una acción a tu herramienta:

Caja de entrada de OpenCode
/nueva-accion renombrar-capturas "Renombra las capturas de pantalla con su fecha y un contador"
/nueva-accionel comando
renombrar-capturas$1
"Renombra las capturas de pantalla con su fecha y un contador"$2

$ARGUMENTS es todo lo que va detrás del comando: aquí, $1 y $2 juntos.

Skills: conocimiento bajo demanda

Una skill es un paquete de conocimiento que el agente carga solo cuando lo necesita. Ve una lista con el id y la descripción de cada skill; si una le sirve, la carga con la herramienta skill y lee el contenido completo. Así no gasta contexto en lo que no toca. Tú también puedes cargarla escribiendo @id.

Dónde y cómo

  • Una carpeta por skill: .opencode/skills/<id>/SKILL.md.
  • El id es el nombre de la carpeta; name es solo una etiqueta.
  • description: imprescindible. Di qué hace y cuándo usarla: sin ella el agente ni la ve.
  • Compruébalo con /skills en la TUI; para forzar que la cargue, @acciones-json.

La skill acciones-json

.opencode/skills/acciones-json/SKILL.md
---name: acciones-jsondescription: Reglas del fichero acciones.json de la CLI tareas (campos, tipos, filtros, plantillas y validación). Úsala siempre que crees o cambies acciones o el código que las lee (config.py, acciones.py, motor.py).---# Esquema de acciones.json- Raíz: {"version": 1, "acciones": [...]}. Cada acción: nombre (único, minúsculas-con-guiones), descripcion, tipo.- Tipos: mover y copiar (requieren destino), renombrar (requiere plantilla), borrar (siempre pide confirmación salvo --si).- filtro opcional: extensiones (lista, en minúsculas), patron (regex válida), mas_antiguo_que_dias, mayor_que_mb.- plantilla: huecos {fecha:%Y-%m-%d}, {n:03}, {ext}, {nombre}.## Reglas al programar- Valida el JSON en config.py ANTES de ejecutar; errores con AccionNoValida(accion, campo, motivo).- pathlib y shutil; encoding="utf-8"; nunca shell=True; nunca sobrescribir (destino_libre).- Toda acción admite --simular y devuelve list[Resultado].- Si añades un campo o un tipo nuevo, documéntalo en el README y en esta skill.

¿AGENTS.md, skill o comando?

AGENTS.md

Qué es
Normas fijas del proyecto
Cuándo se carga
Siempre, al empezar cada sesión
Quién lo dispara
Nadie: está siempre
Gasta contexto
Siempre: tenlo corto
Ejemplo del curso
Stack, órdenes, «no hagas push»
Dónde
AGENTS.md (raíz)

Skill

Qué es
Conocimiento especializado
Cuándo se carga
Solo cuando el agente decide que le sirve
Quién lo dispara
El agente (herramienta skill) o tú con @id
Gasta contexto
Solo id y descripción hasta que se usa
Ejemplo del curso
Reglas del esquema de acciones.json
Dónde
.opencode/skills/<id>/SKILL.md

Comando

Qué es
Un prompt que repites
Cuándo se carga
Cuando tú escribes /nombre
Quién lo dispara
Tú
Gasta contexto
Solo al usarlo
Ejemplo del curso
/nueva-accion renombrar-capturas
Dónde
.opencode/commands/<nombre>.md

Regla rápida: lo que debe saber siempre → AGENTS.md; lo que debe saber a veces → skill; lo que tú pides a menudo → comando. Y los tres se suben a git.

Cuándo entra cada cosa en el contexto

empieza la sesiónla sesión avanza →AGENTS.md (normas)SkillComandoMCP encendidose carga siempresolo su descripcióncarga completatú: /nombretodas sus herramientas, siempre

Desliza el diagrama de lado para verlo entero

Lo que se carga siempre resta contexto a tu tarea: AGENTS.md corto y los MCP, apagados hasta que hagan falta.

MCP: enchufes para herramientas externas

El Model Context Protocol (MCP) es un estándar para conectar un agente con herramientas de fuera: documentación actualizada de librerías, un navegador, una base de datos… Cada servidor MCP es un enchufe que añade herramientas nuevas (se llaman servidor_herramienta). OpenCode es el cliente; tú decides qué enchufas.

opencode.json (bloque mcp)
{  "$schema": "https://opencode.ai/config.json",  "mcp": {    "servers": {      "context7": {        "type": "remote",        "url": "https://mcp.context7.com/mcp",        "disabled": true      },      "apuntes": {        "type": "local",        "command": ["npx", "-y", "@modelcontextprotocol/server-filesystem", "./docs"],        "disabled": true      }    }  }}

remote frente a local

Servidor en Internet

remote

  • Lleva url (y si hace falta, headers).

Programa en tu equipo

local

  • command es un array (["npx", "-y", …]), nunca una cadena: si no, no arranca.
  • Cada servidor va dentro de mcp.servers. disabled: true: definido pero apagado; lo enciendes cuando lo necesitas.
  • opencode mcp list: estado de cada servidor. En la TUI, /mcps los conecta o desconecta (sin tocar la config).

MCP: contexto y riesgos

Gastan contexto

Cada servidor conectado añade la descripción de todas sus herramientas al contexto. Dos o tres MCP pueden comerse buena parte y hacer que el agente use peor sus herramientas. Por eso context7 va con disabled: true y se enciende solo cuando hace falta (semana 3).

Riesgos

Un MCP local ejecuta código con tus permisos; uno remoto recibe lo que el agente le envía. Solo servidores conocidos y de confianza, y si piden token, nunca en claro: "headers": { "Authorization": "Bearer {env:DOCS_API_KEY}" }.

Detalle: opencode mcp add lo añade al proyecto; con --global, a todos tus proyectos.

El flujo de trabajo del curso

El mismo en todas las sesiones. Si te saltas un paso, lo notarás (y se notará en tus commits).

Tú decidesPlan piensaBuild haceIntenciónPide planHazloAuditaCommit/newsiguiente tarea

Desliza el diagrama de lado para verlo entero

Tú decides al principio y al final; plan piensa y build hace en medio. Y vuelta a empezar con la siguiente tarea.

El flujo, paso a paso

  1. Tú

    Escribe la intención

    Spec, entrada de acciones.json o criterio de aceptación. Qué quieres y cómo sabrás que está bien.

    docs/spec.md
  2. Plan

    Pide un plan

    Shift+Tab a plan: «explícame cómo lo harías y qué ficheros tocarías». Lo lees y lo corriges.

    shift+tab → plan
  3. Build

    Que lo haga

    Shift+Tab a build: «hazlo». Apruebas cada edición y cada orden leyendo el diff.

    shift+tab → build
  4. Tú

    Audita

    Lee el código y prueba en ~/pruebas-tareas con --simular y casos feos. Si sale mal: /undo o le explicas el fallo.

    !uv run tareas …
  5. Tú

    Commit pequeño

    git add + git commit con un mensaje que cuenta el paso. Guarda el prompt clave en docs/prompts.md (o exporta la sesión).

    git commit
  6. Tú

    Sesión nueva

    Una sesión por tarea (/new) y compacta (ctrl+x c) si la conversación se alarga.

    /new

Buenas prácticas con modelos locales

  • Tareas pequeñas: una orden, una función, un error. Nunca «hazme la CLI entera».
  • Una sesión por tarea (/new): menos ruido, menos errores.
  • Plan antes de build: corregir un plan cuesta segundos; corregir código, horas.
  • Lee cada diff antes de aceptarlo. Si no lo entiendes, pregunta antes de aceptar.
  • Adjunta solo los ficheros necesarios con @, no «lee todo el proyecto».
  • Compacta (ctrl+x c) cuando la conversación se alargue.
  • Commits pequeños hechos por ti, con mensajes que cuentan el paso.
  • Guarda tus prompts clave en docs/prompts.md (o exporta la sesión).

Seguridad

  • Secretos: las claves solo en variables de entorno. Nunca en el código, en opencode.json ni en el chat.
  • .env en el .gitignore antes del primer commit; el agente tiene prohibido leerlo.
  • Permisos del proyecto siempre activos: edición y órdenes en ask; rm, sudo y git push en policies.
  • Nunca --auto, y always solo para órdenes inofensivas.
  • Nunca en carpetas reales: las acciones de tu CLI se prueban en ~/pruebas-tareas y con --simular.
  • No abras OpenCode en tu carpeta personal (~): ábrelo dentro del proyecto.

Tu ruta con OpenCode en el curso

No se aprende todo el primer día. Cada semana del proyecto 2 añade una pieza. En semipresencial, las semanas 1 y 2 son la quincena 3 y las semanas 3 y 4, la quincena 4.

  1. Semana 1

    26-30 oct

    Sesión 1 · Arranque →
    • Instalar OpenCode y conectarlo con los modelos del centro.
    • Antes de abrir OpenCode, a mano: uv init, .gitignore y git init (sin git no hay /undo).
    • opencode.json de permisos del proyecto.
    • /init → AGENTS.md, que luego editas tú.
    • plan → build para crear cli.py (version + listar), aprobando diffs; /undo; commits tuyos.
    • Tu acciones.json, escrito por ti sin IA.
    • Skill del proyecto acciones-json (compruébala con /skills).
    • Comando personalizado /nueva-accion.
    • Subagente revisor y /review antes de cada commit.
  2. Semana 3

    9-13 nov

    Sesión 3 · Capa IA →
    • MCP: context7 para documentación de librerías, apagado por defecto y encendido solo cuando hace falta.
    • La capa IA de TU CLI llamando desde Python a los mismos modelos del centro (CENTRO_IA_URL / CENTRO_IA_KEY, modo sin red).
  3. Semana 4

    16-20 nov

    Sesión 4 · Release →
    • El agente escribe pruebas que tú auditas.
    • opencode run en un script: sin nadie delante, «ask» es «deny».
    • Release v1.0.

Más adelante en el curso

Plugins

Código que amplía OpenCode o reacciona a lo que hace el agente: por ejemplo, impedir que lea ciertos ficheros.

opencode run en scripts

Sin interfaz: un script o la CI le pasa una tarea. Siempre con permisos exactos y con un tiempo máximo, por si el servidor no responde.

opencode mini

Una interfaz mínima en la terminal, para tareas rápidas sin la pantalla completa.

Escritorio y web

El mismo agente con otra cara: OpenCode también tiene app de escritorio y versión web.

Errores típicos y soluciones

Antes de pedir ayuda, busca aquí el síntoma. Para diagnosticar casi todo:

Diagnóstico
opencode --version        # qué versión tienesopencode debug paths      # dónde están la config, los datos y los logsopencode debug config     # qué ficheros de config ha leídoopencode debug agents     # permisos efectivos de cada agenteopencode mcp list         # estado de los MCP

Errores al instalar

opencode: command not found (o «no se reconoce» en Windows)

Causa probable
La terminal se abrió antes de instalar y no tiene el PATH nuevo, o la carpeta del zip no está en el PATH.
Solución
Cierra y abre la terminal. En Windows, comprueba que la carpeta donde descomprimiste el zip está en el PATH.

opencode --version dice 1.algo

Causa probable
Tienes OpenCode 1: otro instalador, un paquete antiguo (opencode-ai) o un mise anterior a la versión de octubre de 2026.
Solución
Desinstálalo e instala con el script de la v2 (o npm install -g @opencode/cli).

Errores al conectar

/models no enseña el modelo del centro

Causa probable
La config no está donde OpenCode la busca, el JSON tiene un error o el proveedor no se llama centro.
Solución
opencode debug paths config te dice la ruta; revisa el fichero y el nombre.

opencode run se queda esperando

Causa probable
El servidor no responde o no se fía de él: URL mal escrita, falta /v1 o el certificado, no estás en la red del centro o el servidor está caído.
Solución
Ctrl+C. Revisa CENTRO_IA_URL (/v1), NODE_EXTRA_CA_CERTS y la red del aula; si sigue, avisa al profesor.

Error 401/403 o «clave no válida»

Causa probable
La variable no existe en esa terminal: {env:VAR} se sustituye por una cadena vacía. Falta export, o la terminal es anterior al setx.
Solución
echo $CENTRO_IA_KEY (bash) o echo $env:CENTRO_IA_KEY (PowerShell). Si sale vacío: export en ~/.bashrc o setx, y terminal NUEVA.

Errores de configuración

opencode mcp list dice «No MCP servers configured»

Causa probable
Los servidores con disabled: true no salen. O el bloque mcp está mal escrito y OpenCode lo descarta sin avisar: command como cadena, o servidores fuera de mcp.servers.
Solución
Enciende el que necesites. command siempre como array (["npx", "-y", "paquete"]) y cada servidor dentro de mcp.servers.

He cambiado la config y no hace caso

Causa probable
OpenCode trabaja con un servicio de fondo que puede seguir con la config anterior.
Solución
opencode reload, o sal de OpenCode y vuelve a abrirlo.

Una skill no aparece

Causa probable
Le falta description, o la carpeta no se llama como el id que usas.
Solución
La carpeta es el id; description es obligatoria para que el agente la vea.

Errores mientras trabajas

/undo no revierte los ficheros

Causa probable
El proyecto no es un repositorio git, o el fichero está ignorado por git o pasa de 2 MiB.
Solución
git init antes de abrir OpenCode (los commits no hacen falta).

Se ejecutó algo que creía prohibido

Causa probable
Una regla «*: allow» posterior (otra config o un agente) gana a tu deny.
Solución
Lo que nunca debe pasar, en policies (solo pueden negar). Revisa el orden con opencode debug agents.

Respuestas cortadas o «context length exceeded»

Causa probable
Conversación muy larga o demasiados MCP y skills cargados.
Solución
Compacta (ctrl+x c) o abre sesión nueva (/new); apaga los MCP que no uses.

Enlaces