Documentazione
Come si usa Hawklify, passo per passo
Hawklify permette alla tua app AI di lavorare nel tuo Odoo, dalla 16 alla 19, come te e con i tuoi permessi Odoo. Questa guida spiega come configurarlo, come si approvano le modifiche e come un amministratore decide cosa può fare l’assistente per ogni collega. Screenshot e video vengono dall’app vera, riempita con un’azienda di esempio.
1. Per iniziare
Tre passi, una decina di minuti.
- Un Odoo dalla 16 alla 19, Community o Enterprise, raggiungibile in HTTPS
- Il tuo utente Odoo, per creare una chiave API
- Un’app AI che sappia aggiungere un connettore MCP
1Crea l’account
Inizia la prova gratuita con la tua email, Google o GitHub. La prova dura 14 giorni e non serve la carta. Chi crea l’account diventa amministratore dell’organizzazione e potrà invitare i colleghi.
2Collega il tuo Odoo
Apri la pagina Odoo e incolla il tuo login Odoo e una chiave API del tuo utente Odoo. Da lì l’assistente lavora come te: vede e modifica solo quello che puoi vedere e modificare tu in Odoo.
Per creare la chiave in Odoo 19: fai clic sul tuo avatar in alto a destra, apri Le mie preferenze, vai nella scheda Sicurezza e premi Aggiungi chiave API. Odoo chiede la tua password, poi un nome per la chiave (per esempio Hawklify) e quanto deve durare. Copia la chiave: Odoo la mostra una volta sola. Hawklify la verifica sul tuo Odoo, la salva cifrata e non la mostra più.
- In Odoo 16, 17 e 18 i nomi sono Preferenze, la scheda Sicurezza account e il pulsante Nuova chiave API.
- Odoo 18 e 19 chiedono quanto deve durare la chiave: decidi tu. Quando scade, l’assistente ti chiede di salvarne una nuova nella pagina Odoo.
- In Odoo 16 e 17 la chiave non scade.
- Usa una chiave API normale, creata come sopra. Se il tuo Odoo offre anche le chiavi MCP del suo modulo AI, quelle valgono solo per il server MCP di Odoo: Hawklify non può usarle.
Creare la chiave in Odoo 19
3Aggiungi Hawklify alla tua app AI
Hawklify è un connettore MCP standard, quindi funziona con qualsiasi app AI che sappia aggiungerne uno, come Claude, ChatGPT, Cursor o VS Code. Cerca il punto in cui l’app aggiunge un connettore personalizzato o un server remoto, incolla l’indirizzo qui sotto e accedi quando l’app lo chiede.
La pagina Panoramica mostra lo stesso indirizzo con il pulsante Copia, spunta i passi già fatti ed elenca le app collegate al tuo account.
https://mcp.hawklify.com/mcp
Esempio: Claude Desktop
- Apri Customize, poi Connectors.
- Premi + Add, poi Add custom connector.
- Scrivi Hawklify come nome, incolla l’indirizzo qui sopra e premi Continue. Lascia le impostazioni di accesso come le rileva Claude e premi Add.
- Accedi con il tuo account Hawklify e consenti l’accesso.
- In una chat premi + in basso a sinistra, apri Connectors e controlla che Hawklify sia attivo.
Con un piano Claude Team o Enterprise un owner aggiunge il connettore una volta sola, in Organization settings, Connectors, Add, Custom, Web. Poi ogni persona apre Customize, Connectors e preme Connect.
Ora chiedi qualcosa
Scrivi in chat come faresti con un collega che conosce Odoo. Parti da una domanda, poi prova una modifica e un’azione:
- Lettura“Quali preventivi sono ancora aperti e per che totale?”
- Modifica“Sposta la scadenza del preventivo S00003 al 30 novembre”
- Azione“Conferma il preventivo S00003 così diventa un ordine di vendita”
Leggere non richiede mai un’approvazione. La modifica cambia un campo, l’azione preme il pulsante Conferma di Odoo: cosa succede dipende da come lavori, spiegato nella prossima sezione.
2. Come si approva una modifica
Un amministratore sceglie, per ogni persona, uno di due modi di lavorare. Vale dalla prossima azione dell’assistente, senza ricollegare nulla.
Con card
Approvi ogni modifica
Ogni modifica, nuovo record, eliminazione, messaggio e pulsante aspetta il tuo clic prima di arrivare in Odoo. È l’unico modo che garantisce che decida una persona.
In chat
L’assistente può decidere per te
Nessuna card. L’assistente decide quando chiederti, in base al contesto, al rischio della modifica e alle tue regole. Più veloce, ma può anche procedere senza chiedere.
Con card: dove vedi la modifica
Dipende dall’app AI che usi, in quest’ordine:
- 1Una card nella chat
Nelle app che mostrano le card, come Claude, ChatGPT, Cursor e VS Code. Vedi i valori vecchi e nuovi e decidi con un pulsante.
- 2Una domanda sì o no
Nelle app senza card che sanno fare una domanda mentre lavorano, come Claude Code nel terminale. La modifica aspetta anche nella pagina Approvazioni, così puoi decidere lì se la domanda non compare.
- 3La pagina Approvazioni
Nelle app che non mostrano né l’una né l’altra, come Claude in Chrome. L’assistente ti dà il link e la modifica ti aspetta lì.
La card nella chat
La card dice in una frase cosa fa la modifica, poi mostra ogni campo con il valore attuale barrato e quello nuovo accanto. In Odoo non cambia nulla finché non premi “Approva ed esegui”. “Rifiuta” la scarta.
Una card aspetta fino a 4 ore. Fatto il passo, “Avvisa l’assistente” gli comunica il risultato così può proseguire. Se invece decidi nella pagina Approvazioni, la card ricontrolla quando torni in chat o ci passi sopra col mouse e mostra “Non più in attesa”: niente viene eseguito due volte.
La pagina Approvazioni
Con l’accesso a Hawklify, apri Approvazioni dal menu. Elenca ogni modifica che l’assistente ha chiesto di fare con il tuo account e che è ancora in attesa, comprese quelle mostrate in una card o in una domanda. Per ognuna vedi cosa cambia e il link al record in Odoo.
- Approva o rifiuta ogni modifica, oppure usa “Approva tutte”, che lascia sempre fuori le modifiche che eliminano record.
- Dopo una decisione la pagina ti dà un breve messaggio: copialo e incollalo in chat, così l’assistente sa cosa è successo.
- Conta la prima decisione, nella card, nella domanda o nella pagina, e la modifica viene fatta al massimo una volta. Dopo 4 ore una modifica viene scartata.
In chat: come appare
Non compare nessuna card. Chiedi, l’assistente fa la modifica in Odoo e ti dice cosa ha fatto. Quando lo ritiene utile, o se le tue regole lo prevedono, prima ti chiede in chat.
Quello che l’organizzazione non permette resta rifiutato anche in chat, come le modifiche alle impostazioni di Odoo stesso: l’assistente lo dice e non modifica nulla.
In chat: le tue regole
Per una persona che lavora in chat, l’amministratore può scrivere qualche regola a parole, come “chiedimi sempre prima di confermare un ordine”. L’assistente le riceve all’inizio di una chat e a ogni modifica che fa.
Le regole sono indicazioni, non un blocco: l’assistente le segue ma può sbagliare, o essere ingannato dal testo di un record. I limiti fissi sono gli stessi nei due modi di lavorare: il ruolo della persona, i suoi diritti Odoo, le impostazioni di Odoo rifiutate se non permesse, e il registro attività. Quando una persona deve approvare ogni modifica, scegli la card.
3. Gestire il team
Gli amministratori gestiscono tutti dalla pagina Membri: chi può accedere, cosa può fare l’assistente per ogni persona e come chiede conferma.
Invitare un collega
Premi “Invita una persona” e scrivi la sua email. Scegli il ruolo, il numero di chiamate (con Team), come lavora l’assistente per lei e la lingua dell’invito. Riceve un link valido 7 giorni, sceglie una password (o usa Google o GitHub) e poi salva la propria chiave API di Odoo.
Una persona invitata occupa subito un posto, finché non la disabiliti. “Amministratore dell’organizzazione” le permette di invitare persone e cambiare anche queste impostazioni.
I tre ruoli
- Sola lettura legge i dati e non modifica nulla.
- Completo modifica tutto quello che può modificare l’utente Odoo della persona, tranne le impostazioni di Odoo stesso se l’organizzazione non le permette. La scelta giusta per la maggior parte delle persone.
- Operatore un livello di sicurezza in più oltre ai permessi Odoo: modifica solo le aree di Odoo che elenchi per quella persona, e preme solo i pulsanti che elenchi. Senza nulla in elenco non modifica nulla.
Qualunque sia il ruolo, l’assistente non va mai oltre i diritti Odoo della persona: Odoo controlla ogni richiesta.
4. Impostare un Operatore
Operatore serve quando non basta rispettare i permessi che Odoo dà alla persona e vuoi un livello di sicurezza in più. L’assistente non può mai fare più di quello che la persona può fare in Odoo e, in più, modifica solo le parti di Odoo che elenchi, per esempio preventivi e contatti per un commerciale. La lettura non ha limiti in più: segue i permessi Odoo. Gli dai due elenchi: le aree e le azioni.
Aree e azioni
Le aree sono i modelli di Odoo in cui l’assistente può creare, modificare o eliminare record, scritti con il nome tecnico: sale.order per preventivi e ordini, res.partner per i contatti, crm.lead per le opportunità. Le azioni sono i pulsanti che può premere, scritti come modello.metodo, per esempio sale.order.action_confirm per Conferma. Senza azioni l’assistente può comunque creare e modificare record, ma non preme pulsanti.
Scrivi una voce per riga (va bene anche un elenco incollato con le virgole), fino a 100 per elenco. In Odoo il nome tecnico di un modello lo trovi con la modalità sviluppatore attiva, in Impostazioni, Tecnico, Modelli.
| Scrivi | Significa |
|---|---|
sale.order | un modello: preventivi e ordini di vendita |
sale.* | ogni modello il cui nome inizia con sale. |
* | tutte le aree (le impostazioni di Odoo restano soggette all’interruttore dell’organizzazione) |
*, !account.* | tutte le aree tranne la contabilità |
sale.order.action_confirm | un’azione: il pulsante Conferma di un preventivo |
sale.order.action_* | ogni azione di sale.order il cui nome inizia con action_ |
Vuoto vuol dire che non cambia nulla
Un Operatore senza aree in elenco non modifica nulla: niente record, niente messaggi, niente azioni. Lo stesso vale per un elenco con sole esclusioni, come !account.move: per dare tutto tranne un’area, scrivi *, !account.move.
Il pannello ti avvisa in giallo quando nessuna area è elencata, quando un elenco tocca le impostazioni di Odoo mentre l’organizzazione le rifiuta, e quando un’azione appartiene a un modello fuori dalle aree.
Le aree limitano solo quello che l’assistente modifica. Quello che legge segue i diritti di accesso Odoo della persona, come per ogni ruolo.
5. Impostazioni dell’organizzazione
La scheda “Collegamento a Odoo e avanzate” della pagina Membri raccoglie quello che vale per tutta l’organizzazione.
Collegamento a Odoo
Indirizzo di Odoo, nome del database e versione (Odoo dalla 16 alla 18, oppure Odoo 19 e successive). Cambiare indirizzo o database cancella tutte le chiavi API salvate nell’organizzazione, quindi ognuno si ricollega dalla pagina Odoo.
Modifiche ai modelli di sistema di Odoo
Un interruttore, spento di default, per le impostazioni di Odoo stesso: utenti, gruppi, automazioni e i record ir.*. Lascialo spento se non serve. Quando è acceso, un assistente ingannato dal testo di un record potrebbe creare azioni server o azioni pianificate, codice che poi gira nel tuo Odoo con i diritti di quella persona. Se lo accendi, tieni la card per chi lo usa.
Il tuo codice custom
Con i piani Max e Team, la scheda Codice sorgente collega GitHub: scegli i repository con i tuoi moduli custom e, prima di eseguire un metodo o modificare un record, l’assistente legge come si comportano davvero. Legge soltanto, su GitHub non scrive nulla.
6. Registro attività
La scheda Attività registra chi ha fatto cosa e quando: accessi, ogni modifica fatta dall’assistente, ogni approvazione o rifiuto (nella card o nella pagina), i rifiuti e ogni impostazione cambiata nella pagina Membri, con cosa è stato aggiunto e tolto. Si filtra per persona, tipo e data. Le voci restano per 90 giorni.
7. Sicurezza dell’account
Nella pagina Sicurezza cambi la password e attivi la verifica in due passaggi: a ogni accesso Hawklify chiede anche un codice da un’app sul telefono. La consigliamo agli amministratori.
Togliere il connettore dalla tua app AI non ne revoca l’accesso: usa Scollega nella pagina Panoramica. Un’app non usata per 30 giorni viene scollegata da sola.
8. Problemi comuni
Devo installare qualcosa in Odoo, o migrare?
Nessun modulo e nessuna migrazione. Hawklify usa l’API esterna standard di Odoo, dalla 16 alla 19, Community o Enterprise. Il tuo Odoo deve essere raggiungibile in HTTPS da internet.
La mia app dice che non raggiunge il server, o che l’accesso è fallito
Controlla che l’indirizzo sia esattamente https://mcp.hawklify.com/mcp e riprova. Se nel frattempo hai cambiato account o password, rimuovi il connettore dalla tua app e aggiungilo di nuovo.
L’assistente mi chiede di collegare il mio Odoo
La tua chiave API di Odoo non è ancora salvata, oppure è stata cancellata perché un amministratore ha cambiato indirizzo o database di Odoo. Apri la pagina Odoo e salva una chiave.
Odoo ha rifiutato la mia chiave API
La chiave è stata revocata, è scaduta o è stata copiata male. Creane una nuova in Odoo (Il mio profilo, Sicurezza account, Nuova chiave API) e salvala di nuovo nella pagina Odoo.
Hawklify non raggiunge il mio Odoo
Controlla indirizzo, nome del database e versione nella pagina Membri, scheda Collegamento a Odoo. Odoo dalla 16 alla 18 usa l’API XML-RPC, Odoo 19 l’API JSON-2. Un firewall o una VPN davanti a Odoo devono lasciar passare la connessione.
Una modifica è stata rifiutata
Vengono controllate due cose: i tuoi diritti di accesso in Odoo e il ruolo che ti ha dato l’amministratore. Chiedi all’assistente “cosa puoi modificare per me?” e ti spiega il ruolo e perché la modifica è stata rifiutata. Gli amministratori cambiano i ruoli nella pagina Membri, e ogni rifiuto è nel registro attività.
Sono Operatore e non cambia nulla
L’amministratore non ha ancora elencato nessuna area per te, quindi l’assistente si limita a leggere. Chiedigli di aggiungere le aree in cui lavori nella pagina Membri.
La card di approvazione non compare
Non tutte le app sanno mostrarla. Apri Approvazioni dal menu: ogni modifica che ti aspetta è lì, anche quando l’app non ha mostrato nulla. Se non vuoi mai le card, un amministratore può impostarti su “In chat”.
La card o la pagina dice che una modifica è “Non più in attesa”
È già stata approvata o rifiutata altrove (nella card, nella pagina Approvazioni, in un’altra scheda) oppure sono passate le 4 ore. Niente viene eseguito due volte. Chiedi all’assistente di controllare in Odoo prima di riproporre la modifica.
Ho raggiunto il limite giornaliero
Ogni persona ha un numero di chiamate in ogni 24 ore: 50 in prova, 500 con Pro, 5.000 o 10.000 con Max, e con Team il livello scelto per ogni persona. Una chiamata è una singola richiesta dell’assistente a Hawklify, come una ricerca o una modifica. Il conteggio riguarda le ultime 24 ore, quindi le chiamate si liberano col passare del tempo. Un amministratore può scegliere più chiamate nella pagina Piano.