Guide

Connect OpenClaw to Nylas for Email and Calendar

Use OpenClaw's exec tool to run Nylas CLI so your assistant can read inboxes, send email, check calendars, and search contacts. This guide covers TOOLS.md setup, exec-approvals.json, PATH visibility, and safety prompts for the CLI approach.

Written by Qasim Muhammad Staff SRE

Reviewed by Nick Barraclough

Verified — CLI 3.1.1 · Gmail, Outlook · last tested April 11, 2026

What is OpenClaw?

OpenClaw is an open-source, MIT-licensed personal AI assistant created by Peter Steinberger. It runs a gateway on your machine that bridges 6 messaging platforms — WhatsApp, Telegram, Discord, Slack, Signal, and iMessage — to an AI model of your choice (Claude, GPT-4, or others). You message OpenClaw from any of these apps and it responds with the full capabilities of the underlying model plus any tools you configure.

The key difference from cloud-hosted assistants: OpenClaw runs on your hardware. Your conversation history, workspace files, and memory stay on your machine. Only the AI model calls leave your network, going to the provider you choose (Anthropic, OpenAI, Google, etc.). According to the OpenClaw documentation, no user data is stored on external servers.

OpenClaw organizes its knowledge through 4 workspace files — AGENTS.md, TOOLS.md, SOUL.md, and MEMORY.md — and a skill system with community-contributed extensions on ClawHub. It also has an exec tool that lets the agent run shell commands on your machine, which is how it interacts with the Nylas CLI.

Why add Nylas CLI?

Adding the Nylas CLI gives OpenClaw native email and calendar access that the assistant otherwise lacks. OpenClaw can manage tasks, search the web, read and write files, and control a browser, but it ships with no inbox or calendar integration. The CLI fills that gap with 72+ commands across email, calendar, and contacts, covering all 6 major providers — Gmail, Outlook, Exchange, Yahoo, iCloud, and IMAP — through a single authentication flow.

Once installed and authenticated, OpenClaw's exec tool can run commands like nylas email list, nylas email send, and nylas calendar events list. That means you can message your assistant on WhatsApp and say "summarize my unread emails" or "schedule a meeting with Alice next Tuesday at 2pm," and it handles the rest without you opening a browser or email client.

1. Prerequisites

Connecting OpenClaw to the Nylas CLI requires three things: a running OpenClaw gateway, an authenticated CLI installation, and PATH visibility so the gateway process can find the nylas binary. The full setup takes under 10 minutes if both tools are already installed, or roughly 15-20 minutes from scratch.

OpenClaw installed and running

If you already have OpenClaw set up, skip to the Nylas CLI section. If not, install it with npm. OpenClaw requires Node.js 22.12.0 or later.

npm install -g openclaw@latest

# Run the onboarding wizard (configures gateway, channels, workspace, daemon)
openclaw onboard --install-daemon

The onboarding wizard walks you through pairing a messaging channel (WhatsApp, Telegram, etc.), choosing an AI model, and setting up the background daemon. For WhatsApp, the recommended setup uses a dedicated second phone number so that messages to your personal number are not routed to the agent. See the personal assistant setup guide for details.

Once onboarding finishes, start the gateway. The default port is 18789, which the daemon and messaging bridges connect to automatically.

openclaw gateway --port 18789

Nylas CLI installed and authenticated

Install the Nylas CLI via Homebrew and authenticate with your email provider. The OAuth flow completes in under 60 seconds and grants access to email, calendar, and contacts through a single token. After authenticating, verify the CLI can reach your mailbox by listing 3 recent messages.

# macOS / Linux
brew install nylas/nylas-cli/nylas

# Authenticate (opens a browser for OAuth)
nylas auth login

# Verify the CLI can reach your mailbox
nylas auth whoami
nylas email list --limit 3

Verify PATH visibility

OpenClaw's exec tool runs commands using the gateway's shell environment. If you installed the Nylas CLI via Homebrew, the binary is typically at /opt/homebrew/bin/nylas (Apple Silicon) or /usr/local/bin/nylas (Intel). The gateway includes these in its PATH by default.

If you run OpenClaw as a launchd or systemd daemon, the daemon inherits the environment from when it was installed. You can confirm the binary is reachable by running this from the gateway terminal:

which nylas

