Install the OpenClaw Nylas Plugin

What is the OpenClaw Nylas Plugin?

The @nylas/openclaw-nylas-plugin package is an npm-based plugin for OpenClaw that registers 16 typed tool schemas for email, calendar, and contacts directly with the agent runtime. Instead of constructing shell commands through OpenClaw's exec tool, the plugin gives agents structured JSON parameters and responses — cutting tool-call error rates compared to free-form command construction.

The agent calls tools like nylas_list_emails and nylas_send_email with validated parameters and gets JSON responses back — no command construction, no output parsing, and no exec-approvals.json. The CLI exec guide covers the alternative shell-based approach.

Key advantages over the exec approach:

• Typed tool schemas — the agent sees parameter names, types, and descriptions, reducing errors
• Auto-discovery — the plugin finds all grants associated with your API key automatically
• Multi-account — work with multiple email accounts using named grants
• No shell security config — no exec-approvals.json, no PATH setup, no allowlists
• Works with OpenClaw, Moltbot, and Clawdbot

Prerequisites

Setting up the OpenClaw Nylas plugin requires four components: an OpenClaw installation, a Nylas dashboard account, an API key, and at least one connected email grant. The Nylas v3 API supports 6 provider types — Gmail, Outlook, Exchange, Yahoo, iCloud, and generic IMAP — and each connected account becomes a grant the plugin can discover.

• OpenClaw installed and running. The OpenClaw setup guide covers installation.
• Nylas dashboard account — sign up at dashboard-v3.nylas.com if you don't have one.
• Nylas API key — create one in the dashboard under Settings → API Keys.
• At least one grant — connect an email account (Gmail, Outlook, Exchange, Yahoo, iCloud, or IMAP) in the dashboard under Grants.

1. Install the plugin

OpenClaw's built-in plugin manager downloads @nylas/openclaw-nylas-plugin from npm and registers it with the gateway in a single command. The install takes under 30 seconds on a typical connection. After installation, a gateway restart loads the plugin and makes its 16 tools available to agent sessions.

The plugins install command pulls the package, validates its manifest, and writes a plugin entry into OpenClaw's local configuration directory. Run the install command to get started:

openclaw plugins install @nylas/openclaw-nylas-plugin

After the install completes, restart the gateway and verify the plugin appears in the plugin list. The plugins list command shows all installed plugins with their version numbers and status:

openclaw plugins list
openclaw gateway restart

The output should include @nylas/openclaw-nylas-plugin with a status of "loaded."

Newer OpenClaw versions (0.8+) sandbox plugins by default, requiring explicit trust before a plugin's tools appear in agent sessions. The two config commands below add the Nylas plugin to both the plugin allowlist and the tool allowlist:

# Trust the plugin and expose its tools to agent sessions
openclaw config set 'plugins.allow' '["nylas"]'
openclaw config set 'tools.alsoAllow' '["nylas"]'

On older OpenClaw releases (before 0.8), all installed plugins are allowed by default. The config keys are no-ops if the runtime does not enforce sandboxing.

2. Configure your API key

The OpenClaw Nylas plugin authenticates against the Nylas v3 API using an API key, which you can generate in the Nylas dashboard under Settings → API Keys. The API key grants access to all grants (connected accounts) under your Nylas application, so the plugin can auto-discover every linked mailbox, calendar, and contact book from a single credential.

Store the API key in OpenClaw's config using the config set command. OpenClaw encrypts plugin config values at rest, so the key is not stored in plaintext on disk. Restart the gateway after setting the key:

openclaw config set 'plugins.entries.nylas.config.apiKey' 'YOUR_NYLAS_API_KEY'
openclaw gateway restart

Alternatively, set the NYLAS_API_KEY environment variable in your shell profile or OpenClaw's environment config. The plugin checks the environment variable as a fallback if no config value is set.

For multi-account setups, named grant aliases map human-readable labels to specific grant IDs. Each grant ID corresponds to one connected email account. Configure aliases explicitly instead of relying on auto-discovery:

openclaw config set 'plugins.entries.nylas.config.grants' '{"work":"grant-id-1","personal":"grant-id-2"}'
openclaw gateway restart

3. Verify it works

Verification confirms that the plugin loaded successfully, authenticated with the Nylas API, and discovered at least one grant. The plugins list command shows whether the plugin is loaded, and a quick openclaw run prompt tests end-to-end connectivity — from the agent through the plugin to the Nylas API and back. A successful run returns grant details in under 2 seconds on a typical connection.

The first command checks plugin status. The second command triggers the agent to call nylas_discover_grants, which queries the Nylas API for all grants associated with the configured API key and returns their IDs, email addresses, and providers:

# Check the plugin is loaded
openclaw plugins list

# Verify grant discovery through the plugin
openclaw run "List my connected email accounts" --plugin nylas

