Claude Code con un vault de Obsidian en un VPS

Por qué Claude Code funciona con un vault de Obsidian

Un vault de Obsidian es una carpeta de archivos Markdown, por lo que Claude Code puede trabajar con él del mismo modo que trabaja con un repositorio de código. El sitio oficial de Obsidian indica que «almacena las notas localmente como archivos Markdown de texto sin formato», y la ayuda de Obsidian define un vault como «una carpeta del sistema de archivos local donde Obsidian almacena las notas». No hay ninguna base de datos intermedia ni un paso de exportación.

Ese hecho explica por completo por qué la combinación funciona. Claude Code ya lee directorios, busca texto, edita archivos directamente y ejecuta comandos de shell. Un vault le proporciona archivos Markdown, el front matter YAML situado al principio de cada archivo, los enlaces entre notas y un árbol de directorios con significado. Reubicar una captura y reconstruir un índice son operaciones normales con archivos. No interviene ningún plugin de Obsidian y Obsidian no tiene que estar ejecutándose en el equipo donde trabaja el agente.

El problema es que las notas no son código. Una prueba fallida indica cuándo un agente ha roto una compilación. Nada indica cuándo un agente ha reformulado silenciosamente cuarenta notas. La mayor parte de esta guía trata de recuperar esa red de seguridad.

Qué ofrece ejecutar el vault en un VPS

Ejecutar Claude Code contra un vault en el portátil funciona y, para una tarea de cinco minutos, es la opción adecuada. Mover el vault a un servidor cambia lo que puede pedirle de forma razonable.

• La sesión sobrevive al portátil. Inicie el agente dentro de una sesión de tmux en el servidor y una tarea larga seguirá ejecutándose con la tapa cerrada.
• El vault está disponible desde cualquier lugar donde pueda abrir una conexión SSH, incluido un teléfono.
• El agente se ejecuta en una máquina que no usa a diario, por lo que un error queda contenido en un equipo que puede reconstruir.
• La sincronización sigue ejecutándose en el servidor, por lo que la copia que edita el agente es la misma que abre el teléfono unos segundos después.

La sesión persistente es lo más importante y usa la misma configuración que ejecutar Claude Code en un VPS dentro de tmux. La forma de acceder a esa sesión desde un teléfono se explica en controlar Claude Code desde el teléfono. Cuando una tarea larga de reorganización ocupa una sesión y inicia una segunda junto a ella, una sesión puede entregar trabajo a la otra en lugar de tener que transmitir el resultado manualmente.

Coloque el vault en el servidor

Asigne al vault su propio directorio. Copie un vault existente desde su portátil con rsync. Este comando se ejecuta en el portátil, no en el servidor.

rsync -av --exclude '.obsidian/workspace*.json' \
  ~/Documents/notes/ you@your-vps:vaults/notes/

Después, compruebe qué se ha copiado. Esta vez, en el servidor:

ls -a ~/vaults/notes
du -sh ~/vaults/notes

Debería ver las carpetas de nivel superior y un directorio .obsidian. .obsidian contiene la configuración propia del vault, incluidos app.json y workspace.json. workspace.json registra qué paneles están abiertos, por lo que cambia cada vez que mueve un panel en la aplicación de escritorio. Por eso la línea rsync lo excluye: copiarlo entre equipos genera cambios constantes y no aporta nada.

Sincronice el almacén con su portátil y su teléfono

Syncthing mantiene sincronizada la copia del servidor con sus dispositivos sin que un tercero almacene los archivos. Instálelo desde el repositorio apt del propio proyecto.

sudo mkdir -p /etc/apt/keyrings
sudo curl -L -o /etc/apt/keyrings/syncthing-archive-keyring.gpg https://syncthing.net/release-key.gpg
echo "deb [signed-by=/etc/apt/keyrings/syncthing-archive-keyring.gpg] https://apt.syncthing.net/ syncthing stable-v2" \
  | sudo tee /etc/apt/sources.list.d/syncthing.list
sudo apt-get update
sudo apt-get install syncthing

Ejecútelo como un servicio del sistema asociado a su cuenta de usuario:

sudo systemctl enable syncthing@$USER.service
sudo systemctl start syncthing@$USER.service
systemctl status syncthing@$USER.service

status debe mostrar active (running). La interfaz web escucha en 127.0.0.1:8384 de forma predeterminada, por lo que no está expuesta a Internet y no necesita una regla de firewall para ella. Acceda a ella mediante un reenvío del puerto por SSH desde su portátil:

ssh -L 8384:127.0.0.1:8384 you@your-vps

