Conectar API de Notion a OpenClaw: Dale ojos a tu agente para leer tus notas 🦞📝
Ultima actualizacion:

¿Por qué no puedo simplemente mandarle un link de Notion a OpenClaw?

Si llegaste aquí probablemente ya intentaste lo mismo que yo: agarrar el link público de tu página de Notion, mandárselo a tu OpenClaw y esperar que lo leyera como cualquier página web. Spoiler: no funciona.

El web_fetch de OpenClaw sí puede leer páginas web normales (HTML estático, SSR, etc.), pero Notion es una Single Page Application (SPA) — una app construida casi enteramente con JavaScript del lado del cliente. Cuando web_fetch solicita una URL de Notion, lo que recibe es un cascarón vacío: un HTML con un <div></div> y un montón de scripts que dicen “espérame, ahorita cargo el contenido”. Pero web_fetch no ejecuta JavaScript, así que se queda con la cáscara vacía.

Es como pedir una pizza y que te den la masa cruda con una nota que dice “métela al horno tú”.

Para comprobarlo, puedes hacer la misma prueba que hice yo: mándale a tu OpenClaw el link de cualquier página web estática (un blog personal, por ejemplo) y verás que la lee sin problemas. Luego mándale un link de Notion y solo obtendrás el título “Notion” y un aviso de seguridad.

Diagrama comparativo: web_fetch falla con Notion SPA pero la API oficial funciona correctamente

La solución: conectar OpenClaw directamente a la API oficial de Notion. En vez de intentar scrapear la página, le das a tu OpenClaw una llave para entrar por la puerta principal.

Flujo de conexion de OpenClaw a Notion via API Key

Pre-requisitos

  • OpenClaw corriendo en Docker (en mi caso: AlmaLinux, 2GB VRAM, 2GB swap, 2 vCores, 100GB SSD)
  • Acceso al dashboard web de OpenClaw
  • Una cuenta de Notion con permisos para crear integraciones

Paso 1 — Crear una integración interna en Notion

  1. Ve a notion.so/my-integrations
  2. Crea una nueva integración interna
  3. Copia el token (empieza con ntn_ o secret_)
  4. Guárdalo en un lugar seguro temporalmente

Paso 2 — Guardar el token en tu VPS

Aquí tienes dos opciones principales. Ambas funcionan, pero una es más limpia que la otra.

Opción A: Hardcodearlo directo en docker-compose.yml (solo para pruebas rápidas)

services:
  openclaw-gateway:
    environment:
      - NOTION_API_KEY=ntn_tu_token_super_secreto

Tu token queda en texto plano (plaintext) directamente en el archivo. Si algún día haces git push de tu configuración por accidente, acabas de regalarle tu token al mundo (leaked secret).

Veredicto: Solo para pruebas donde no te importa la seguridad.

Opción B: Archivo .env — La forma recomendada ✅

Crea un archivo .env en el mismo directorio donde vive tu docker-compose.yml:

NOTION_API_KEY=ntn_tu_token_aqui

En tu docker-compose.yml referéncialo con interpolación de variables:

services:
  openclaw-gateway:
    environment:
      - NOTION_API_KEY=${NOTION_API_KEY}

Docker Compose lee automáticamente el .env que esté al lado del docker-compose.yml — ni siquiera necesitas declarar env_file:, es syntactic sugar que ya viene de serie.

Después asegura el archivo:

chmod 600 ~/openclaw/.env

⚠️ Cuidado con los permisos: El .env lo lee docker compose desde el host, antes de levantar el contenedor. El usuario que ejecuta docker compose up -d es quien necesita permiso de lectura. Si creaste el .env con sudo, el dueño será root y con chmod 600 tu usuario normal quedará fuera.

Fix rápido:

sudo chown tu_usuario:tu_usuario ~/openclaw/.env
chmod 600 ~/openclaw/.env

Si usas AlmaLinux (o cualquier distro con SELinux), puede que también necesites ajustar el contexto de seguridad:

restorecon -v ~/openclaw/.env
# O si no funciona:
chcon -t container_file_t ~/openclaw/.env

Y asegúrate de que .env esté en tu .gitignore:

echo ".env" >> .gitignore

Esta es la opción que yo usé.

Comparativa visual entre hardcodear el token y usar archivo .env

Paso 3 — Verificar que la skill de Notion esté disponible

La skill de Notion ya viene built-in en OpenClaw, así que no necesitas instalar nada extra. Pero si eres como yo y necesitas verlo con tus propios ojos, tienes dos formas de comprobarlo:

Desde el dashboard web

Accede a tu dashboard de OpenClaw y ve a la sección Skills. Ahí debería aparecer Notion como skill disponible.

Tip para acceder al dashboard: Si tu OpenClaw corre en un VPS, necesitas port forwarding SSH:

ssh -L 18789:127.0.0.1:18789 tu_usuario@tu-vps-ip

Y luego abres en tu navegador local: http://127.0.0.1:18789?token=TU_TOKEN