If the binary is in a non-standard location, add it to tools.exec.pathPrepend in your OpenClaw config:

// ~/.openclaw/openclaw.json
{
  "tools": {
    "exec": {
      "pathPrepend": ["/path/to/directory/containing/nylas"]
    }
  }
}

2. Tell the agent about Nylas

OpenClaw's agent reads workspace files at the start of each session to learn what tools are available and how to use them. The file that controls tool guidance is TOOLS.md, located at ~/.openclaw/workspace/TOOLS.md by default. Adding a Nylas section to this file takes about 2 minutes and gives the agent instructions for 10+ email, calendar, and contacts commands.

Open TOOLS.md and add the following section. The instructions cover the most common commands the agent will need, including the --yes flag that prevents interactive prompts from hanging the exec tool.

## Nylas CLI (email and calendar)

The `nylas` CLI is installed and authenticated. Use it via exec to manage email and calendar.

### Email
- `nylas email list --limit N [--unread] [--json]` - list recent messages
- `nylas email search "search terms" --limit N --json` - search by keyword
- `nylas email send --to ADDRESS --subject "..." --body "..." --yes` - send a message (--yes skips the confirmation prompt)
- `nylas email smart-compose --prompt "draft a reply saying..."` - AI-powered draft

### Calendar
- `nylas calendar events list [--days N] [--json]` - upcoming events
- `nylas calendar schedule ai "meeting with X next Tuesday at 2pm"` - natural language scheduling
- `nylas calendar events create --title "..." --start "2026-02-18 14:00" --end "2026-02-18 14:30"` - explicit event creation
- `nylas calendar availability check` - check free/busy
- `nylas calendar find-time --participants email@... --duration 30m` - find a mutual opening

### Contacts
- `nylas contacts list --limit N --json` - list contacts
- `nylas contacts search "name or email" --json` - search contacts

### Important
- Always pass `--yes` when sending email to avoid interactive prompts that hang the exec tool.
- Use `--json` when you need to parse the output or extract specific fields.
- Do not send email without the user confirming the recipient and content first.

The agent reads TOOLS.md at session start and uses it as guidance for when and how to invoke tools. The last line about confirmation is important: it tells the agent to check with you before sending, which you can adjust to match your comfort level.

3. Configure exec security

OpenClaw's exec tool enforces 3 security modes — deny (blocks all commands), allowlist (permits only approved binaries), and full (permits everything). The default is deny in sandboxed mode and allowlist on the gateway host. This means the agent needs approval before running any command it has not been explicitly allowed to use, and you can configure exactly how that approval works.

Option A: Use the allowlist (recommended)

When exec security is set to allowlist and ask: "on-miss" (the default for gateway host), OpenClaw will prompt you for approval the first time the agent tries to run nylas. After you approve, the binary path is saved to ~/.openclaw/exec-approvals.json and future calls are automatic.

This is the safest approach. You approve the nylas binary once, and the agent can use it freely without approving every individual invocation.

Pre-approve Nylas in exec-approvals.json

Instead of waiting for the first prompt, you can pre-approve the nylas binary by editing ~/.openclaw/exec-approvals.json directly. This file controls which binaries the agent can run without asking. According to the OpenClaw exec documentation, each pattern must be a full binary path — basename-only entries like "nylas" are silently ignored. The following example allowlists the Nylas CLI alongside common utilities:

{
  "version": 1,
  "defaults": {
    "security": "deny",
    "ask": "on-miss"
  },
  "agents": {
    "main": {
      "security": "allowlist",
      "ask": "on-miss",
      "autoAllowSkills": true,
      "allowlist": [
        {
          "pattern": "/opt/homebrew/bin/nylas"
        },
        {
          "pattern": "/opt/homebrew/bin/rg"
        },
        {
          "pattern": "/opt/homebrew/bin/jq"
        }
      ]
    }
  }
}

Key fields explained:

  • version — always 1 (required).
  • defaults.security — the global fallback. "deny" blocks everything not explicitly allowed. Other values: "allowlist", "full" (allows all — use with caution).
  • defaults.ask — "on-miss" prompts you when a binary is not in the allowlist. "always" prompts for every command. "off" never prompts.
  • agents.main.allowlist — array of allowed binary patterns. Each pattern is a case-insensitive glob that must resolve to a full binary path (basename-only entries like "nylas" are ignored).
  • autoAllowSkills — when true, binaries referenced in the requires.bins field of installed skills are automatically treated as allowlisted.