Mientras la conexión esté activa, abra http://127.0.0.1:8384 en el navegador, añada ~/vaults/notes como carpeta y empareje su portátil. Syncthing es compatible con Linux, macOS, Windows y Android. La aplicación oficial para Android dejó de publicar versiones a finales de 2024, y la compilación comunitaria que se utiliza en su lugar es Syncthing-Fork en F-Droid (comprobado en agosto de 2026). La FAQ del propio Syncthing indica: "El equipo actual de Syncthing no tiene previsto ofrecer compatibilidad oficial con iOS en un futuro previsible", por lo que un iPhone necesita un cliente de terceros o una herramienta completamente distinta. Si prefiere mantener los archivos detrás de un servidor que ya administra, la comparación entre Syncthing y Nextcloud explica las diferencias.

Instalar Claude Code junto al vault

curl -fsSL https://claude.ai/install.sh | bash
claude --version

Una instalación correcta muestra una versión como 2.1.211 (Claude Code). Si el shell responde claude: command not found, el instalador colocó el binario en ~/.local/bin/claude y ese directorio no está incluido en PATH. Añádalo al perfil del shell y abra un shell nuevo. claude doctor muestra diagnósticos de la instalación y la configuración sin iniciar una sesión. Es la forma más rápida de determinar qué falla.

Claude Code necesita una cuenta Pro, Max, Team, Enterprise o Console. El plan gratuito de Claude.ai no incluye acceso. Inícielo dentro del vault, porque el directorio de trabajo es el que sus herramientas de archivos alcanzan de forma predeterminada:

tmux new -s vault
cd ~/vaults/notes
claude

Sepárese con Ctrl-b y después d. La sesión seguirá ejecutándose. Vuelva a conectarse más tarde con tmux attach -t vault. Si la sesión de Claude ha terminado y no sólo se ha separado, claude --resume la recupera. Reanudar una sesión y encontrar su transcripción explica dónde se guardan esas transcripciones en el servidor cuando necesite revisar lo que el agente hizo realmente en sus notas.

Escriba un CLAUDE.md que defina las convenciones del vault

Claude Code carga CLAUDE.md desde el directorio de trabajo y desde todos los directorios superiores al inicio de cada sesión. En un repositorio de código, la mitad de las convenciones son visibles en el propio código. En un vault no lo son: ningún archivo indica que 00-inbox/ es un área de staging o que las notas archivadas están congeladas. Escriba estas reglas o el agente tendrá que adivinarlas.

# Vault conventions

## Layout
- `00-inbox/` holds unfiled captures. Only I write here.
- `10-notes/` holds permanent notes, one idea per file.
- `20-daily/` holds daily notes named `YYYY-MM-DD.md`.
- `90-archive/` is frozen. Never edit anything under it.

## Rules
- Every note opens with an H1 that matches its filename.
- Front matter holds `tags` and `created` only. Do not invent fields.
- Link by note name using Obsidian double bracket links. No paths, no `.md`.
- Never rename or move a file. Ask me instead.
- Never edit more than five files in one go without listing them first.

Manténgalo por debajo de 200 líneas. La documentación de Claude Code establece ese objetivo porque un archivo más largo consume una parte mayor de la ventana de contexto y se sigue de forma menos coherente. Confirme que se ha cargado ejecutando /context en una sesión y comprobando la lista de Memory files. Claude Code lee CLAUDE.md, no AGENTS.md, así que, si ya utiliza uno de ellos para otra herramienta, consulte cómo se relacionan AGENTS.md y CLAUDE.md. Un vault con miles de notas alcanza los mismos límites que un repositorio grande; gestionar el contexto en Claude Code explica este tema.

Reglas de permisos para que nada se reescriba en bloque

Guárdelo como .claude/settings.json dentro del vault.

{
  "permissions": {
    "defaultMode": "plan",
    "deny": [
      "Read(/90-archive/**)",
      "Edit(/90-archive/**)",
      "Bash(rm *)"
    ],
    "ask": [
      "Bash(git push *)",
      "Bash(mv *)"
    ],
    "allow": [
      "Bash(git status)",
      "Bash(git diff *)"
    ]
  }
}

Conviene conocer cuatro aspectos de ese archivo, porque cada uno ha causado problemas.

• Las reglas se evalúan primero con deny, después con ask y por último con allow. La primera coincidencia decide. La especificidad no cambia el orden, por lo que una regla deny general no puede contener dentro una excepción incluida en allow.
• Una regla deny de Read también bloquea las herramientas Edit y Write en la misma ruta, incluida la creación de un archivo nuevo allí. Añadir la regla Edit correspondiente no tiene ningún coste y cubre la única herramienta integrada que la regla Read no alcanza.
• Claude Code comprueba las rutas de archivos sólo con las reglas Edit(path) y Read(path). Si escribe una regla de ruta Write(...) o Glob(...), se acepta, pero nunca se consulta y se informa durante el arranque como una regla que no coincide con las comprobaciones de permisos de archivos. Use Edit(...) cuando quería usar Write(...).
• permissions.defaultMode establecido en plan significa que Claude lee archivos y ejecuta comandos de sólo lectura, pero no edita sus notas hasta que usted aprueba un plan. acceptEdits hace lo contrario y acepta todas las ediciones de archivos sin preguntar. Para un vault, plan es el valor predeterminado adecuado.