The plugin auto-discovers grants linked to the configured API key at gateway startup. If you add new grants in the Nylas dashboard after the initial setup, restart the gateway with openclaw gateway restart to trigger rediscovery.

4. What tools does the plugin provide?

The OpenClaw Nylas plugin registers 16 native tools across four domains: 6 email tools, 7 calendar tools, 2 contacts tools, and 1 grant discovery tool. Each tool has a typed JSON schema that defines its parameters, types, and descriptions, so the agent knows exactly which fields are required and what values are valid. The schemas are auto-registered at gateway startup with no manual configuration.

Email tools

Calendar tools

Contacts tools

Discovery tools

5. Example conversations

With the plugin installed, OpenClaw agents can handle multi-step email, calendar, and contact workflows in natural language. Each prompt below shows the tool calls the agent makes — typically 1-3 calls per request. The plugin's typed schemas mean the agent doesn't need to guess flag names or parse text output; it receives structured JSON for every response.

Email examples

• "What are my unread emails?" — the agent calls nylas_list_emails with { unread: true, limit: 20 }, then summarizes senders, subjects, and snippets.
• "Find emails from Sarah about the Q4 budget" — the agent calls nylas_list_emails with { query: "from:sarah Q4 budget" }, reads the matching threads, and pulls out the key points.
• "Draft a reply to the latest email from Dave saying I'll review it by Friday" — the agent calls nylas_list_emails to find Dave's email, then nylas_create_draft with the reply content. It shows you the draft before sending.
• "Send Alice the meeting notes from yesterday" — the agent calls nylas_list_contacts with a search query to resolve Alice's email address, composes the message, confirms with you, then calls nylas_send_email.

Calendar examples

• "What's on my calendar this week?" — the agent calls nylas_list_events with start and end timestamps for the current week, then summarizes each day's schedule.
• "Schedule a 30-minute meeting with bob@company.com on Tuesday at 2pm" — the agent calls nylas_create_event with the title, participants, start time, and duration. It confirms the event details before creating it.
• "Am I free Thursday afternoon?" — the agent calls nylas_check_availability for Thursday 12:00–18:00 and tells you which slots are open.
• "Move my 3pm meeting to 4pm" — the agent calls nylas_list_events to find the 3pm event, then nylas_update_event to shift the start and end times by one hour.

Contacts examples

• "What's Sarah Chen's email address?" — the agent calls nylas_list_contacts with { query: "Sarah Chen" } and returns the matching contact details.
• "Look up everyone from Acme Corp in my contacts" — the agent calls nylas_list_contacts with { query: "Acme Corp" } and lists all matching names and email addresses.

Combined workflow examples

• "Find a time to meet with alice@company.com this week and send her an invite" — the agent calls nylas_check_availability to check both calendars, picks the first open slot, calls nylas_create_event with Alice as a participant, and confirms the invite was sent.
• "Check if I have any emails from the attendees of tomorrow's standup" — the agent calls nylas_list_events to find tomorrow's standup and its participants, then calls nylas_list_emails with targeted queries for each attendee to surface recent threads.
• "Email everyone in my 2pm meeting that I'll be 10 minutes late" — the agent calls nylas_list_events to find the 2pm event, extracts the participant emails, composes a short message, confirms with you, then calls nylas_send_email for the outgoing message.

6. How do I use multiple email accounts?

The OpenClaw Nylas plugin supports named grant aliases, letting one agent manage multiple email accounts — for example, a work Gmail and a personal Outlook account — from a single API key. The Nylas v3 API allows up to 50 grants per application, and each grant maps to one connected provider account. Named aliases give agents a human-readable label (like "work" or "personal") instead of raw grant UUIDs.

Configure aliases with the config set command. Each key is the alias name and each value is the grant ID from the Nylas dashboard. The plugin resolves the alias to the correct grant ID at call time:

openclaw config set 'plugins.entries.nylas.config.grants' '{"work":"grant-id-1","personal":"grant-id-2"}'
openclaw gateway restart

With aliases configured, the plugin targets a specific account by name instead of a raw grant ID. Without aliases, the plugin auto-discovers all grants from the Nylas application at gateway startup and presents them by email address.

The agent selects which account to use based on the prompt. For example, "list my work emails" routes to the "work" grant, while "send from my personal account" routes to the "personal" grant.

7. Optional: Standalone usage

The @nylas/openclaw-nylas-plugin package also works as a standalone npm library outside of OpenClaw, giving TypeScript and JavaScript projects the same typed Nylas client without depending on the OpenClaw runtime. The package exports a createNylasClient function that handles API authentication and grant discovery in a single async call.

Install the package with npm. The package is approximately 45 KB unpacked and has zero runtime dependencies beyond the Node.js standard library:

npm install @nylas/openclaw-nylas-plugin