On Intel Macs, the Homebrew path is /usr/local/bin/nylas instead. On Linux, check which nylas for the correct path. After editing the file, the changes take effect on the next exec call — no restart needed.

If you created the Nylas skill with requires.bins: ["nylas"] and set autoAllowSkills: true, the binary is auto-approved and you do not need a manual allowlist entry at all.

Option B: Pre-approve via pathPrepend

If you want the agent to use nylas without any initial prompt, add the directory to pathPrepend and set security: "allowlist". This approach is broader than the allowlist — it permits any binary in the prepended directories, not just nylas. Use this when you trust all binaries in the directory (for example, /opt/homebrew/bin contains only Homebrew-managed packages).

// ~/.openclaw/openclaw.json
{
  "tools": {
    "exec": {
      "pathPrepend": ["/opt/homebrew/bin"],
      "security": "allowlist",
      "ask": "on-miss"
    }
  }
}

Option C: Use per-session override

If you want to enable exec only for specific sessions, send /exec host=gateway security=allowlist ask=on-miss in the chat. This sets exec defaults for the current session without changing the global config.

4. Optional: Create a Nylas skill

OpenClaw skills are a more structured alternative to editing TOOLS.md for tool instructions. Each skill is a self-contained folder with a SKILL.md file that includes YAML frontmatter and usage instructions. Skills can declare binary dependencies via requires.bins, which auto-approves those binaries when autoAllowSkills is enabled — eliminating the need for a manual allowlist entry. Skills load from 2 locations: ~/.openclaw/workspace/skills/ (workspace-level, highest priority) or ~/.openclaw/skills/ (managed).

The following script creates a Nylas skill folder and writes the SKILL.md file. The requires.bins field tells OpenClaw the skill needs the nylas binary, and the instructions mirror the TOOLS.md content from the earlier section.

mkdir -p ~/.openclaw/workspace/skills/nylas-cli

cat > ~/.openclaw/workspace/skills/nylas-cli/SKILL.md << 'EOF'
---
name: nylas-cli
description: Read, send, and schedule email and calendar events via the Nylas CLI
metadata: {"openclaw":{"requires":{"bins":["nylas"]}}}
---

# Nylas CLI

The `nylas` CLI is installed and authenticated. Use exec to run commands.

## Email
- `nylas email list --limit N [--unread] --json` - list messages
- `nylas email search "search terms" --limit N --json` - search
- `nylas email send --to ADDRESS --subject "..." --body "..." --yes` - send (--yes required to avoid hanging)
- `nylas email smart-compose --prompt "..."` - AI draft

## Calendar
- `nylas calendar events list [--days N] --json` - upcoming events
- `nylas calendar schedule ai "meeting with X next Tuesday at 2pm"` - natural language
- `nylas calendar events create --title "..." --start "..." --end "..."` - explicit
- `nylas calendar availability check` - free/busy
- `nylas calendar find-time --participants email@... --duration 30m` - mutual availability

## Contacts
- `nylas contacts list --limit N --json` - list contacts
- `nylas contacts search "name or email" --json` - search

## Rules
- Always use --yes for sends to prevent interactive prompts.
- Always confirm recipient and content with the user before sending.
- Use --json when parsing output.
EOF

If skill file watching is enabled (the default), the skill is picked up automatically on the next agent turn — no gateway restart needed. Otherwise, restart the gateway or start a new session to load the skill.

5. MCP alternative

OpenClaw supports MCP (Model Context Protocol) servers as an alternative to exec-based shell commands. MCP provides native tool schemas with typed parameters and structured JSON responses, which eliminates the need for the agent to construct CLI command strings and parse text output. Adding the Nylas MCP server to OpenClaw takes a single config entry and exposes 30+ typed tools to the agent.

To configure MCP, add the Nylas server to the mcp.servers section of ~/.openclaw/openclaw.json. The server starts automatically when the gateway launches and stops when it shuts down.

// ~/.openclaw/openclaw.json
{
  "mcp": {
    "servers": {
      "nylas": {
        "command": "nylas",
        "args": ["mcp", "serve"]
      }
    }
  }
}