Las reglas Read y Edit usan la sintaxis de patrones de gitignore. La barra inicial de Read(/90-archive/**) ancla el patrón a la raíz del proyecto, por lo que coincide con 90-archive/ en el nivel superior del vault y con ninguna otra ruta. Sin la barra, una regla deny coincide con un directorio de ese nombre en cualquier nivel bajo el vault, que es lo que normalmente se desea para una carpeta llamada Private. Cuando se aplica una regla, la herramienta devuelve File is covered by a Read deny rule in your permission settings.

Conviene indicar claramente un límite. Estas reglas cubren las herramientas de archivos integradas de Claude y los comandos de archivos que reconoce en Bash, como cat, head, tail y sed. No cubren un script que abre un archivo por su cuenta. Por eso, la primera línea de defensa es la ubicación y no la configuración: si un modelo no debe leer algo bajo ninguna circunstancia, ese contenido no debe estar bajo la raíz del vault. Las reglas deny son la segunda capa. Ejecutar Claude Code de forma segura en un VPS cubre el aspecto del servidor, y modo automático y configuración de permisos explica los modos con más detalle.

Git en el vault es el botón para deshacer

Un vault no tiene una suite de pruebas, por lo que el control de versiones es toda la red de seguridad. Convierta el vault en un repositorio antes de que el agente pueda acceder a él.

cd ~/vaults/notes
git init
printf '.obsidian/workspace*.json\n.trash/\n*.sync-conflict-*\n' >> .gitignore
git add -A
git commit -m "Vault before the agent touches it"

Haga un commit antes de iniciar un trabajo, no después. Un árbol limpio al comenzar garantiza que las diferencias resultantes corresponden al trabajo del agente y a nada más. git status debe mostrar nothing to commit, working tree clean antes de cada solicitud que modifique archivos.

git diff --stat
git restore .

git diff --stat muestra todos los archivos modificados y cuántas líneas se movieron en cada uno. Si esa lista es más larga de lo esperado, git restore . descarta todos los cambios sin commit del árbol de trabajo y devuelve el vault a su estado inicial. Si ya hizo un commit, git revert <sha> crea un commit nuevo que revierte el anterior.

Hay una trampa en la combinación de git y la sincronización. Si Syncthing comparte la carpeta del vault, replica .git junto con todo lo demás, y dos máquinas que escriben el índice de git al mismo tiempo generan archivos de conflicto dentro del repositorio. Mantenga git sólo en el servidor y añada .git a un archivo .stignore en la raíz del vault:

.git
.obsidian/workspace*.json

Tres tareas que conviene delegar

Estas son instrucciones, no scripts. Cada una está redactada para que el resultado se pueda comprobar después con git diff --stat.

Reconstruir una nota de índice

Read every file in 10-notes/ and rewrite 10-notes/index.md so it lists each
note under its primary tag, sorted alphabetically within each tag, using the
one-line summary from each note's front matter. Change no file except
index.md. Show me the plan before you write anything.

La restricción está en la instrucción y también es lo que se verifica. git diff --stat debería indicar un solo archivo. Si indica más, ejecute git restore . y formule la instrucción de manera más específica.

Buscar huérfanos y enlaces rotos

List every note in 10-notes/ that no other note links to, and every link in
the vault that points at a file that does not exist. Write the results to
90-reports/orphans.md and edit nothing else.

La auditoría de enlaces es una búsqueda de texto en todo el vault, que es el tipo de tarea que esta herramienta realiza con mayor rapidez. Es de solo lectura, salvo por un archivo de informe, por lo que es una primera tarea razonable mientras todavía aprende cómo trabaja el agente con sus notas.

Convertir un volcado de reunión en tareas

Read 00-inbox/2026-08-19-standup.md. For each action item, create one file in
10-notes/tasks/ named after the action, with front matter holding owner, due
and status. Leave the source file untouched. List the files you created.

No se modifica nada de lo que ya existe, por lo que la reversión consiste en eliminar los archivos nuevos. Esta propiedad es lo que hace que una tarea sea segura de probar, más que cualquier redacción de la instrucción.

Revise siempre el diff. Un CLAUDE.md contiene directrices que el modelo lee, pero no es una regla que el cliente imponga. Por tanto, trate la lista de archivos de git diff --stat como el registro real de lo que ocurrió.

Qué puede fallar

Una lectura falla con File is covered by a Read deny rule in your permission settings. Una regla de denegación coincide con una ruta que quería leer. Un patrón de directorio de un solo segmento sin anclaje en una regla de denegación coincide a cualquier profundidad, por lo que Read(archive/**) también bloquea 10-notes/archive/. Ancle el patrón con una barra inicial para limitarlo a una única ubicación.

Claude Code muestra al inicio que una regla no coincide con las comprobaciones de permisos de archivos. Escribió una regla de rutas para una herramienta que las comprobaciones de archivos nunca consultan. Sustituya Write(90-archive/**) por Edit(90-archive/**) para eliminar la advertencia.

Los archivos aparecen con sync-conflict en el nombre. Syncthing cambia el nombre de uno de los lados de una edición simultánea usando el patrón <filename>.sync-conflict-<date>-<time>-<modifiedBy>.<ext>. Esto ocurre cuando el agente edita una nota en el servidor mientras usted tiene abierta la misma nota en el portátil. Edite en un solo lugar cada vez y espere a que la sincronización termine antes de cambiar de dispositivo.

Los enlaces se rompen después de que el agente mueve una nota. Obsidian reescribe los enlaces internos cuando el cambio de nombre se realiza dentro de Obsidian. No puede detectar un cambio de nombre realizado por otro proceso, por lo que un archivo movido por un agente en el servidor deja todos los enlaces apuntando al nombre anterior. Por eso «nunca cambie el nombre de un archivo ni lo mueva» debe figurar en el archivo CLAUDE.md del vault, y por eso los cambios de nombre deben hacerse en la aplicación de escritorio.

El agente edita notas que nunca mencionó. Compruebe permissions.defaultMode. En acceptEdits todas las ediciones de archivos se aceptan sin solicitar confirmación. Establézcalo en plan para que la sesión comience en modo de solo lectura hasta que apruebe un plan.

FAQ

¿Necesito un plugin de Obsidian para usar Claude Code con mi vault?

No. Obsidian almacena las notas como archivos Markdown de texto sin formato en una carpeta normal, por lo que Claude Code las lee y edita con sus herramientas de archivos habituales. No se instala nada dentro de Obsidian y Obsidian no tiene que estar en ejecución. El agente trabaja con los archivos, y Obsidian es uno de varios programas que también los leen.

¿Cómo impido que Claude Code lea notas privadas de mi vault?

Manténgalas fuera del directorio del vault. Esa es la medida efectiva, porque las reglas de permisos cubren las herramientas de archivos integradas de Claude y los comandos de archivos de Bash que reconoce, pero no un script que abra un archivo directamente. Como segunda capa, añada reglas de denegación para Read y Edit a la ruta de .claude/settings.json. Pruebe la regla pidiendo a Claude que abra un archivo de esa ubicación: una lectura bloqueada devuelve File is covered by a Read deny rule in your permission settings.

¿Claude Code dañará mis enlaces de Obsidian?

Puede hacerlo de una forma concreta. Obsidian actualiza los enlaces internos cuando cambia el nombre de una nota dentro de Obsidian, pero no puede detectar un cambio de nombre realizado por otro proceso. Si un agente mueve un archivo en el servidor, los enlaces seguirán apuntando al nombre anterior. Indique en su CLAUDE.md que el agente nunca debe cambiar de nombre ni mover archivos, y haga esos cambios de nombre en la aplicación de escritorio. Editar el contenido de una nota es seguro, porque los enlaces son texto sin formato dentro del archivo.

¿Puedo ejecutar esto con un vault de mi portátil en lugar de un VPS?

Sí. El CLAUDE.md, las reglas de permisos y los hábitos de git son idénticos. Lo que añade un servidor es una sesión que sobrevive al cierre de la tapa y el acceso desde cualquier dispositivo que pueda abrir una conexión SSH. Si ninguna de esas ventajas es necesaria para el trabajo actual, ejecútelo localmente. Si lo que busca es no tener que mantener una máquina, Cowork se ejecuta en un sandbox de Anthropic con las carpetas que conecte, y cómo se comparan Cowork y Claude Code explica cuál se adapta mejor a un vault como este.

¿El vault tiene que ser un repositorio de git?

No para que Claude Code funcione, pero sí por seguridad. Un vault no tiene una suite de pruebas, por lo que git diff --stat después de un trabajo es la forma más barata de ver qué cambió realmente, y git restore . es la forma más barata de deshacerlo. Haga un commit antes de cada trabajo para que el diff muestre sólo el trabajo del agente. Si Syncthing comparte la carpeta, añada .git a .stignore para que el repositorio no se replique entre dispositivos.