Guide

Use Nylas CLI with OpenClaw as Your AI Personal Assistant

OpenClaw is an open-source, self-hosted AI assistant that connects to WhatsApp, Telegram, Discord, iMessage, and other messaging apps. It runs 24/7 on your own machine and keeps your data local. The Nylas CLI gives it the ability to read your inbox, send email, and manage your calendar. This guide walks through setup, configuration, and the security considerations you should know about.

What is OpenClaw?

OpenClaw is an open-source (MIT license) personal AI assistant created by Peter Steinberger. It acts as a gateway between your messaging apps and an AI agent (Claude, GPT-4, or other models). You message it from WhatsApp, Telegram, Discord, Slack, Signal, or iMessage, and it responds with the full capabilities of the underlying model plus any tools you give it access to.

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.).

OpenClaw organizes its knowledge through workspace files (AGENTS.md, TOOLS.md, SOUL.md, MEMORY.md) and a skill system with thousands of 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 will interact with the Nylas CLI.

Why add Nylas CLI?

OpenClaw can manage tasks, search the web, read and write files, and control a browser. But it does not have built-in email or calendar access. The Nylas CLI bridges that gap. Once installed and authenticated, OpenClaw's exec tool can run commands like nylas email list, nylas email send, and nylas calendar events list to interact with Gmail, Outlook, or any provider supported by the Nylas API.

This 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 will handle the rest without you opening a browser or email client.

1. Prerequisites

OpenClaw installed and running

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

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:

openclaw gateway --port 18789

Nylas CLI installed and authenticated

# macOS / Linux
brew install nylas-cli/tap/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 injects several workspace files into the agent's context at the start of each session. The most relevant one for tool guidance is TOOLS.md, which lives at ~/.openclaw/workspace/TOOLS.md by default. Open it and add a section for the Nylas CLI:

## 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 list --query "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

### 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

By default, OpenClaw's exec tool runs with security: "deny" in sandboxed mode and security: "allowlist" on the gateway/node host. This means the agent needs approval before running commands it has not been explicitly allowed to use. You have a few options:

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.

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". The agent will be able to run any binary in those directories:

// ~/.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

Skills are a more structured alternative to editing TOOLS.md. They live in ~/.openclaw/workspace/skills/ (workspace-level, highest priority) or ~/.openclaw/skills/ (managed). Each skill is a folder containing a SKILL.md file with frontmatter and instructions.

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 list --query "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

## 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

The requires.bins field tells OpenClaw the skill needs the nylas binary. If skill file watching is enabled (the default), the skill is picked up automatically on the next agent turn. Otherwise, restart the gateway or start a new session.

5. MCP alternative

OpenClaw supports MCP (Model Context Protocol) servers, which provide native tool schemas instead of shell commands. If you prefer structured tool calls over exec, add the Nylas MCP server to your config:

// ~/.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 everything is configured, here are realistic prompts and what happens under the hood:

  • "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 list --query "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

All of this runs locally except for the AI model API calls (to Anthropic, OpenAI, etc.) and the Nylas API calls (to read/send email and manage calendar). Your conversation history and workspace files never leave your machine.

Troubleshooting

"nylas: command not found"

The gateway daemon does not see the nylas binary. This usually happens because the daemon was started with a minimal PATH that does not include Homebrew directories. 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

# Re-authenticate
nylas auth login

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

If the Nylas CLI token has expired, the agent's exec calls will fail with authentication errors. 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.

Agent sends email without asking first

By default, the TOOLS.md instructions above tell the agent to confirm before sending. If the agent skips confirmation, reinforce the behavior in SOUL.md (which controls the agent's persona and boundaries):

# 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

If you are getting approval prompts on every Nylas CLI invocation, approve the binary once and it is saved to ~/.openclaw/exec-approvals.json. Alternatively, set ask: "off" for the exec tool in config (only do this if you trust the agent fully and understand the security implications).

Next steps