With MCP, the agent gets typed tools like list_messages, send_message, and create_event with proper parameter schemas and structured JSON responses. This avoids the need for the agent to construct CLI commands and parse text output.

The trade-off: MCP requires the nylas mcp serve process to be running, and the exact config key may vary across OpenClaw versions. The exec + TOOLS.md approach works on every version and needs no extra configuration beyond PATH access.

6. Example conversations

Once OpenClaw is configured with the Nylas CLI, you can manage email and calendar through natural language messages from any connected chat platform. The agent translates your request into the appropriate CLI command, runs it via exec, and returns a human-readable summary. The 6 examples below cover the most common workflows — inbox triage, replying, scheduling, availability checks, search, and quick sends.

  • "What are my unread emails?" - the agent runs nylas email list --unread --limit 20 --json, parses the output, and summarizes the senders, subjects, and snippets.
  • "Reply to Sarah's email about the budget and say I'll have the numbers by Friday" - the agent lists recent messages, finds Sarah's email, uses nylas email smart-compose to draft a reply, shows you the draft, and sends it after you confirm.
  • "Schedule a 30-minute meeting with alice@company.com next Tuesday at 2pm" - the agent runs nylas calendar events create with the right timestamps and confirms the event was created.
  • "Am I free Thursday afternoon?" - the agent checks nylas calendar events list or nylas calendar availability check and tells you what is on your schedule.
  • "Find emails about the Q4 contract and pull out the key decisions" - the agent searches with nylas email search "Q4 contract" --json, reads the relevant threads, and summarizes the decisions.
  • "Tell bob@team.com I'll be 10 minutes late" - the agent composes a short message, confirms the content with you, and sends with --yes.

How the pieces connect

The OpenClaw + Nylas CLI integration involves 5 components in a linear chain: your messaging app, the OpenClaw gateway, the AI agent, the exec tool running CLI commands, and the Nylas API connecting to your email provider. All processing happens locally on your machine except for 2 external calls — the AI model API (Anthropic, OpenAI, etc.) and the Nylas API (for email and calendar operations).

All 5 components run locally except for 2 external network calls: the AI model API requests (to Anthropic, OpenAI, etc.) and the Nylas API requests (to read/send email and manage calendar). Your conversation history and workspace files never leave your machine.

Troubleshooting

The most common issues with the OpenClaw + Nylas CLI integration fall into 4 categories: PATH visibility, authentication, agent behavior, and exec approval prompts. Each problem below includes the root cause and a specific fix. Most issues resolve in under 2 minutes.

"nylas: command not found"

The gateway daemon does not see the nylas binary. This happens when the daemon starts with a minimal PATH that does not include Homebrew directories — common with launchd on macOS and systemd on Linux. Fix it by adding the directory to tools.exec.pathPrepend in ~/.openclaw/openclaw.json, or by restarting the daemon from a shell where which nylas resolves correctly.

Authentication errors from the CLI

If the Nylas CLI token has expired, the agent's exec calls fail with authentication errors. OAuth tokens issued by the Nylas API typically expire after 3600 seconds (1 hour), though the CLI handles refresh automatically in most cases. When automatic refresh fails, re-run nylas auth login from a terminal on the same machine. The refreshed credentials are stored locally and picked up on the next exec call.

# Re-authenticate
nylas auth login

# Verify
nylas auth whoami
nylas email list --limit 1

Agent sends email without asking first

The TOOLS.md instructions from the earlier configuration step tell the agent to confirm before sending. If the agent skips confirmation — which can happen when the model's instructions are long and the safety rule gets lost in context — reinforce the behavior in SOUL.md. This file controls the agent's persona and boundaries and is always loaded first, before other workspace files.

# Add to ~/.openclaw/workspace/SOUL.md

## Email safety
Never send an email without showing me the recipient, subject, and body first.
Wait for my explicit "send it" or "go ahead" before running nylas email send.

Exec approval prompts are annoying

Pre-approve the nylas binary in ~/.openclaw/exec-approvals.json so the agent can run Nylas CLI commands without prompting on every call. The exec-approvals.json configuration shown in the security section of this guide includes a full example. Alternatively, if you created the Nylas skill with autoAllowSkills: true, the binary is auto-approved and no manual entry is needed.

Next steps