# OpenClaw + PortEden Setup

Add secure calendar and email access to your OpenClaw agent.
List events, create meetings, send and manage emails, RSVP to invitations, and more.

## 1. Install the PortEden CLI

The skills require the `porteden` binary. Pick one:

```bash
# Homebrew (macOS / Linux)
brew install porteden/tap/porteden

# Install script
curl -sSfL https://raw.githubusercontent.com/porteden/cli/main/install.sh | bash

# Go install
go install github.com/porteden/cli/cmd/porteden@latest
```

Verify:

```bash
porteden --version
```

## 2. Install the Skills

```bash
clawhub install porteden/calendar
clawhub install porteden/email
```

This places the skills in `~/openclaw/skills/porteden/`.

To install at the workspace level instead (higher priority):

```bash
cp -r porteden/ <workspace>/skills/porteden/
```

## 3. Authenticate

**If the user is at the computer - prefer browser login**:

```bash
porteden auth login
```

This opens the browser to authenticate and stores the credentials locally.

**If the user is on a remote channel** (Telegram, WhatsApp, or other gateway):

Direct them to https://my.porteden.com to create an account and generate an API key.
Then authenticate with:

```bash
porteden auth login --token pe_their_key_here
```

## 4. Add the Key to OpenClaw Config

OpenClaw sessions don't inherit CLI credentials or shell environment variables.
The key must be in the config so it's injected into every session.

Get your key (if you used browser login, it was shown in the output):

```bash
porteden auth status
```

Add to `~/.openclaw/openclaw.json`:

```json
{
  "skills": {
    "entries": {
      "porteden": {
        "enabled": true,
        "env": {
          "PE_API_KEY": "pe_your_api_key"
        }
      }
    }
  }
}
```

Verify:

```bash
porteden auth status
```

## Available Commands

All commands use `-jc` for compact JSON output optimized for LLM consumption.

### Calendar – Read Commands

| Command | Description |
|---------|-------------|
| `porteden calendar calendars -jc` | List all accessible calendars |
| `porteden calendar events --today -jc` | Today's events (also `--tomorrow`, `--week`) |
| `porteden calendar events --from <date> --to <date> -jc` | Events in a custom date range |
| `porteden calendar events --week --all -jc` | Auto-paginate all results |
| `porteden calendar events -q "keyword" --today -jc` | Search events by keyword |
| `porteden calendar by-contact "email" -jc` | Find events shared with a contact |
| `porteden calendar event <eventId> -jc` | Get a single event by ID |

### Calendar – Write Commands

| Command | Description |
|---------|-------------|
| `porteden calendar create --calendar <id> --summary "..." --from "..." --to "..."` | Create a new event |
| `porteden calendar update <eventId> --summary "New Title"` | Update event fields |
| `porteden calendar update <eventId> --add-attendees "a@b.com" --notify` | Add attendees with notification |
| `porteden calendar update <eventId> --remove-attendees "a@b.com"` | Remove attendees |
| `porteden calendar delete <eventId>` | Delete an event |
| `porteden calendar respond <eventId> accepted` | RSVP (`accepted`, `declined`, `tentative`) |

### Email – Read Commands

| Command | Description |
|---------|-------------|
| `porteden email messages -jc` | List recent emails |
| `porteden email messages --today -jc` | Today's emails (also `--week`, `--days N`) |
| `porteden email messages --unread -jc` | Unread emails only |
| `porteden email messages -q "keyword" -jc` | Search emails by keyword |
| `porteden email messages --from boss@example.com -jc` | Filter by sender |
| `porteden email messages --subject "invoice" -jc` | Filter by subject |
| `porteden email messages --has-attachment -jc` | Emails with attachments |
| `porteden email messages --week --all -jc` | Auto-paginate all results |
| `porteden email message <emailId> -jc` | Get a single email by ID |
| `porteden email thread <threadId> -jc` | Get an email thread |

### Email – Write Commands

| Command | Description |
|---------|-------------|
| `porteden email send --to user@example.com --subject "Hi" --body "Hello"` | Send a new email |
| `porteden email reply <emailId> --body "Thanks"` | Reply to sender |
| `porteden email reply <emailId> --body "Thanks" --reply-all` | Reply to all recipients |
| `porteden email forward <emailId> --to colleague@example.com` | Forward an email |
| `porteden email modify <emailId> --mark-read` | Mark as read |
| `porteden email modify <emailId> --add-labels IMPORTANT` | Add labels |
| `porteden email delete <emailId>` | Delete an email |

## Usage Examples

**User:** "What's on my calendar today?"

```bash
porteden calendar events --today -jc
```

**User:** "Schedule a 30-min sync with alice@acme.com tomorrow at 2pm"

```bash
porteden calendar create \
  --calendar 1 \
  --summary "Sync with Alice" \
  --from "2026-02-08T14:00:00Z" \
  --to "2026-02-08T14:30:00Z" \
  --attendees "alice@acme.com"
```

**User:** "Do I have any meetings with the marketing team this week?"

```bash
porteden calendar events -q "marketing" --week -jc
```

**User:** "Any unread emails from my boss today?"

```bash
porteden email messages --from boss@example.com --unread --today -jc
```

**User:** "Reply to that email saying I'll review it by end of day"

```bash
porteden email reply <emailId> --body "I'll review it by end of day."
```

**User:** "Send an email to the team about tomorrow's standup being moved to 3pm"

```bash
porteden email send \
  --to team@example.com \
  --subject "Standup moved to 3pm" \
  --body "Hi team, tomorrow's standup has been moved to 3pm."
```

## Tips

| Variable | Description |
|----------|-------------|
| `PE_API_KEY` | API key (overrides stored credentials) |
| `PE_PROFILE` | Default profile name (for multi-account setups) |
| `PE_TIMEZONE` | Output timezone (e.g. `America/New_York`) |

- `-jc` combines `--json` and `--compact`: filters noise, truncates long fields, reduces token usage
- Use `--all` to auto-paginate large result sets
- Get calendar IDs with `porteden calendar calendars -jc` before creating events
- Confirm before creating, updating, or deleting events and before sending, replying, or forwarding emails
- All times use RFC 3339 UTC format: `2026-02-01T10:00:00Z`

## Permissions & Security

Access is governed by the API key's [token permissions](https://porteden.com/docs/api/token-permissions/).

You can restrict what the agent can do:

- **Read-only access:** set `masterAccessLevel` to `view_only`
- **Filtered fields:** hide sensitive data with `visibleFields`
- **Time window:** limit access with `timeframePastDays` / `timeframeFutureDays`
- **Access rules:** fine-grained control per calendar or contact via [access rules](https://porteden.com/docs/api/access-rules/)

Create a dedicated API key with only the permissions the agent needs.