Integrations

What are integrations?

Integrations connect Pinchy to external systems — ERPs, email accounts, CRMs, search engines — so agents can work with real business data and access live information. Instead of giving agents direct access, Pinchy provides a controlled bridge: the admin sets up a connection once, then decides which agents can use it and what they’re allowed to do.

Supported integrations

Integration	Connection method	Guide
Google (Gmail)	OAuth 2.0	Connect Email
Odoo	API key	Connect Odoo
Web Search (Brave)	API key	Set Up Web Search

Note

Integrations vs. Channels. This page is about data integrations — how agents access external business systems. If you’re looking for communication channels (how users reach their agents from outside the Pinchy web UI), see Set Up Telegram. LLM providers like OpenAI, Anthropic, Google, and Ollama (local and cloud) are configured separately via Manage LLM Providers.

Connections vs. permissions

These are two separate concepts:

• Connection — a global setting an admin creates once. It stores the credentials and knows how to talk to the external system. Think of it as “Pinchy can talk to this system.”
• Permissions — per-agent settings that control what each agent can do with that connection. Think of it as “this agent can read emails but not send them” or “this agent can search the web but not fetch arbitrary pages.”

Creating a connection doesn’t give any agent access. You must explicitly grant access in each agent’s Permissions tab.

Gmail (Google)

Gmail is the first email integration. An admin connects a Google account via OAuth 2.0, then grants specific permissions per agent.

Setup flow

Gmail requires a Google Cloud OAuth app (one-time, per Pinchy installation). Once created, admins connect one or more Google accounts through the Add Integration wizard. Google requires HTTPS — the wizard shows a warning and blocks the OAuth flow when Pinchy is running without HTTPS.

Permissions model

Each agent gets email permissions independently. Permissions are additive: granting Send automatically includes Read and Draft.

Permission	Tools enabled
Read messages	email_list, email_read, email_search
Create drafts	above + email_draft
Send messages	above + email_send

Token handling

OAuth access tokens expire after about one hour. Pinchy refreshes them in the background using the stored refresh token. If a refresh fails (the user revoked access, or the refresh token expired in Google’s Testing mode), the integration surfaces the error and prompts the admin to reconnect.

Security

• Client ID and Client Secret are encrypted with AES-256-GCM before storage
• Access and refresh tokens are encrypted per-connection
• Tokens are decrypted on-demand when the agent makes an API call — they never end up in the OpenClaw config file
• The pinchy-email plugin fetches tokens via Pinchy’s internal API, authenticated by the shared gateway token

For the full setup walkthrough, see Connect Email.

Web Search (Brave)

Web Search is the simplest integration — a single API key connects Pinchy to the Brave Search API, giving agents the ability to search the web and fetch pages.

Unlike Odoo, Web Search has no multi-step sync or schema discovery. You enter your API key, Pinchy validates it, and the connection is ready. From there, you enable web search tools per agent in the Permissions tab.

Web search tools

Tool	What it does
Search the web	Queries Brave Search and returns ranked results
Fetch web pages	Downloads and extracts readable content from a URL

Per-agent filters

Each agent can have its own web search configuration:

• Domain restrictions — one list where each domain is marked Include (agent may only access these) or Exclude (agent is blocked from these); modes can be combined
• Freshness — limit results to a time window (last day, week, month, or year)
• Language / Region — bias results toward a language or geographic region (full ISO lists, searchable)

These filters are stored per agent, so you can have a support agent restricted to your docs site while a research agent has unrestricted access.

Security

When an agent has both web fetch access and access to sensitive data (files or Odoo records), Pinchy shows a contextual security warning about data exfiltration risk. The web fetch module also includes built-in SSRF protection — agents cannot fetch internal network addresses or localhost.

For the full setup walkthrough, see Set Up Web Search.

Odoo

How the sync works

When you add a connection, Pinchy probes the external system to discover what’s available:

1. Schema discovery — Pinchy calls fields_get() on each model to learn the field names, types, and relationships
2. Permission check — Pinchy calls check_access_rights() to determine which operations (read, create, write, delete) the API user can perform
3. Filtering — Only models where the API user has at least read access appear in the connection summary

This means the connection reflects what’s actually accessible — not what exists in theory. If the Odoo admin later restricts the API user’s permissions, some models may disappear on the next sync.

Access levels

When granting an agent access to an Odoo connection, you choose an access level:

Level	Tools enabled	Use case
Read-only	list-models, describe-model, read, count, aggregate	Reporting, dashboards, Q&A
Read & Write	read-only set + create, write, attach-file	Data entry, updating records
Full	read & write set + delete	Full CRUD — use with caution
Custom	You pick individual tools	Fine-grained control

Each level maps directly to the Odoo tools that get enabled for the agent. See Agent Permissions for the full tool list, including the per-tool IDs and the cross-company write protection that applies to all Odoo agents regardless of level.

What happens when Odoo permissions change

If the Odoo admin changes the API user’s permissions after you’ve set up the connection, agents may lose access to certain models. When this happens:

• The agent gets a clear error message explaining that access was denied
• The error suggests that an admin re-syncs the connection

To re-sync: go to Settings → Integrations, select the connection, and click Re-sync. Pinchy probes the available models again and updates the connection accordingly.

Re-syncing may remove models that are no longer accessible. Agents that were configured to use those models will lose access to them.

Security

All integration credentials are handled with the same rigor as provider API keys:

• Encryption — credentials are encrypted with AES-256-GCM before being stored in the database. They never appear in logs, config files, or API responses.
• Audit trail — connection creation and permission changes are logged. All audit rows are HMAC-SHA256 signed.
• Least privilege — each integration enforces its own permission model. Agents start with zero access and must be granted specific operations explicitly.
• Token isolation — OAuth tokens and API keys stay in Pinchy’s encrypted database. They are never written to the OpenClaw config file — plugins fetch them on-demand via an internal API.

See Agent Permissions for the full allow-list model and how integration tools fit in.