Configurazione

ZenCopy funziona subito, senza configurare nulla. Questa pagina è per quando vuoi che ti si adatti meglio. La prima metà, sulla finestra delle impostazioni, è per tutti; la seconda metà, sui file di configurazione, è per utenti esperti.

La finestra delle impostazioni

Aprila dal menu dell’icona nella barra di sistema, o dall’icona a ingranaggio sul popup. Ha tre schede: Generali, IA e Azioni.

Generali

• Posizione del popup — in quale angolo dello schermo appaiono i risultati.
• Tema — chiaro / scuro / segui il sistema.
• Lingua — la lingua dell’interfaccia (segue il sistema operativo per impostazione predefinita).
• Avvia all’accesso — avere ZenCopy pronto ogni volta che il computer è acceso.
• Conferma prima di inviare — se chiedere una conferma prima che immagini o file vadano all’IA.

IA

Qui cambi il servizio di IA (provider, modello, chiave API). Il pulsante Prova ti dice subito se la connessione funziona.

La scheda ha anche un campo Su di te. È uno spazio dove descrivere il tuo ruolo e le tue preferenze in poche frasi semplici, in qualsiasi lingua.

Esempio: “Commerciale. Scrivo soprattutto e-mail ai clienti — cortesi ma non rigide, la conclusione per prima.”

Con questo campo compilato, ogni azione adatta i risultati a te. Le spiegazioni arrivano al tuo livello di conoscenza, e le bozze tornano nel tono che preferisci. Non influisce mai sui compiti non pertinenti, e il testo in sé non compare mai nei risultati.

Azioni

L’elenco di “cosa succede dopo una doppia copia”.

• Le azioni preinstallate possono essere aperte e lette — fanno anche da esempi svolti.
• Una nuova azione richiede solo un nome e cosa vuoi che faccia. Per esempio: nome “Riassunto in 3 righe”, istruzione “Riassumi in 3 righe”.
• Non ti senti sicuro nello scrivere le istruzioni? Annota all’incirca cosa vuoi e premi Bozza con IA — l’IA che hai configurato la trasforma in un’istruzione ben formulata.
• Routing ti permette di scegliere un’azione diversa per ogni tipo di contenuto (testo / immagine / file).

Le azioni che crei possono essere condivise: Esporta (.md) ne scrive una come file, e chi la riceve non deve far altro che incollarla in Importa o scegliere il file.

Preferisci affidare l’intero lavoro a un’IA? Qualsiasi chat IA può scrivere un’azione pronta per l’importazione per te: incolla questo testo e compila lo spazio vuoto:

Leggi https://zencopy.app/llms-full.txt — la documentazione completa di ZenCopy, incluso il formato del file di azione, le variabili di modello e il funzionamento del routing. Quindi scrivi un'azione ZenCopy che faccia quanto segue: [cosa desideri]. Genera un file di azione completo (Markdown con frontmatter) in un singolo blocco di codice, pronto per essere incollato in Impostazioni → Azioni → Importa di ZenCopy. Se l'azione ha senso solo in un'app specifica o su un sito specifico, aggiungi una frase che mi indichi quale regola di routing impostare.

Il blocco di codice nella risposta va direttamente in Impostazioni → Azioni → Importa. Per domande a cui la documentazione non può rispondere (“ZenCopy potrebbe persino fare…?”), un clic impacchetta il codice sorgente pertinente — consegna il risultato alla stessa IA.

File di configurazione (per utenti esperti)

Da qui in poi, questa pagina parla di modificare direttamente file di testo. Tutto l’essenziale è disponibile dalla finestra delle impostazioni, quindi puoi tranquillamente smettere di leggere qui.

I file vengono letti dalla directory di configurazione dell’app, per utente. Il percorso esatto viene anche scritto nel log all’avvio:

Windows

%APPDATA%\app.zencopy

macOS

~/Library/Application Support/app.zencopy

Linux

~/.config/app.zencopy

I valori predefiniti del routing sono incorporati nell’app; routing.json non fa altro che sovrascriverli. I file delle azioni sono additivi: definiscono nuove azioni, e le integrate sono intoccabili (un file locale che rivendica l’id di un’azione integrata viene ignorato). Le modifiche si applicano al trigger successivo — nessun riavvio necessario.

ai-sdk-catalog.json

I provider più una mappatura role → model. La casa del formato di file è ai-sdk-catalog — ogni campo è documentato lì (incluso uno $schema per la validazione e il completamento nell’editor), e examples/ contiene configurazioni in tre taglie. Per punti di partenza in stile ZenCopy (ciò che scrive l’interfaccia delle impostazioni, Ollama in locale, role per le azioni), vedi le Ricette.

Un requisito è di ZenCopy, non del formato: roles deve sempre includere default. Ogni azione viene eseguita con esso a meno che il suo frontmatter non nomini un altro role, e il test di connessione nelle impostazioni lo usa per il ping.

Le chiavi API vanno direttamente in questo file locale (l’interfaccia delle impostazioni scrive lo stesso formato); non lasciano mai la tua macchina. Le variabili d’ambiente non vengono lette — le app con interfaccia grafica sono avviate dal sistema operativo, non dalla tua shell, quindi le variabili esportate in .zshrc e simili non le raggiungono mai. Il file viene validato con lo schema a ogni lettura. Una modifica errata appare come messaggio chiaro nel popup e nell’editor delle impostazioni — niente fallisce in silenzio.

