From bec38ebc1dcaa03bf1e13cba8bbbae200a66af59 Mon Sep 17 00:00:00 2001 From: Jon Saad-Falcon <41205309+jonsaadfalcon@users.noreply.github.com> Date: Fri, 27 Mar 2026 17:01:17 -0700 Subject: [PATCH] docs: add Channels & Connectors troubleshooting guide Covers setup instructions and troubleshooting for all 12 connectors: Gmail, Google Drive, Calendar, Contacts, Slack, Notion, Granola, Apple Notes, iMessage, Outlook, Obsidian, Dropbox. Co-Authored-By: Claude Opus 4.6 (1M context) --- docs/user-guide/channels-and-connectors.md | 351 +++++++++++++++++++++ mkdocs.yml | 1 + 2 files changed, 352 insertions(+) create mode 100644 docs/user-guide/channels-and-connectors.md diff --git a/docs/user-guide/channels-and-connectors.md b/docs/user-guide/channels-and-connectors.md new file mode 100644 index 00000000..99ccd605 --- /dev/null +++ b/docs/user-guide/channels-and-connectors.md @@ -0,0 +1,351 @@ +# Channels & Connectors + +OpenJarvis connects to your personal data sources to power Deep Research. This guide walks you through setting up each connector and troubleshooting common issues. + +--- + +## Gmail + +**What it indexes:** Email messages and threads from your Gmail inbox. + +### Setup (App Password — recommended) + +1. **Enable 2-Factor Authentication** on your Google account: + [Open Google Security Settings →](https://myaccount.google.com/signinoptions/two-step-verification) + +2. **Generate an App Password** for "Mail": + [Open App Passwords →](https://myaccount.google.com/apppasswords) + - Select "Mail" as the app + - Copy the 16-character password (e.g. `qpde kebj evhy zljc`) + +3. **Connect in OpenJarvis:** + - Desktop/Browser: Agents → your agent → Channels tab → Gmail → Reconnect + - CLI: `uv run jarvis connect gmail_imap` + - Enter your email address and the app password + +### Troubleshooting + +| Issue | Solution | +|-------|----------| +| "App Passwords" page not available | Enable 2-Factor Authentication first | +| Login failed | Make sure you're using the app password, not your regular Google password | +| No emails syncing | Check that IMAP is enabled: [Gmail Settings → Forwarding and POP/IMAP](https://mail.google.com/mail/u/0/#settings/fwdandpop) | +| Only getting recent emails | By default, the last 500 emails are synced. Increase with `max_messages` config | + +--- + +## Google Drive + +**What it indexes:** Documents, Sheets, PDFs, and other files from your Drive. + +### Setup + +1. **Go to Google Cloud Console** and create a project (or use an existing one): + [Create Project →](https://console.cloud.google.com/projectcreate) + +2. **Enable the Google Drive API:** + [Enable Drive API →](https://console.cloud.google.com/apis/library/drive.googleapis.com) + +3. **Create OAuth credentials:** + [Open Credentials →](https://console.cloud.google.com/apis/credentials) + - Click "Create Credentials" → "OAuth 2.0 Client ID" + - Choose "Desktop app" as the application type + - Copy the **Client ID** and **Client Secret** + +4. **Add yourself as a test user** (required while app is unverified): + [Open OAuth Consent Screen →](https://console.cloud.google.com/apis/credentials/consent) + - Scroll to "Test users" → click "+ Add Users" + - Add your Gmail address (e.g. `jonsaadfalcon@gmail.com`) + +5. **Add the redirect URI:** + [Open Credentials →](https://console.cloud.google.com/apis/credentials) + - Click your OAuth Client → Authorized redirect URIs + - Add: `http://localhost:8789/callback` + +6. **Connect in OpenJarvis:** + - Desktop/Browser: Agents → Channels tab → Google Drive → paste Client ID and Client Secret + - Your browser will open Google's consent page → grant read-only access + - You'll see "Authorization successful!" → Drive data starts syncing + +### Troubleshooting + +| Issue | Solution | +|-------|----------| +| "Access blocked: app has not completed verification" | Add your email as a test user (step 4 above) | +| "Error 400: redirect_uri_mismatch" | Add `http://localhost:8789/callback` as an authorized redirect URI (step 5) | +| "Error 403: access_denied" | Make sure you selected "Desktop app" when creating the OAuth client | +| Connected but 0 files | Check that you granted Drive read access in the consent screen. Try reconnecting. | +| Token expired | Access tokens expire after 1 hour. Reconnect to get a new one. (Auto-refresh coming soon.) | + +--- + +## Google Calendar + +**What it indexes:** Events, meetings, and calendar entries. + +### Setup + +Same as Google Drive — use the same Google Cloud project and OAuth client. + +1. **Enable the Google Calendar API:** + [Enable Calendar API →](https://console.cloud.google.com/apis/library/calendar-json.googleapis.com) + +2. Follow steps 3-6 from the Google Drive section above (same Client ID/Secret works) + +### Troubleshooting + +Same as Google Drive. Additionally: + +| Issue | Solution | +|-------|----------| +| Only seeing primary calendar | The connector reads all calendars you have access to | +| Missing shared calendars | Shared calendars from other users may require additional permissions | + +--- + +## Google Contacts + +**What it indexes:** People, phone numbers, emails, and contact information. + +### Setup + +Same as Google Drive — use the same Google Cloud project and OAuth client. + +1. **Enable the People API:** + [Enable People API →](https://console.cloud.google.com/apis/library/people.googleapis.com) + +2. Follow steps 3-6 from the Google Drive section above + +--- + +## Slack + +**What it indexes:** Channel messages and threads from your Slack workspace. + +### Setup + +1. **Go to Slack App Settings:** + [Open Slack Apps →](https://api.slack.com/apps) + +2. **Create a new app** (or use existing): + - Click "Create New App" → "From scratch" + - Name it (e.g. "OpenJarvis") and select your workspace + +3. **Add OAuth scopes:** + - Go to "OAuth & Permissions" + - Under "Bot Token Scopes", add: `channels:history`, `channels:read`, `users:read` + +4. **Install to workspace:** + - Click "Install to Workspace" → Authorize + - Copy the **Bot User OAuth Token** (starts with `xoxb-`) + +5. **Connect in OpenJarvis:** + - Desktop/Browser: Agents → Channels tab → Slack → paste the bot token + - CLI: `uv run jarvis connect slack` + +### Troubleshooting + +| Issue | Solution | +|-------|----------| +| "not_allowed_token_type" | Make sure you're using the **Bot** token (`xoxb-...`), not a user token (`xoxp-`) or session token (`xoxe-`) | +| No messages found | The bot can only see channels it's been added to. Invite it: `/invite @OpenJarvis` in the channel | +| Missing private channels | Add `groups:history` and `groups:read` scopes, then reinstall the app | + +--- + +## Notion + +**What it indexes:** Pages, databases, and their content. + +### Setup + +1. **Create an internal integration:** + [Open Notion Integrations →](https://www.notion.so/profile/integrations) + - Click "New integration" + - Name it (e.g. "OpenJarvis") + - Select your workspace + - Copy the **Internal Integration Secret** (starts with `ntn_`) + +2. **Share pages with your integration:** + - Open any Notion page you want indexed + - Click "..." (top right) → "Connections" → find your integration → click it + - Repeat for each page or database + +3. **Connect in OpenJarvis:** + - Desktop/Browser: Agents → Channels tab → Notion → paste the token + - CLI: `uv run jarvis connect notion` + +### Troubleshooting + +| Issue | Solution | +|-------|----------| +| 0 pages found | You must explicitly share pages with the integration (step 2). The integration can only see pages you've connected. | +| Missing database content | Share the database page itself, not just individual entries | +| Token expired | Notion integration tokens don't expire. If it stops working, regenerate at the integrations page. | + +--- + +## Granola + +**What it indexes:** AI meeting notes and transcripts from the Granola app. + +### Setup + +1. **Open the Granola desktop app** → Settings → API +2. **Copy your API key** (starts with `grn_`) +3. **Connect in OpenJarvis:** + - Desktop/Browser: Agents → Channels tab → Granola → paste the key + - CLI: `uv run jarvis connect granola` + +### Troubleshooting + +| Issue | Solution | +|-------|----------| +| No API key in settings | Granola API is available on Business and Enterprise plans | +| 0 meeting notes | Check that you have meetings recorded in Granola | + +--- + +## Apple Notes + +**What it indexes:** Notes from the macOS Notes app. + +### Setup (automatic) + +1. **Grant Full Disk Access** to your terminal app: + - Open System Settings → Privacy & Security → Full Disk Access + - Enable access for Terminal, iTerm, Warp, or the OpenJarvis desktop app + +2. Apple Notes is detected automatically when Full Disk Access is granted + +### Troubleshooting + +| Issue | Solution | +|-------|----------| +| "Not connected" despite Full Disk Access | Restart your terminal app after granting access | +| Notes content is garbled | Some very old notes may have encoding issues. Most notes should be clean. | +| Missing notes | Only notes stored locally or in iCloud are indexed. Notes in third-party accounts (Gmail, Exchange) may not appear. | + +--- + +## iMessage + +**What it indexes:** Text messages from the macOS Messages app. + +### Setup (automatic) + +Same as Apple Notes — requires Full Disk Access. + +### Troubleshooting + +| Issue | Solution | +|-------|----------| +| "Not connected" | Grant Full Disk Access (see Apple Notes above) | +| Very slow sync | iMessage databases can be large (50K+ messages). First sync may take 10-30 seconds. | +| Missing recent messages | Messages sync from the local database. If Messages.app hasn't synced from iCloud yet, recent messages may be missing. | + +--- + +## Outlook / Microsoft 365 + +**What it indexes:** Email messages via IMAP. + +### Setup + +1. **Enable 2-Factor Authentication** on your Microsoft account: + [Open Microsoft Security →](https://account.microsoft.com/security) + +2. **Generate an App Password:** + - Go to Security → Advanced security options → App passwords + - Create a new app password + +3. **Connect in OpenJarvis:** + - Desktop/Browser: Agents → Channels tab → Outlook → enter email + app password + - CLI: `uv run jarvis connect outlook` + +### Troubleshooting + +| Issue | Solution | +|-------|----------| +| Login failed | Use the app password, not your regular Microsoft password | +| "Authentication failed" | Some Microsoft 365 organizations disable IMAP. Check with your IT admin. | +| Only getting Inbox | Currently only the Inbox folder is synced | + +--- + +## Obsidian + +**What it indexes:** Markdown files from your Obsidian vault. + +### Setup + +1. Find your Obsidian vault folder (the folder containing the `.obsidian` directory) +2. **Connect in OpenJarvis:** + - Desktop/Browser: Agents → Channels tab → Obsidian → paste the vault path + - CLI: `uv run jarvis connect obsidian --path /path/to/vault` + +### Troubleshooting + +| Issue | Solution | +|-------|----------| +| "Not connected" | Double-check the path exists and contains a `.obsidian` folder | +| Missing files | Only `.md`, `.markdown`, and `.txt` files are indexed. Binary files and images are skipped. | +| Slow sync for large vaults | Vaults with 1000+ files may take a minute to sync | + +--- + +## Dropbox + +**What it indexes:** Files and documents from your Dropbox. + +### Setup + +1. **Create a Dropbox app:** + [Open Dropbox App Console →](https://www.dropbox.com/developers/apps/create) + - Choose "Scoped access" → "Full Dropbox" + +2. **Set permissions:** + - Under Permissions tab, enable `files.metadata.read` and `files.content.read` + +3. **Generate an access token:** + - Go to Settings tab → "Generated access token" → Generate + +4. **Connect in OpenJarvis:** + - Desktop/Browser: Agents → Channels tab → Dropbox → paste the token + - CLI: `uv run jarvis connect dropbox` + +### Troubleshooting + +| Issue | Solution | +|-------|----------| +| "Invalid access token" | Dropbox short-lived tokens expire after 4 hours. Generate a new one. | +| Missing files | Check that you enabled the correct permissions (step 2) | + +--- + +## General Troubleshooting + +### All connectors + +| Issue | Solution | +|-------|----------| +| "Connected — no data synced yet" | The connector authenticated but hasn't synced. Try running `uv run jarvis deep-research-setup --skip-chat` to trigger a sync. | +| Data seems stale | Connectors sync on demand. Run the setup command or click "Reconnect" to re-sync. | +| Want to reset a connector | Click "Reconnect" in the Channels tab, or delete the credential file at `~/.openjarvis/connectors/{connector}.json` | + +### Where credentials are stored + +All credentials are saved locally at `~/.openjarvis/connectors/` with file permissions `0600` (owner-only read/write). No credentials are sent to any server — everything stays on your device. + +``` +~/.openjarvis/connectors/ +├── gmail_imap.json # Gmail email + app password +├── gdrive.json # Google Drive OAuth tokens +├── gcalendar.json # Google Calendar OAuth tokens +├── gcontacts.json # Google Contacts OAuth tokens +├── slack.json # Slack bot token +├── notion.json # Notion integration token +├── granola.json # Granola API key +├── outlook.json # Outlook email + app password +└── dropbox.json # Dropbox access token +``` diff --git a/mkdocs.yml b/mkdocs.yml index a90a5e9c..ddf85eec 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -165,6 +165,7 @@ nav: - Design Principles: architecture/design-principles.md - API Reference: api-reference/ - User Guide: + - Channels & Connectors: user-guide/channels-and-connectors.md - Tools: user-guide/tools.md - External MCP Servers: user-guide/mcp-external-servers.md - Leaderboard: leaderboard.md