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
- Detectas una tarea que te hace perder tiempo
- La automatizas con tu propia CLI, construida con OpenCode
- 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
Desliza el diagrama de lado para verlo entero
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
readLee un fichero (o un trozo). Como abrirlo en el editor para mirarlo.
globBusca ficheros por nombre o patrón: src/**/*.py. Como el buscador de ficheros.
grepBusca texto dentro de los ficheros. Como Ctrl+Shift+F en VS Code.
webfetchDescarga una página web y la lee. En el proyecto, siempre pregunta antes.
Para cambiar
editCambia unas líneas concretas de un fichero que ya existe. Te enseña el diff antes de aplicarlo (si está en ask).
writeCrea un fichero nuevo o lo reescribe entero. Lo controla el mismo permiso que edit.
shellEjecuta una orden en la terminal: uv run, git status, ls… La más potente y la más peligrosa: por eso pregunta.
Para organizarse
subagentLanza un subagente (general, explore o uno tuyo) para una subtarea. Trabaja en una sesión hija y te devuelve un resumen.
todowriteMantiene una lista de pasos pendientes y hechos. Verás la lista tachándose mientras trabaja.
skillCarga una skill (conocimiento extra) cuando la necesita. Solo carga la que le sirve, no todas.
questionTe 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
Desliza el diagrama de lado para verlo entero
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.)
curl -fsSL https://opencode.ai/v2/install | bashWindows nativo
- Instala Git for Windows: OpenCode ejecuta sus órdenes con Git Bash (sin él, con PowerShell) y sin git no hay
/undode ficheros. - Descarga el zip oficial: opencode-windows-x64.zip.
- Descomprímelo en una carpeta tuya (por ejemplo
C:\opencode) y añade esa carpeta al PATH. - 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:
curl -fsSL https://opencode.ai/v2/install | bashOjo: 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.
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:
mkdir -p ~/.config/opencodecode ~/.config/opencode/opencode.json # o nanoNew-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).
{ "$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(enproviders): el nombre del proveedor; es lo que va antes de la barra enmodel.packageopenai-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 formatoproveedor/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.
# 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"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
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.
opencodeprogramarunsubcomando"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:
cd ~/cli-tareasopencodeLa pantalla de OpenCode
- 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.
- 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.
- Caja de entrada. Escribes la petición. Intro envía; para un salto de línea, shift+enter o ctrl+j.
- Barra inferior. Agente activo (Build o Plan) y modelo. Míralo antes de escribir: ¿estás en el agente que quieres?
- 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:
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+tab
Cambia de agente: build ↔ plan - ctrl+x a
/agentsElegir agente de la lista - Esc
Interrumpe la respuesta en curso - ctrl+p
Paleta 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+c
Salir (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).
Desliza el diagrama de lado para verlo entero
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.
---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
Desliza el diagrama de lado para verlo entero
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é pasaEl * 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 abajo | git diff src/tareas/cli.py | rm -r build |
|---|---|---|
| shell · * → ask | coincide | coincide |
| shell · git diff * → allow | coincide · gana ✓ | no coincide |
| shell · rm * → deny | no coincide | coincide · 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
{ "$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 · * → askCada 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 · * → askSi quiere leer una web, pregunta. Así sabes de dónde saca la información.
external_directory · * → askNada fuera de la carpeta del proyecto sin preguntar (tu carpeta personal, otras prácticas…). De fábrica no pregunta: por eso la regla.
read · * → allowPuede 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 → allowLa plantilla sin claves sí puede leerla (va al final para volver a permitirla).
Parte 2: órdenes
{ "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 · * → askRegla general: cualquier orden pregunta. Es la primera para que las demás la puedan matizar.
shell · ls *, pwd, cat * → allowMirar carpetas y ficheros no rompe nada.
shell · git status *, git diff *, git log * → allowConsultar git tampoco. El agente puede ver qué ha cambiado.
shell · uv run tareas --help, uv run tareas validar * → allowProbar la ayuda y validar acciones.json es inofensivo.
shell · uv run pytest * → allowPasar las pruebas (semana 4).
shell · git commit * → askLos commits los haces tú; si te lo propone, te pregunta (y normalmente dirás que no).
Parte 3: lo que nunca hará
"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 * → denySubir o reescribir historia: nunca el agente.
shell:rm *, shell:sudo * → denyBorrar ficheros o usar permisos de administrador: prohibido.
agents.plan · edit * → denyAl agente plan le quita editar; sus órdenes siguen tus reglas de shell (explicado en Agentes).
agents.explore · edit * → denyLo 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.
Desliza el diagrama de lado para verlo entero
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.
# 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
Desliza el diagrama de lado para verlo entero
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,modelosubagent: 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
@ficherodentro del comando no se adjunta: adjúntalo en la caja al lanzarlo.
---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:
/nueva-accion renombrar-capturas "Renombra las capturas de pantalla con su fecha y un contador"/nueva-accionel comandorenombrar-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;
namees solo una etiqueta. description: imprescindible. Di qué hace y cuándo usarla: sin ella el agente ni la ve.- Compruébalo con
/skillsen la TUI; para forzar que la cargue,@acciones-json.
La skill acciones-json
---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
Desliza el diagrama de lado para verlo entero
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.
{ "$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
commandes 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,/mcpslos 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).
Desliza el diagrama de lado para verlo entero
El flujo, paso a paso
- 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 - 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 - Build
Que lo haga
Shift+Tab a build: «hazlo». Apruebas cada edición y cada orden leyendo el diff.
shift+tab → build - 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 … - 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 - 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.jsonni en el chat. .enven el.gitignoreantes del primer commit; el agente tiene prohibido leerlo.- Permisos del proyecto siempre activos: edición y órdenes en ask;
rm,sudoygit pushen policies. - Nunca
--auto, y always solo para órdenes inofensivas. - Nunca en carpetas reales: las acciones de tu CLI se prueban en
~/pruebas-tareasy 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.
- 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.
- 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).
- 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:
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 MCPErrores 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
Documentación oficial: opencode.ai/v2/docs. Si un tutorial usa permission, agent o bash en singular, es de OpenCode 1: la 2 todavía lo entiende, pero aquí escribimos la sintaxis nueva.