routing.json

Quale azione gestisce quale tipo di cattura: una mappa piatta kind → action più un elenco overrides opzionale e a priorità più alta (vince la prima corrispondenza). I quattro kind sono text, rich_text, image e files; in partenza il testo è instradato su Zen, immagini e file su Spiega. La mappa piatta è modificabile nell’app (Impostazioni → Azioni → Routing), quindi devi toccare questo file solo per gli overrides.

{
  "text": "zencopy-zen",
  "rich_text": "zencopy-zen",
  "image": "zencopy-explain",
  "files": "zencopy-explain",
  "overrides": [{ "when": { "app_name": "Slack", "min_chars": 200 }, "action": "summarize" }]
}

Condizioni di when: kind, app_name, exec_name, window_title, url (tutte con wildcard *), file_name (una wildcard a cui deve corrispondere il nome di ogni file copiato, senza distinzione tra maiuscole e minuscole — ad es. *.pdf), più min_chars / max_chars.

Per le catture image e files, il contenuto stesso viene inviato al modello (fino a 10 MB totali per cattura). I tipi di file sono rilevati dal contenuto, non dai nomi: immagini, PDF e audio vengono allegati così come sono, mentre i file di testo (Markdown, codice sorgente, CSV, …) diventano il testo della cattura ({{ text }}) e si comportano esattamente come se ne avessi copiato il contenuto. Anche i documenti di Office (Word, Excel, PowerPoint) diventano testo: il loro contenuto viene estratto e inviato, ma non il layout e le immagini. Le codifiche dei caratteri vengono rilevate automaticamente, convertendo formati datati come Shift_JIS e UTF-16. Tutto il resto viene rifiutato con un messaggio chiaro. I percorsi completi viaggiano insieme ai contenuti, così il modello può distinguere i file e sa dove si trovano. Poiché gli allegati binari possono costare più del testo, il popup chiede prima di inviarli (i file di testo partono senza conferma) — la conferma si può disattivare lì stesso o nelle Impostazioni.

actions/*.md

Un file = un’azione: frontmatter YAML + un corpo del prompt in Liquid. Lo stesso singolo file è anche il formato di condivisione — Impostazioni → Azioni → Importa lo accetta come testo incollato o come file scelto.

---
id: summarize
label: Riassumi
role: default
instructions: Sei un assistente conciso.
---

Riassumi in 3 righe, in {{ locale }}:

{{ text }}

Frontmatter	Significato
id	Nome referenziato da routing.json (predefinito: nome del file) — il prefisso zencopy- è riservato alle azioni preinstallate
label	Mostrato nel popup
role	Role del catalog con cui eseguire (predefinito: default)
instructions	Prompt di sistema (template Liquid)

Variabili di template, con valori d’esempio per un paragrafo copiato in un browser:

Variabile	Esempio
{{ text }}	Il testo copiato (le copie HTML formattate diventano Markdown)
{{ markup }}	Il sorgente HTML/RTF di una copia formattata
{{ format }}	html (o rtf; vuoto per le copie semplici)
{{ file_name }}	report.pdf (il nome del primo file copiato)
{{ file_names }}	Il nome di ogni file copiato, uno per riga
{{ file_paths }}	Il percorso completo di ogni file copiato, uno per riga
{{ app_name }}	Safari
{{ exec_name }}	Safari / chrome.exe
{{ exec_path }}	/Applications/Safari.app/Contents/MacOS/Safari
{{ window_title }}	Pricing – Example
{{ url }}	https://example.com/pricing (solo browser)
{{ process_id }}	8123
{{ now }}	2026-07-08 20:15:00
{{ locale }}	it

C’è anche un filtro language_name specifico di ZenCopy: {{ locale | language_name }} si espande in “Italian” invece di “it”, che in un prompt suona naturale. Per vedere i valori reali, attiva la modalità sviluppatore nelle Impostazioni — le variabili di template di ogni cattura appaiono nel popup come JSON.

Le azioni semplici (un nome e un’istruzione) si possono creare anche dalla finestra delle impostazioni; ciò che scrive è esattamente questo formato di file.

Template avanzati

Sia il frontmatter instructions sia il corpo sono template LiquidJS completi: condizioni, cicli e filtri funzionano tutti. Una singola azione può adattarsi alla provenienza della copia:

---
id: context-aware
label: Sensibile al contesto
---

{% if url contains "github.com" %}
Rivedi questo codice e indica il singolo rischio più grande:
{% elsif app_name == "Slack" %}
Riassumi questa conversazione in 2 righe:
{% else %}
Spiega questo in {{ locale }}:
{% endif %}

{{ text | truncate: 8000 }}

Log

I log strutturati (segreti e contenuti copiati oscurati) vanno al terminale in sviluppo e a un file a rotazione in release:

Windows

%LOCALAPPDATA%\app.zencopy\logs

macOS

~/Library/Logs/app.zencopy/

Linux

~/.local/share/app.zencopy/logs