Dar acceso a un agente de IA

Cómo funciona el acceso

Las personas inician sesión en la consola con Google, a través de Cloudflare Access (inicio de sesión único). Los agentes de IA nunca usan ese inicio de sesión: cada agente obtiene su propio service token, que creas en la consola. Un token tiene nombre, alcance y caducidad; solo tú, con sesión iniciada, puedes crearlo o revocarlo; y todo lo que un agente cambie queda en el registro de auditoría. Los cambios del agente pasan por la misma validación y la misma canalización de publicación que los tuyos: no hay que volver a desplegar a mano.

1. Inicia sesión

Abre https://admin.jenksguo.xyz/admin (para el sitio de desarrollo: https://admin.dev.jenksguo.xyz/admin). Cloudflare te pedirá que inicies sesión; usa tu cuenta de Google. La consola se abre con tu correo en la esquina superior izquierda.

2. Crea el token

1. Elige Access en la barra superior.
2. En New agent token, ponle un nombre según el agente y la máquina, por ejemplo Claude Code on MacBook.
3. Elige lo que puede hacer (los alcances están en la tabla de abajo). Sin publish, el agente guarda en la rama dev; tú revisas https://dev.jenksguo.pages.dev y promocionas el cambio tú mismo.
4. Elige cuándo caduca (90 días por defecto) y selecciona Create token.
5. Copia el token ahora. Empieza con jgx_agt_ y solo se muestra una vez; el sitio guarda solo su hash.

Alcance	Permite
(siempre)	Leer: esquema, archivos, traducciones, texto del sitio, lista de medios, estado de despliegue
content	Escribir archivos de contenido, traducciones y texto del sitio
media	Subir, describir y borrar imágenes, video y PDF
publish	Escribir en main (el sitio en vivo) y promocionar dev → main

Guarda el token donde el agente pueda leerlo pero las personas no puedan verlo — por ejemplo, el macOS Keychain — y nunca lo pegues en un chat, un commit o un archivo de contenido.

3. Conecta el agente

El token va en el encabezado Authorization. Usa https://jenksguo.pages.dev (o el espejo https://jenksguo.xyz); el host de administración es para personas.

MCP (Claude Code y otros clientes MCP):

claude mcp add --transport http jenks-admin https://jenksguo.pages.dev/mcp/admin \
  --header "Authorization: Bearer $JENKSGUO_ADMIN_TOKEN"

CLI (también un servidor MCP local con jenks mcp --admin):

export JENKSGUO_ADMIN_TOKEN=jgx_agt_…   # from your Keychain or password manager
jenks admin whoami                      # who the token is, its scopes and expiry

REST:

curl -H "Authorization: Bearer $JENKSGUO_ADMIN_TOKEN" https://jenksguo.pages.dev/api/admin/whoami

4. Revisa lo que hicieron los agentes

Access → Audit log enumera cada escritura de administración y cada intento rechazado, de más reciente a más antiguo: quién (tu correo o agent:<name>), qué herramienta, qué archivos, rama y resultado. Un agente puede leer sus propias entradas con jenks admin audit o la herramienta admin_audit_log. Cada commit que haga también lo nombra en el mensaje del commit.

5. Revoca

Selecciona Revoke junto al token. La siguiente solicitud del agente fallará con token_revoked. Los tokens también se detienen en su fecha de caducidad (token_expired); crea uno nuevo cuando eso ocurra.

Solución de problemas

• 401 unknown_token — el token es incorrecto o está incompleto; cópialo de nuevo o crea uno nuevo.
• 403 missing_scope — al token le falta un alcance para esa herramienta. El mensaje lo nombra. Para publish, guarda en dev en su lugar, o crea un token con publish.
• 403 sso_required — gestionar tokens requiere tu inicio de sesión de Google en el host de administración; los agentes no pueden crear tokens.