The createNylasClient function accepts an API key, queries the Nylas v3 API for all associated grants, and returns a typed client instance. The discovered array contains each grant's ID, email address, and provider type:

import { createNylasClient } from "@nylas/openclaw-nylas-plugin"

const { client, discovered } = await createNylasClient({
  apiKey: process.env.NYLAS_API_KEY!,
})

console.log(`Discovered ${discovered.length} grants`)

const emails = await client.listMessages({ limit: 5 })
console.log(emails)

The standalone approach is useful when building a custom agent with the agent tools pattern and you want typed Nylas tools without the OpenClaw gateway or the CLI.

8. Which approach should I choose: plugin, CLI exec, or MCP?

OpenClaw agents can access Nylas through three methods: the native plugin (1 install command), CLI exec (requires PATH setup and an exec-approvals.json allowlist), or an MCP server (requires a separate running process on port 3100). The plugin approach has the fewest moving parts and is the only method that supports multi-account grant aliases. The table below compares all 7 decision factors.

Recommendation: Use the plugin for the simplest setup and best multi-account support. Use the CLI exec approach if you already have the Nylas CLI authenticated and prefer OAuth-based auth. Use MCP if you need the same tools available to other MCP-compatible clients (Claude Desktop, Cursor, VS Code).

Troubleshooting

The 5 most common OpenClaw Nylas plugin errors fall into two categories: authentication failures (API key missing, invalid, or expired) and discovery failures (no grants found, stale grant IDs, or plugin not loaded). Each error below includes the exact error message, the root cause, and the fix. Most issues resolve with a config update and a gateway restart.

"apiKey is required"

The plugin cannot find a Nylas API key in either the OpenClaw config or the NYLAS_API_KEY environment variable. The plugin checks the config value first and falls back to the environment variable. Verify the stored value is not empty — an empty string triggers the same error as a missing key:

openclaw config get 'plugins.entries.nylas.config.apiKey'

"No grants found"

The API key authenticated successfully, but the associated Nylas application has zero connected email accounts. At least 1 grant is required for the plugin to function. Go to dashboard-v3.nylas.com → Grants and connect an email account. Then restart the gateway so the plugin re-runs grant discovery:

openclaw gateway restart
openclaw run "List my connected email accounts" --plugin nylas

401 Unauthorized

A 401 response from the Nylas API means the API key is invalid, revoked, or expired. Nylas API keys do not expire automatically, but they can be revoked in the dashboard. Generate a new key in the Nylas dashboard under Settings → API Keys and replace the old value:

openclaw config set 'plugins.entries.nylas.config.apiKey' 'NEW_API_KEY'
openclaw gateway restart

404 Not Found on grant operations

A 404 on a grant operation means the grant ID in the plugin config no longer exists in the Nylas application. Grants become invalid when an email account is disconnected or deleted in the Nylas dashboard. Update plugins.entries.nylas.config.grants to point at valid grant IDs from the Nylas dashboard, then restart the gateway.

Plugin not showing up

If openclaw plugins list does not show the Nylas plugin, the npm install may have failed silently or the plugin manifest is corrupted. A clean reinstall followed by trust configuration resolves the issue in most cases:

openclaw plugins uninstall @nylas/openclaw-nylas-plugin
openclaw plugins install @nylas/openclaw-nylas-plugin
openclaw config set 'plugins.allow' '["nylas"]'
openclaw config set 'tools.alsoAllow' '["nylas"]'
openclaw gateway restart

If the plugin is listed but its tools never appear in agent sessions, the plugin is installed but not trusted by the OpenClaw sandbox. The two openclaw config set commands above add the plugin to both the plugin allowlist and the tool allowlist, which is required on OpenClaw 0.8 and later.

Next steps

• Nylas CLI with OpenClaw (exec approach) — the alternative setup using shell commands and exec-approvals
• Give AI Agents Email Access via MCP — connect Claude, Cursor, or VS Code to your inbox
• Build an Agent with Email Tools — use Nylas tools in a custom LLM agent
• Send email from the terminal — use the Nylas CLI directly for scripting
• Manage calendar from the terminal — timezone handling, DST, and AI scheduling
• Organize Emails by Company — auto-label and sort messages by sender domain for multi-account workflows
• Export Email to HubSpot — sync email conversations to HubSpot contacts and deals
• Secure Email Handling with the CLI — token storage, grant scoping, and safe automation patterns
• List iCloud Emails — read and filter iCloud Mail from the command line
• List IMAP Emails — connect to any IMAP provider and list messages with the Nylas CLI
• OpenClaw CLI Setup Guide — install OpenClaw via npm, add plugins, and configure WhatsApp
• Fix OpenClaw CLI Errors — troubleshoot PATH, npm permissions, Node.js version, and Windows issues
• Command reference — every flag, subcommand, and example