💡 Si no recuerdas tu token del dashboard, puedes obtenerlo desde dentro del contenedor:

docker exec -it tu-contenedor node dist/index.js dashboard --no-open

O buscarlo manualmente:

docker exec -it tu-contenedor cat /home/node/.openclaw/openclaw.json | grep gatewayToken

⚠️ Nota sobre bind: Si tu config tiene "bind": "loopback", el dashboard solo será accesible desde http://localhost/. Si necesitas acceder vía SSH tunneling, cambia a "bind": "lan" en tu openclaw.json. Para la mayoría de setups con port forwarding SSH, loopback funciona bien.

Desde la terminal (para calmar la ansiedad)

docker exec -it tu-contenedor node dist/index.js skills list | grep -i notion

⚠️ Notas importantes sobre el CLI dentro de Docker:

  • El binario openclaw como tal no existe dentro del contenedor gateway. Todos los comandos se ejecutan con node dist/index.js.
  • El subcomando es skills (plural), no skill.
  • skills solo lista e inspecciona — no tiene install. La instalación de skills se hace desde el dashboard o con la herramienta clawhub.

Paso 4 — Compartir tus páginas con la integración desde Notion

Este es el paso que todo mundo olvida y luego se queda media hora debuggeando un 403 Forbidden.

Las integraciones internas de Notion usan un modelo de permisos explícitos — no tienen acceso a nada por default. Tienes que ir página por página e invitar a tu integración manualmente.

Para cada página o base de datos que quieras que OpenClaw lea:

  1. Abre la página en Notion
  2. Click en los tres puntitos ... (arriba a la derecha)
  3. Busca “Add connections” (o “Conectar a” en español)
  4. Selecciona el nombre de tu integración

💡 Tip: Si compartes una página padre, las subpáginas heredan el acceso. Si tienes un workspace organizado con una página raíz tipo “Wiki” o “Documentación”, basta con compartir esa raíz y todo lo que cuelga de ella queda accesible.

Paso 5 — Probar que todo funciona

Manda un mensaje a tu OpenClaw y pídele algo como:

Lee el contenido de mi página de Notion con ID 31161db7db7f8103a9f1c48ac9be085f

El page_id es el UUID largo que aparece en tu URL de Notion.

¿Siempre debo usar el page_id?

No necesariamente. La skill de Notion usa la Search API por detrás, así que también puedes referirte a tus páginas por título:

Lee mi página de Notion llamada "Configurar API Keys en OpenClaw"

Eso sí, el page_id es más preciso — es como la diferencia entre buscar a alguien por nombre (puede haber duplicados) versus buscarlo por CURP (único e irrepetible). Si tienes páginas con títulos similares, el ID es más confiable.

Smoke test desde la terminal

Si algo falla, puedes verificar que el token funciona directamente con curl desde dentro del contenedor:

docker exec -it tu-contenedor bash

Y dentro:

curl -s "https://api.notion.com/v1/pages/TU_PAGE_ID" \
  -H "Authorization: Bearer $NOTION_API_KEY" \
  -H "Notion-Version: 2022-06-28" | head -c 500

Si ves un JSON con las propiedades de tu página, el pipeline está completo.

Errores comunes

ErrorCausa probableSolución
403 ForbiddenLa página no está compartida con tu integraciónVe a Notion → página → ... → Add connections → selecciona tu integración
404 Not FoundEl page_id es incorrecto o no existeVerifica el UUID en la URL de Notion (el string largo después del último -)
401 UnauthorizedToken inválido, expirado o mal copiadoRegenera el token en notion.so/my-integrations y actualiza tu .env
ECONNREFUSEDLa variable de entorno no llegó al contenedorVerifica con docker exec tu-contenedor env | grep NOTION que la variable existe
Rate limitedDemasiadas peticiones a la API de NotionEspera unos minutos, Notion tiene un límite de ~3 requests/segundo por integración

Ver logs

docker compose logs -f tu-contenedor | grep -i notion

Resumen

Diagrama resumen de los 5 pasos para conectar Notion a OpenClaw

  1. Crear integración en notion.so/my-integrations
  2. Guardar token en .env + referenciarlo en docker-compose.yml
  3. Verificar skill — ya viene built-in, confírmalo desde el dashboard o terminal
  4. Compartir páginas — “Add connections” en cada página o página padre
  5. Probar — por título o page_id, y revisar logs si algo falla

Escrito mientras configuro mi propia langosta para que lea mis notas. 🦞

Serie OpenClaw

Si llegaste hasta aquí, probablemente te interesen los demás artículos de esta serie:

  1. OpenClaw: El Asistente de IA Personal que Corre en Tu Propia Máquina 🦞
  2. Guía: Instalar OpenClaw en un VPS Barato con AlmaLinux 🐧
  3. Conectar OpenClaw a WhatsApp y Telegram 🦞💬
  4. Configurar API Keys en OpenClaw 🔑🦞
  5. Conectar API de Notion a OpenClaw 🦞📝 ← Estás aquí