v2: channel isolation model, manage-channels skill, refactored channel skills
- Add three-level isolation model (shared session, same agent, separate agent) with agent-shared session mode for cross-channel shared sessions - Create /manage-channels skill for wiring channels to agent groups - Refactor all 12 v2 channel skills: lean SKILL.md + VERIFY.md + REMOVE.md with structured Channel Info section for platform-specific metadata - Create /add-discord-v2 skill (was missing) - Add step 5a to setup SKILL.md invoking /manage-channels after channel install - Update setup/verify.ts to check all 12 channel token types - Add docs/v2-isolation-model.md explaining the isolation model - Update v2-checklist.md and v2-setup-wiring.md to reflect completed work Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
gavrielc
7
.claude/skills/add-discord-v2/REMOVE.md
Normal file
7
.claude/skills/add-discord-v2/REMOVE.md
Normal file
@@ -0,0 +1,7 @@
|
||||
# Remove Discord
|
||||
|
||||
1. Comment out `import './discord.js'` in `src/channels/index.ts`
|
||||
2. Remove `DISCORD_BOT_TOKEN` from `.env`
|
||||
3. Rebuild and restart
|
||||
|
||||
No package to uninstall — Discord is built in.
|
||||
69
.claude/skills/add-discord-v2/SKILL.md
Normal file
69
.claude/skills/add-discord-v2/SKILL.md
Normal file
@@ -0,0 +1,69 @@
|
||||
---
|
||||
name: add-discord-v2
|
||||
description: Add Discord bot channel integration to NanoClaw v2 via Chat SDK.
|
||||
---
|
||||
|
||||
# Add Discord Channel
|
||||
|
||||
Adds Discord bot support to NanoClaw v2. Discord is built in — no adapter package to install.
|
||||
|
||||
## Pre-flight
|
||||
|
||||
Check if `src/channels/discord.ts` exists and the import is uncommented in `src/channels/index.ts`. If both are in place, skip to Credentials.
|
||||
|
||||
## Install
|
||||
|
||||
Discord support is bundled with NanoClaw — there is no separate package to install.
|
||||
|
||||
### Enable the channel
|
||||
|
||||
Uncomment the Discord import in `src/channels/index.ts`:
|
||||
|
||||
```typescript
|
||||
import './discord.js';
|
||||
```
|
||||
|
||||
### Build
|
||||
|
||||
```bash
|
||||
npm run build
|
||||
```
|
||||
|
||||
## Credentials
|
||||
|
||||
### Create Discord Bot
|
||||
|
||||
1. Go to the [Discord Developer Portal](https://discord.com/developers/applications)
|
||||
2. Click **New Application** and give it a name (e.g., "NanoClaw Assistant")
|
||||
3. Go to the **Bot** tab and click **Add Bot** if needed
|
||||
4. Copy the Bot Token (click **Reset Token** if you need a new one — you can only see it once)
|
||||
5. Under **Privileged Gateway Intents**, enable **Message Content Intent**
|
||||
6. Go to **OAuth2** > **URL Generator**:
|
||||
- Scopes: select `bot`
|
||||
- Bot Permissions: select `Send Messages`, `Read Message History`, `Add Reactions`, `Attach Files`, `Use Slash Commands`
|
||||
7. Copy the generated URL and open it in your browser to invite the bot to your server
|
||||
|
||||
### Configure environment
|
||||
|
||||
Add to `.env`:
|
||||
|
||||
```bash
|
||||
DISCORD_BOT_TOKEN=your-bot-token
|
||||
```
|
||||
|
||||
Sync to container: `mkdir -p data/env && cp .env data/env/env`
|
||||
|
||||
## Next Steps
|
||||
|
||||
If you're in the middle of `/setup`, return to the setup flow now.
|
||||
|
||||
Otherwise, run `/manage-channels` to wire this channel to an agent group.
|
||||
|
||||
## Channel Info
|
||||
|
||||
- **type**: `discord`
|
||||
- **terminology**: Discord has "servers" (also called "guilds") containing "channels." Text channels start with #. The bot can also receive direct messages.
|
||||
- **how-to-find-id**: Enable Developer Mode in Discord (Settings > App Settings > Advanced > Developer Mode). Then right-click a server or channel and select "Copy ID."
|
||||
- **supports-threads**: yes
|
||||
- **typical-use**: Interactive chat — server channels or direct messages
|
||||
- **default-isolation**: Same agent group for your personal server. Separate agent group for servers with different communities or where different members have different information boundaries.
|
||||
3
.claude/skills/add-discord-v2/VERIFY.md
Normal file
3
.claude/skills/add-discord-v2/VERIFY.md
Normal file
@@ -0,0 +1,3 @@
|
||||
# Verify Discord
|
||||
|
||||
Send a message in a channel where the bot has access, or DM the bot directly. The bot should respond within a few seconds.
|
||||
6
.claude/skills/add-gchat-v2/REMOVE.md
Normal file
6
.claude/skills/add-gchat-v2/REMOVE.md
Normal file
@@ -0,0 +1,6 @@
|
||||
# Remove Google Chat Channel
|
||||
|
||||
1. Comment out `import './gchat.js'` in `src/channels/index.ts`
|
||||
2. Remove `GCHAT_CREDENTIALS` from `.env`
|
||||
3. `npm uninstall @chat-adapter/gchat`
|
||||
4. Rebuild and restart
|
||||
@@ -3,39 +3,31 @@ name: add-gchat-v2
|
||||
description: Add Google Chat channel integration to NanoClaw v2 via Chat SDK.
|
||||
---
|
||||
|
||||
# Add Google Chat Channel (v2)
|
||||
# Add Google Chat Channel
|
||||
|
||||
This skill adds Google Chat support to NanoClaw v2 using the Chat SDK bridge.
|
||||
Adds Google Chat support to NanoClaw v2 using the Chat SDK bridge.
|
||||
|
||||
## Phase 1: Pre-flight
|
||||
## Pre-flight
|
||||
|
||||
Check if `src/channels/gchat.ts` exists and the import is uncommented in `src/channels/index.ts`. If both are in place, skip to Phase 3.
|
||||
Check if `src/channels/gchat.ts` exists and the import is uncommented in `src/channels/index.ts`. If both are in place, skip to Credentials.
|
||||
|
||||
## Phase 2: Apply Code Changes
|
||||
|
||||
### Install the adapter package
|
||||
## Install
|
||||
|
||||
```bash
|
||||
npm install @chat-adapter/gchat
|
||||
```
|
||||
|
||||
### Enable the channel
|
||||
|
||||
Uncomment the Google Chat import in `src/channels/index.ts`:
|
||||
|
||||
```typescript
|
||||
import './gchat.js';
|
||||
```
|
||||
|
||||
### Build
|
||||
|
||||
```bash
|
||||
npm run build
|
||||
```
|
||||
|
||||
## Phase 3: Setup
|
||||
|
||||
### Create Google Chat App
|
||||
## Credentials
|
||||
|
||||
> 1. Go to [Google Cloud Console](https://console.cloud.google.com)
|
||||
> 2. Create or select a project
|
||||
@@ -58,21 +50,17 @@ GCHAT_CREDENTIALS={"type":"service_account","project_id":"...","private_key":"..
|
||||
|
||||
Sync to container: `mkdir -p data/env && cp .env data/env/env`
|
||||
|
||||
### Build and restart
|
||||
## Next Steps
|
||||
|
||||
```bash
|
||||
npm run build
|
||||
launchctl kickstart -k gui/$(id -u)/com.nanoclaw # macOS
|
||||
# systemctl --user restart nanoclaw # Linux
|
||||
```
|
||||
If you're in the middle of `/setup`, return to the setup flow now.
|
||||
|
||||
## Phase 4: Verify
|
||||
Otherwise, run `/manage-channels` to wire this channel to an agent group.
|
||||
|
||||
> Add the bot to a Google Chat space, then send a message or @mention the bot.
|
||||
## Channel Info
|
||||
|
||||
## Removal
|
||||
|
||||
1. Comment out `import './gchat.js'` in `src/channels/index.ts`
|
||||
2. Remove `GCHAT_CREDENTIALS` from `.env`
|
||||
3. `npm uninstall @chat-adapter/gchat`
|
||||
4. Rebuild and restart
|
||||
- **type**: `gchat`
|
||||
- **terminology**: Google Chat has "spaces." A space can be a group conversation or a direct message with the bot.
|
||||
- **how-to-find-id**: Open the space in Google Chat, look at the URL — the space ID is the segment after `/space/` (e.g. `spaces/AAAA...`). Or use the Google Chat API to list spaces.
|
||||
- **supports-threads**: yes
|
||||
- **typical-use**: Interactive chat — team spaces or direct messages
|
||||
- **default-isolation**: Same agent group for spaces where you're the primary user. Separate agent group for spaces with different teams or sensitive contexts.
|
||||
|
||||
3
.claude/skills/add-gchat-v2/VERIFY.md
Normal file
3
.claude/skills/add-gchat-v2/VERIFY.md
Normal file
@@ -0,0 +1,3 @@
|
||||
# Verify Google Chat Channel
|
||||
|
||||
Add the bot to a Google Chat space, then send a message or @mention the bot. The bot should respond within a few seconds.
|
||||
6
.claude/skills/add-github-v2/REMOVE.md
Normal file
6
.claude/skills/add-github-v2/REMOVE.md
Normal file
@@ -0,0 +1,6 @@
|
||||
# Remove GitHub Channel
|
||||
|
||||
1. Comment out `import './github.js'` in `src/channels/index.ts`
|
||||
2. Remove `GITHUB_TOKEN` and `GITHUB_WEBHOOK_SECRET` from `.env`
|
||||
3. `npm uninstall @chat-adapter/github`
|
||||
4. Rebuild and restart
|
||||
@@ -1,41 +1,33 @@
|
||||
---
|
||||
name: add-github-v2
|
||||
description: Add GitHub channel integration to NanoClaw v2 via Chat SDK. PR comment threads as conversations.
|
||||
description: Add GitHub channel integration to NanoClaw v2 via Chat SDK. PR and issue comment threads as conversations.
|
||||
---
|
||||
|
||||
# Add GitHub Channel (v2)
|
||||
# Add GitHub Channel
|
||||
|
||||
This skill adds GitHub support to NanoClaw v2 using the Chat SDK bridge. The agent can participate in PR comment threads.
|
||||
Adds GitHub support to NanoClaw v2 using the Chat SDK bridge. The agent participates in PR and issue comment threads.
|
||||
|
||||
## Phase 1: Pre-flight
|
||||
## Pre-flight
|
||||
|
||||
Check if `src/channels/github.ts` exists and the import is uncommented in `src/channels/index.ts`. If both are in place, skip to Phase 3.
|
||||
Check if `src/channels/github.ts` exists and the import is uncommented in `src/channels/index.ts`. If both are in place, skip to Credentials.
|
||||
|
||||
## Phase 2: Apply Code Changes
|
||||
|
||||
### Install the adapter package
|
||||
## Install
|
||||
|
||||
```bash
|
||||
npm install @chat-adapter/github
|
||||
```
|
||||
|
||||
### Enable the channel
|
||||
|
||||
Uncomment the GitHub import in `src/channels/index.ts`:
|
||||
|
||||
```typescript
|
||||
import './github.js';
|
||||
```
|
||||
|
||||
### Build
|
||||
|
||||
```bash
|
||||
npm run build
|
||||
```
|
||||
|
||||
## Phase 3: Setup
|
||||
|
||||
### Create GitHub credentials
|
||||
## Credentials
|
||||
|
||||
> 1. Go to [GitHub Settings > Developer Settings > Personal Access Tokens](https://github.com/settings/tokens)
|
||||
> 2. Create a **Fine-grained token** with:
|
||||
@@ -60,21 +52,17 @@ GITHUB_WEBHOOK_SECRET=your-webhook-secret
|
||||
|
||||
Sync to container: `mkdir -p data/env && cp .env data/env/env`
|
||||
|
||||
### Build and restart
|
||||
## Next Steps
|
||||
|
||||
```bash
|
||||
npm run build
|
||||
launchctl kickstart -k gui/$(id -u)/com.nanoclaw # macOS
|
||||
# systemctl --user restart nanoclaw # Linux
|
||||
```
|
||||
If you're in the middle of `/setup`, return to the setup flow now.
|
||||
|
||||
## Phase 4: Verify
|
||||
Otherwise, run `/manage-channels` to wire this channel to an agent group.
|
||||
|
||||
> @mention the bot in a PR comment or issue comment. The bot should respond within a few seconds.
|
||||
## Channel Info
|
||||
|
||||
## Removal
|
||||
|
||||
1. Comment out `import './github.js'` in `src/channels/index.ts`
|
||||
2. Remove `GITHUB_TOKEN` and `GITHUB_WEBHOOK_SECRET` from `.env`
|
||||
3. `npm uninstall @chat-adapter/github`
|
||||
4. Rebuild and restart
|
||||
- **type**: `github`
|
||||
- **terminology**: GitHub has "repositories" containing "pull requests" and "issues." Each PR or issue comment thread is a separate conversation.
|
||||
- **how-to-find-id**: The platform ID is `owner/repo` (e.g. `acme/backend`). Each PR/issue becomes its own thread automatically.
|
||||
- **supports-threads**: yes (PR and issue comment threads are native conversations)
|
||||
- **typical-use**: Webhook/notification — the agent receives PR and issue events and responds in comment threads
|
||||
- **default-isolation**: Typically shares a session with a chat channel (e.g. Slack) so the agent can summarize PRs and respond to reviews in the same context. Use a separate agent group if the repo contains sensitive code that other channels shouldn't access.
|
||||
|
||||
3
.claude/skills/add-github-v2/VERIFY.md
Normal file
3
.claude/skills/add-github-v2/VERIFY.md
Normal file
@@ -0,0 +1,3 @@
|
||||
# Verify GitHub Channel
|
||||
|
||||
@mention the bot in a PR comment or issue comment. The bot should respond within a few seconds.
|
||||
6
.claude/skills/add-imessage-v2/REMOVE.md
Normal file
6
.claude/skills/add-imessage-v2/REMOVE.md
Normal file
@@ -0,0 +1,6 @@
|
||||
# Remove iMessage Channel
|
||||
|
||||
1. Comment out `import './imessage.js'` in `src/channels/index.ts`
|
||||
2. Remove iMessage env vars (`IMESSAGE_ENABLED`, `IMESSAGE_LOCAL`, `IMESSAGE_SERVER_URL`, `IMESSAGE_API_KEY`) from `.env`
|
||||
3. `npm uninstall chat-adapter-imessage`
|
||||
4. Rebuild and restart
|
||||
@@ -3,61 +3,55 @@ name: add-imessage-v2
|
||||
description: Add iMessage channel integration to NanoClaw v2 via Chat SDK. Local (macOS) or remote (Photon API) mode.
|
||||
---
|
||||
|
||||
# Add iMessage Channel (v2)
|
||||
# Add iMessage Channel
|
||||
|
||||
This skill adds iMessage support to NanoClaw v2 using the Chat SDK bridge. Supports local mode (macOS with Full Disk Access) and remote mode (via Photon API).
|
||||
Adds iMessage support to NanoClaw v2 using the Chat SDK bridge. Two modes: local (macOS with Full Disk Access) or remote (Photon API).
|
||||
|
||||
## Phase 1: Pre-flight
|
||||
## Pre-flight
|
||||
|
||||
Check if `src/channels/imessage.ts` exists and the import is uncommented in `src/channels/index.ts`. If both are in place, skip to Phase 3.
|
||||
Check if `src/channels/imessage.ts` exists and the import is uncommented in `src/channels/index.ts`. If both are in place, skip to Credentials.
|
||||
|
||||
## Phase 2: Apply Code Changes
|
||||
|
||||
### Install the adapter package
|
||||
## Install
|
||||
|
||||
```bash
|
||||
npm install chat-adapter-imessage
|
||||
```
|
||||
|
||||
### Enable the channel
|
||||
|
||||
Uncomment the iMessage import in `src/channels/index.ts`:
|
||||
|
||||
```typescript
|
||||
import './imessage.js';
|
||||
```
|
||||
|
||||
### Build
|
||||
|
||||
```bash
|
||||
npm run build
|
||||
```
|
||||
|
||||
## Phase 3: Setup
|
||||
## Credentials
|
||||
|
||||
### Local Mode (macOS)
|
||||
|
||||
> **Requirements**: macOS with Full Disk Access granted to your terminal/Node.js process.
|
||||
>
|
||||
> 1. Go to **System Settings** > **Privacy & Security** > **Full Disk Access**
|
||||
> 2. Add your terminal app (Terminal, iTerm2, etc.) or the Node.js binary
|
||||
> 3. The adapter reads directly from the iMessage database on disk
|
||||
Requirements: macOS with Full Disk Access granted to your terminal/Node.js process.
|
||||
|
||||
1. Go to **System Settings** > **Privacy & Security** > **Full Disk Access**
|
||||
2. Add your terminal app (Terminal, iTerm2, etc.) or the Node.js binary
|
||||
3. The adapter reads directly from the iMessage database on disk
|
||||
|
||||
### Remote Mode (Photon API)
|
||||
|
||||
> 1. Set up a [Photon](https://photon.im) account
|
||||
> 2. Get your server URL and API key
|
||||
1. Set up a [Photon](https://photon.im) account
|
||||
2. Get your server URL and API key
|
||||
|
||||
### Configure environment
|
||||
|
||||
**Local mode** — add to `.env`:
|
||||
**Local mode** -- add to `.env`:
|
||||
|
||||
```bash
|
||||
IMESSAGE_ENABLED=true
|
||||
IMESSAGE_LOCAL=true
|
||||
```
|
||||
|
||||
**Remote mode** — add to `.env`:
|
||||
**Remote mode** -- add to `.env`:
|
||||
|
||||
```bash
|
||||
IMESSAGE_LOCAL=false
|
||||
@@ -67,20 +61,17 @@ IMESSAGE_API_KEY=your-api-key
|
||||
|
||||
Sync to container: `mkdir -p data/env && cp .env data/env/env`
|
||||
|
||||
### Build and restart
|
||||
## Next Steps
|
||||
|
||||
```bash
|
||||
npm run build
|
||||
launchctl kickstart -k gui/$(id -u)/com.nanoclaw # macOS
|
||||
```
|
||||
If you're in the middle of `/setup`, return to the setup flow now.
|
||||
|
||||
## Phase 4: Verify
|
||||
Otherwise, run `/manage-channels` to wire this channel to an agent group.
|
||||
|
||||
> Send an iMessage to the account running NanoClaw. The bot should respond within a few seconds.
|
||||
## Channel Info
|
||||
|
||||
## Removal
|
||||
|
||||
1. Comment out `import './imessage.js'` in `src/channels/index.ts`
|
||||
2. Remove iMessage env vars from `.env`
|
||||
3. `npm uninstall chat-adapter-imessage`
|
||||
4. Rebuild and restart
|
||||
- **type**: `imessage`
|
||||
- **terminology**: iMessage has "conversations." Each conversation is with a contact identified by phone number or email address. Group chats are also supported.
|
||||
- **how-to-find-id**: The platform ID is the contact's phone number (e.g. `+15551234567`) or email address. For group chats, the ID is assigned by iMessage internally.
|
||||
- **supports-threads**: no
|
||||
- **typical-use**: Interactive 1:1 chat — personal messaging
|
||||
- **default-isolation**: Same agent group if you're the only person messaging the bot across iMessage and other channels. Separate agent group if different contacts should have information isolation.
|
||||
|
||||
3
.claude/skills/add-imessage-v2/VERIFY.md
Normal file
3
.claude/skills/add-imessage-v2/VERIFY.md
Normal file
@@ -0,0 +1,3 @@
|
||||
# Verify iMessage Channel
|
||||
|
||||
Send an iMessage to the account running NanoClaw. The bot should respond within a few seconds.
|
||||
6
.claude/skills/add-linear-v2/REMOVE.md
Normal file
6
.claude/skills/add-linear-v2/REMOVE.md
Normal file
@@ -0,0 +1,6 @@
|
||||
# Remove Linear Channel
|
||||
|
||||
1. Comment out `import './linear.js'` in `src/channels/index.ts`
|
||||
2. Remove `LINEAR_API_KEY` and `LINEAR_WEBHOOK_SECRET` from `.env`
|
||||
3. `npm uninstall @chat-adapter/linear`
|
||||
4. Rebuild and restart
|
||||
@@ -3,39 +3,31 @@ name: add-linear-v2
|
||||
description: Add Linear channel integration to NanoClaw v2 via Chat SDK. Issue comment threads as conversations.
|
||||
---
|
||||
|
||||
# Add Linear Channel (v2)
|
||||
# Add Linear Channel
|
||||
|
||||
This skill adds Linear support to NanoClaw v2 using the Chat SDK bridge. The agent can participate in issue comment threads.
|
||||
Adds Linear support to NanoClaw v2 using the Chat SDK bridge. The agent participates in issue comment threads.
|
||||
|
||||
## Phase 1: Pre-flight
|
||||
## Pre-flight
|
||||
|
||||
Check if `src/channels/linear.ts` exists and the import is uncommented in `src/channels/index.ts`. If both are in place, skip to Phase 3.
|
||||
Check if `src/channels/linear.ts` exists and the import is uncommented in `src/channels/index.ts`. If both are in place, skip to Credentials.
|
||||
|
||||
## Phase 2: Apply Code Changes
|
||||
|
||||
### Install the adapter package
|
||||
## Install
|
||||
|
||||
```bash
|
||||
npm install @chat-adapter/linear
|
||||
```
|
||||
|
||||
### Enable the channel
|
||||
|
||||
Uncomment the Linear import in `src/channels/index.ts`:
|
||||
|
||||
```typescript
|
||||
import './linear.js';
|
||||
```
|
||||
|
||||
### Build
|
||||
|
||||
```bash
|
||||
npm run build
|
||||
```
|
||||
|
||||
## Phase 3: Setup
|
||||
|
||||
### Create Linear credentials
|
||||
## Credentials
|
||||
|
||||
> 1. Go to [Linear Settings > API](https://linear.app/settings/api)
|
||||
> 2. Create a **Personal API Key** (or use an OAuth application for team-wide access)
|
||||
@@ -57,21 +49,17 @@ LINEAR_WEBHOOK_SECRET=your-webhook-secret
|
||||
|
||||
Sync to container: `mkdir -p data/env && cp .env data/env/env`
|
||||
|
||||
### Build and restart
|
||||
## Next Steps
|
||||
|
||||
```bash
|
||||
npm run build
|
||||
launchctl kickstart -k gui/$(id -u)/com.nanoclaw # macOS
|
||||
# systemctl --user restart nanoclaw # Linux
|
||||
```
|
||||
If you're in the middle of `/setup`, return to the setup flow now.
|
||||
|
||||
## Phase 4: Verify
|
||||
Otherwise, run `/manage-channels` to wire this channel to an agent group.
|
||||
|
||||
> @mention the bot in a Linear issue comment. The bot should respond within a few seconds.
|
||||
## Channel Info
|
||||
|
||||
## Removal
|
||||
|
||||
1. Comment out `import './linear.js'` in `src/channels/index.ts`
|
||||
2. Remove `LINEAR_API_KEY` and `LINEAR_WEBHOOK_SECRET` from `.env`
|
||||
3. `npm uninstall @chat-adapter/linear`
|
||||
4. Rebuild and restart
|
||||
- **type**: `linear`
|
||||
- **terminology**: Linear has "teams" containing "issues." Each issue's comment thread is a separate conversation.
|
||||
- **how-to-find-id**: The platform ID is your team key (e.g. `ENG`). Find it in Linear under Settings > Teams. Each issue becomes its own thread automatically.
|
||||
- **supports-threads**: yes (issue comment threads are native conversations)
|
||||
- **typical-use**: Webhook/notification — the agent receives issue comment events and responds in threads
|
||||
- **default-isolation**: Typically shares a session with a chat channel (e.g. Slack) so the agent can discuss issues in the same context as team chat. Use a separate agent group if the Linear team tracks sensitive work.
|
||||
|
||||
3
.claude/skills/add-linear-v2/VERIFY.md
Normal file
3
.claude/skills/add-linear-v2/VERIFY.md
Normal file
@@ -0,0 +1,3 @@
|
||||
# Verify Linear Channel
|
||||
|
||||
@mention the bot in a Linear issue comment. The bot should respond within a few seconds.
|
||||
6
.claude/skills/add-matrix-v2/REMOVE.md
Normal file
6
.claude/skills/add-matrix-v2/REMOVE.md
Normal file
@@ -0,0 +1,6 @@
|
||||
# Remove Matrix Channel
|
||||
|
||||
1. Comment out `import './matrix.js'` in `src/channels/index.ts`
|
||||
2. Remove `MATRIX_BASE_URL`, `MATRIX_ACCESS_TOKEN`, `MATRIX_USER_ID`, `MATRIX_BOT_USERNAME` from `.env`
|
||||
3. `npm uninstall @beeper/chat-adapter-matrix`
|
||||
4. Rebuild and restart
|
||||
@@ -1,48 +1,40 @@
|
||||
---
|
||||
name: add-matrix-v2
|
||||
description: Add Matrix channel integration to NanoClaw v2 via Chat SDK. Works with any Matrix homeserver (Element, Beeper, etc.).
|
||||
description: Add Matrix channel integration to NanoClaw v2 via Chat SDK. Works with any Matrix homeserver.
|
||||
---
|
||||
|
||||
# Add Matrix Channel (v2)
|
||||
# Add Matrix Channel
|
||||
|
||||
This skill adds Matrix support to NanoClaw v2 using the Chat SDK bridge. Works with any Matrix homeserver.
|
||||
Adds Matrix support to NanoClaw v2 using the Chat SDK bridge.
|
||||
|
||||
## Phase 1: Pre-flight
|
||||
## Pre-flight
|
||||
|
||||
Check if `src/channels/matrix.ts` exists and the import is uncommented in `src/channels/index.ts`. If both are in place, skip to Phase 3.
|
||||
Check if `src/channels/matrix.ts` exists and the import is uncommented in `src/channels/index.ts`. If both are in place, skip to Credentials.
|
||||
|
||||
## Phase 2: Apply Code Changes
|
||||
|
||||
### Install the adapter package
|
||||
## Install
|
||||
|
||||
```bash
|
||||
npm install @beeper/chat-adapter-matrix
|
||||
```
|
||||
|
||||
### Enable the channel
|
||||
|
||||
Uncomment the Matrix import in `src/channels/index.ts`:
|
||||
|
||||
```typescript
|
||||
import './matrix.js';
|
||||
```
|
||||
|
||||
### Build
|
||||
|
||||
```bash
|
||||
npm run build
|
||||
```
|
||||
|
||||
## Phase 3: Setup
|
||||
## Credentials
|
||||
|
||||
### Create Matrix bot account
|
||||
|
||||
> 1. Register a bot account on your Matrix homeserver (e.g., via Element)
|
||||
> 2. Get the homeserver URL (e.g., `https://matrix.org` or your self-hosted URL)
|
||||
> 3. Get an access token:
|
||||
> - In Element: **Settings** > **Help & About** > **Access Token** (advanced)
|
||||
> - Or via API: `curl -XPOST 'https://matrix.org/_matrix/client/r0/login' -d '{"type":"m.login.password","user":"botuser","password":"..."}'`
|
||||
> 4. Note the bot's user ID (e.g., `@botuser:matrix.org`)
|
||||
1. Register a bot account on your Matrix homeserver (e.g., via Element)
|
||||
2. Get the homeserver URL (e.g., `https://matrix.org` or your self-hosted URL)
|
||||
3. Get an access token:
|
||||
- In Element: **Settings** > **Help & About** > **Access Token** (advanced)
|
||||
- Or via API: `curl -XPOST 'https://matrix.org/_matrix/client/r0/login' -d '{"type":"m.login.password","user":"botuser","password":"..."}'`
|
||||
4. Note the bot's user ID (e.g., `@botuser:matrix.org`)
|
||||
|
||||
### Configure environment
|
||||
|
||||
@@ -57,21 +49,17 @@ MATRIX_BOT_USERNAME=botuser
|
||||
|
||||
Sync to container: `mkdir -p data/env && cp .env data/env/env`
|
||||
|
||||
### Build and restart
|
||||
## Next Steps
|
||||
|
||||
```bash
|
||||
npm run build
|
||||
launchctl kickstart -k gui/$(id -u)/com.nanoclaw # macOS
|
||||
# systemctl --user restart nanoclaw # Linux
|
||||
```
|
||||
If you're in the middle of `/setup`, return to the setup flow now.
|
||||
|
||||
## Phase 4: Verify
|
||||
Otherwise, run `/manage-channels` to wire this channel to an agent group.
|
||||
|
||||
> Invite the bot to a Matrix room and send a message. The bot should respond within a few seconds.
|
||||
## Channel Info
|
||||
|
||||
## Removal
|
||||
|
||||
1. Comment out `import './matrix.js'` in `src/channels/index.ts`
|
||||
2. Remove `MATRIX_BASE_URL`, `MATRIX_ACCESS_TOKEN`, `MATRIX_USER_ID`, `MATRIX_BOT_USERNAME` from `.env`
|
||||
3. `npm uninstall @beeper/chat-adapter-matrix`
|
||||
4. Rebuild and restart
|
||||
- **type**: `matrix`
|
||||
- **terminology**: Matrix has "rooms." A room can be a group chat or a direct message. Rooms have internal IDs (like `!abc123:matrix.org`) and optional aliases (like `#general:matrix.org`).
|
||||
- **how-to-find-id**: In Element, click the room name > Settings > Advanced — the "Internal room ID" is the platform ID (starts with `!`). Or use a room alias like `#general:matrix.org`.
|
||||
- **supports-threads**: partial (some clients support threads, but not all — treat as no for reliability)
|
||||
- **typical-use**: Interactive chat — rooms or direct messages
|
||||
- **default-isolation**: Same agent group for rooms where you're the primary user. Separate agent group for rooms with different communities or sensitive contexts.
|
||||
|
||||
3
.claude/skills/add-matrix-v2/VERIFY.md
Normal file
3
.claude/skills/add-matrix-v2/VERIFY.md
Normal file
@@ -0,0 +1,3 @@
|
||||
# Verify Matrix Channel
|
||||
|
||||
Invite the bot to a Matrix room and send a message. The bot should respond within a few seconds.
|
||||
6
.claude/skills/add-resend-v2/REMOVE.md
Normal file
6
.claude/skills/add-resend-v2/REMOVE.md
Normal file
@@ -0,0 +1,6 @@
|
||||
# Remove Resend Email Channel
|
||||
|
||||
1. Comment out `import './resend.js'` in `src/channels/index.ts`
|
||||
2. Remove `RESEND_API_KEY`, `RESEND_FROM_ADDRESS`, `RESEND_FROM_NAME`, `RESEND_WEBHOOK_SECRET` from `.env`
|
||||
3. `npm uninstall @resend/chat-sdk-adapter`
|
||||
4. Rebuild and restart
|
||||
@@ -3,48 +3,42 @@ name: add-resend-v2
|
||||
description: Add Resend (email) channel integration to NanoClaw v2 via Chat SDK.
|
||||
---
|
||||
|
||||
# Add Resend Email Channel (v2)
|
||||
# Add Resend Email Channel
|
||||
|
||||
This skill adds email support via Resend to NanoClaw v2 using the Chat SDK bridge.
|
||||
Connect NanoClaw to email via Resend for async email conversations.
|
||||
|
||||
## Phase 1: Pre-flight
|
||||
## Pre-flight
|
||||
|
||||
Check if `src/channels/resend.ts` exists and the import is uncommented in `src/channels/index.ts`. If both are in place, skip to Phase 3.
|
||||
Check if `src/channels/resend.ts` exists and the import is uncommented in `src/channels/index.ts`. If both are in place, skip to Credentials.
|
||||
|
||||
## Phase 2: Apply Code Changes
|
||||
|
||||
### Install the adapter package
|
||||
## Install
|
||||
|
||||
```bash
|
||||
npm install @resend/chat-sdk-adapter
|
||||
```
|
||||
|
||||
### Enable the channel
|
||||
|
||||
Uncomment the Resend import in `src/channels/index.ts`:
|
||||
|
||||
```typescript
|
||||
import './resend.js';
|
||||
```
|
||||
|
||||
### Build
|
||||
Build:
|
||||
|
||||
```bash
|
||||
npm run build
|
||||
```
|
||||
|
||||
## Phase 3: Setup
|
||||
## Credentials
|
||||
|
||||
### Create Resend credentials
|
||||
|
||||
> 1. Go to [resend.com](https://resend.com) and create an account
|
||||
> 2. Add and verify your sending domain
|
||||
> 3. Go to **API Keys** and create a new key
|
||||
> 4. Set up a webhook:
|
||||
> - Go to **Webhooks** > **Add webhook**
|
||||
> - URL: `https://your-domain/webhook/resend`
|
||||
> - Events: select **email.received** (for inbound email)
|
||||
> - Copy the signing secret
|
||||
1. Go to [resend.com](https://resend.com) and create an account.
|
||||
2. Add and verify your sending domain.
|
||||
3. Go to **API Keys** and create a new key.
|
||||
4. Set up a webhook:
|
||||
- Go to **Webhooks** > **Add webhook**.
|
||||
- URL: `https://your-domain/webhook/resend`.
|
||||
- Events: select **email.received**.
|
||||
- Copy the signing secret.
|
||||
|
||||
### Configure environment
|
||||
|
||||
@@ -59,21 +53,17 @@ RESEND_WEBHOOK_SECRET=your-webhook-secret
|
||||
|
||||
Sync to container: `mkdir -p data/env && cp .env data/env/env`
|
||||
|
||||
### Build and restart
|
||||
## Next Steps
|
||||
|
||||
```bash
|
||||
npm run build
|
||||
launchctl kickstart -k gui/$(id -u)/com.nanoclaw # macOS
|
||||
# systemctl --user restart nanoclaw # Linux
|
||||
```
|
||||
If you're in the middle of `/setup`, return to the setup flow now.
|
||||
|
||||
## Phase 4: Verify
|
||||
Otherwise, run `/manage-channels` to wire this channel to an agent group.
|
||||
|
||||
> Send an email to the configured from address. The bot should respond via email within a few seconds.
|
||||
## Channel Info
|
||||
|
||||
## Removal
|
||||
|
||||
1. Comment out `import './resend.js'` in `src/channels/index.ts`
|
||||
2. Remove `RESEND_API_KEY`, `RESEND_FROM_ADDRESS`, `RESEND_FROM_NAME`, `RESEND_WEBHOOK_SECRET` from `.env`
|
||||
3. `npm uninstall @resend/chat-sdk-adapter`
|
||||
4. Rebuild and restart
|
||||
- **type**: `resend`
|
||||
- **terminology**: Resend handles email. Each email thread (identified by subject/In-Reply-To headers) is a separate conversation. The "from address" is the bot's identity.
|
||||
- **how-to-find-id**: The platform ID is the from email address (e.g. `bot@yourdomain.com`). Each sender's email thread becomes its own conversation.
|
||||
- **supports-threads**: yes (via email threading headers -- replies to the same thread stay together)
|
||||
- **typical-use**: Async communication -- email conversations with longer response expectations
|
||||
- **default-isolation**: Same agent group if you want your agent to handle email alongside other channels. Separate agent group if email contains sensitive correspondence that shouldn't be accessible from other channels.
|
||||
|
||||
3
.claude/skills/add-resend-v2/VERIFY.md
Normal file
3
.claude/skills/add-resend-v2/VERIFY.md
Normal file
@@ -0,0 +1,3 @@
|
||||
# Verify Resend Email Channel
|
||||
|
||||
Send an email to the configured from address. The bot should respond via email within a few seconds.
|
||||
6
.claude/skills/add-slack-v2/REMOVE.md
Normal file
6
.claude/skills/add-slack-v2/REMOVE.md
Normal file
@@ -0,0 +1,6 @@
|
||||
# Remove Slack
|
||||
|
||||
1. Comment out `import './slack.js'` in `src/channels/index.ts`
|
||||
2. Remove `SLACK_BOT_TOKEN` and `SLACK_SIGNING_SECRET` from `.env`
|
||||
3. `npm uninstall @chat-adapter/slack`
|
||||
4. Rebuild and restart
|
||||
@@ -3,15 +3,15 @@ name: add-slack-v2
|
||||
description: Add Slack channel integration to NanoClaw v2 via Chat SDK.
|
||||
---
|
||||
|
||||
# Add Slack Channel (v2)
|
||||
# Add Slack Channel
|
||||
|
||||
This skill adds Slack support to NanoClaw v2 using the Chat SDK bridge.
|
||||
Adds Slack support to NanoClaw v2 using the Chat SDK bridge.
|
||||
|
||||
## Phase 1: Pre-flight
|
||||
## Pre-flight
|
||||
|
||||
Check if `src/channels/slack.ts` exists and the import is uncommented in `src/channels/index.ts`. If both are in place, skip to Phase 3.
|
||||
Check if `src/channels/slack.ts` exists and the import is uncommented in `src/channels/index.ts`. If both are in place, skip to Credentials.
|
||||
|
||||
## Phase 2: Apply Code Changes
|
||||
## Install
|
||||
|
||||
### Install the adapter package
|
||||
|
||||
@@ -33,21 +33,19 @@ import './slack.js';
|
||||
npm run build
|
||||
```
|
||||
|
||||
## Phase 3: Setup
|
||||
## Credentials
|
||||
|
||||
### Create Slack App (if needed)
|
||||
### Create Slack App
|
||||
|
||||
If the user doesn't have a Slack app:
|
||||
|
||||
> 1. Go to [api.slack.com/apps](https://api.slack.com/apps) and click **Create New App** > **From scratch**
|
||||
> 2. Name it (e.g., "NanoClaw") and select your workspace
|
||||
> 3. Go to **OAuth & Permissions** and add Bot Token Scopes:
|
||||
> - `chat:write`, `channels:history`, `groups:history`, `im:history`, `channels:read`, `groups:read`, `users:read`, `reactions:write`
|
||||
> 4. Click **Install to Workspace** and copy the **Bot User OAuth Token** (`xoxb-...`)
|
||||
> 5. Go to **Basic Information** and copy the **Signing Secret**
|
||||
> 6. Go to **Event Subscriptions**, enable events, and subscribe to:
|
||||
> - `message.channels`, `message.groups`, `message.im`, `app_mention`
|
||||
> 7. Set the Request URL to your webhook endpoint (e.g., `https://your-domain/webhook/slack`)
|
||||
1. Go to [api.slack.com/apps](https://api.slack.com/apps) and click **Create New App** > **From scratch**
|
||||
2. Name it (e.g., "NanoClaw") and select your workspace
|
||||
3. Go to **OAuth & Permissions** and add Bot Token Scopes:
|
||||
- `chat:write`, `channels:history`, `groups:history`, `im:history`, `channels:read`, `groups:read`, `users:read`, `reactions:write`
|
||||
4. Click **Install to Workspace** and copy the **Bot User OAuth Token** (`xoxb-...`)
|
||||
5. Go to **Basic Information** and copy the **Signing Secret**
|
||||
6. Go to **Event Subscriptions**, enable events, and subscribe to:
|
||||
- `message.channels`, `message.groups`, `message.im`, `app_mention`
|
||||
7. Set the Request URL to your webhook endpoint (e.g., `https://your-domain/webhook/slack`)
|
||||
|
||||
### Configure environment
|
||||
|
||||
@@ -60,22 +58,17 @@ SLACK_SIGNING_SECRET=your-signing-secret
|
||||
|
||||
Sync to container: `mkdir -p data/env && cp .env data/env/env`
|
||||
|
||||
### Build and restart
|
||||
## Next Steps
|
||||
|
||||
```bash
|
||||
npm run build
|
||||
launchctl kickstart -k gui/$(id -u)/com.nanoclaw # macOS
|
||||
# systemctl --user restart nanoclaw # Linux
|
||||
```
|
||||
If you're in the middle of `/setup`, return to the setup flow now.
|
||||
|
||||
## Phase 4: Verify
|
||||
Otherwise, run `/manage-channels` to wire this channel to an agent group.
|
||||
|
||||
> Add the bot to a Slack channel, then send a message or @mention the bot.
|
||||
> The bot should respond within a few seconds.
|
||||
## Channel Info
|
||||
|
||||
## Removal
|
||||
|
||||
1. Comment out `import './slack.js'` in `src/channels/index.ts`
|
||||
2. Remove `SLACK_BOT_TOKEN` and `SLACK_SIGNING_SECRET` from `.env`
|
||||
3. `npm uninstall @chat-adapter/slack`
|
||||
4. Rebuild and restart
|
||||
- **type**: `slack`
|
||||
- **terminology**: Slack has "workspaces" containing "channels." Channels can be public (#general) or private. The bot can also receive direct messages.
|
||||
- **how-to-find-id**: Right-click a channel name > "View channel details" — the Channel ID is at the bottom (starts with C). Or copy the channel link — the ID is the last segment of the URL.
|
||||
- **supports-threads**: yes
|
||||
- **typical-use**: Interactive chat — team channels or direct messages
|
||||
- **default-isolation**: Same agent group for channels where you're the primary user. Separate agent group for channels with different teams or sensitive contexts.
|
||||
|
||||
3
.claude/skills/add-slack-v2/VERIFY.md
Normal file
3
.claude/skills/add-slack-v2/VERIFY.md
Normal file
@@ -0,0 +1,3 @@
|
||||
# Verify Slack
|
||||
|
||||
Add the bot to a Slack channel, then send a message or @mention the bot. The bot should respond within a few seconds.
|
||||
6
.claude/skills/add-teams-v2/REMOVE.md
Normal file
6
.claude/skills/add-teams-v2/REMOVE.md
Normal file
@@ -0,0 +1,6 @@
|
||||
# Remove Microsoft Teams Channel
|
||||
|
||||
1. Comment out `import './teams.js'` in `src/channels/index.ts`
|
||||
2. Remove `TEAMS_APP_ID` and `TEAMS_APP_PASSWORD` from `.env`
|
||||
3. `npm uninstall @chat-adapter/teams`
|
||||
4. Rebuild and restart
|
||||
@@ -3,46 +3,38 @@ name: add-teams-v2
|
||||
description: Add Microsoft Teams channel integration to NanoClaw v2 via Chat SDK.
|
||||
---
|
||||
|
||||
# Add Microsoft Teams Channel (v2)
|
||||
# Add Microsoft Teams Channel
|
||||
|
||||
This skill adds Microsoft Teams support to NanoClaw v2 using the Chat SDK bridge.
|
||||
Connect NanoClaw to Microsoft Teams for interactive chat in team channels and direct messages.
|
||||
|
||||
## Phase 1: Pre-flight
|
||||
## Pre-flight
|
||||
|
||||
Check if `src/channels/teams.ts` exists and the import is uncommented in `src/channels/index.ts`. If both are in place, skip to Phase 3.
|
||||
Check if `src/channels/teams.ts` exists and the import is uncommented in `src/channels/index.ts`. If both are in place, skip to Credentials.
|
||||
|
||||
## Phase 2: Apply Code Changes
|
||||
|
||||
### Install the adapter package
|
||||
## Install
|
||||
|
||||
```bash
|
||||
npm install @chat-adapter/teams
|
||||
```
|
||||
|
||||
### Enable the channel
|
||||
|
||||
Uncomment the Teams import in `src/channels/index.ts`:
|
||||
|
||||
```typescript
|
||||
import './teams.js';
|
||||
```
|
||||
|
||||
### Build
|
||||
Build:
|
||||
|
||||
```bash
|
||||
npm run build
|
||||
```
|
||||
|
||||
## Phase 3: Setup
|
||||
## Credentials
|
||||
|
||||
### Create Teams Bot
|
||||
|
||||
> 1. Go to [Azure Portal](https://portal.azure.com) > **Azure Bot** > **Create**
|
||||
> 2. Fill in the bot details and create
|
||||
> 3. Go to **Configuration**:
|
||||
> - Messaging endpoint: `https://your-domain/webhook/teams`
|
||||
> 4. Go to **Channels** > add **Microsoft Teams**
|
||||
> 5. Note the **Microsoft App ID** and **Password** (from the bot's Azure AD app registration)
|
||||
1. Go to [Azure Portal](https://portal.azure.com) > **Azure Bot** > **Create**.
|
||||
2. Configure the messaging endpoint: `https://your-domain/webhook/teams`.
|
||||
3. Add the **Microsoft Teams** channel.
|
||||
4. Note the **App ID** and **Password** from the Azure AD app registration.
|
||||
|
||||
### Configure environment
|
||||
|
||||
@@ -55,21 +47,17 @@ TEAMS_APP_PASSWORD=your-app-password
|
||||
|
||||
Sync to container: `mkdir -p data/env && cp .env data/env/env`
|
||||
|
||||
### Build and restart
|
||||
## Next Steps
|
||||
|
||||
```bash
|
||||
npm run build
|
||||
launchctl kickstart -k gui/$(id -u)/com.nanoclaw # macOS
|
||||
# systemctl --user restart nanoclaw # Linux
|
||||
```
|
||||
If you're in the middle of `/setup`, return to the setup flow now.
|
||||
|
||||
## Phase 4: Verify
|
||||
Otherwise, run `/manage-channels` to wire this channel to an agent group.
|
||||
|
||||
> Add the bot to a Teams channel or send it a direct message. The bot should respond within a few seconds.
|
||||
## Channel Info
|
||||
|
||||
## Removal
|
||||
|
||||
1. Comment out `import './teams.js'` in `src/channels/index.ts`
|
||||
2. Remove `TEAMS_APP_ID` and `TEAMS_APP_PASSWORD` from `.env`
|
||||
3. `npm uninstall @chat-adapter/teams`
|
||||
4. Rebuild and restart
|
||||
- **type**: `teams`
|
||||
- **terminology**: Teams has "teams" containing "channels." The bot can also receive direct messages. Teams channels can have threaded replies.
|
||||
- **how-to-find-id**: Right-click a channel in Teams > "Get link to channel" -- the channel ID is in the URL. Or use the Microsoft Graph API to list channels.
|
||||
- **supports-threads**: yes
|
||||
- **typical-use**: Interactive chat -- team channels or direct messages
|
||||
- **default-isolation**: Same agent group for channels where you're the primary user. Separate agent group for channels with different teams or where different members have different information boundaries.
|
||||
|
||||
3
.claude/skills/add-teams-v2/VERIFY.md
Normal file
3
.claude/skills/add-teams-v2/VERIFY.md
Normal file
@@ -0,0 +1,3 @@
|
||||
# Verify Microsoft Teams Channel
|
||||
|
||||
Add the bot to a Teams channel or send it a direct message. The bot should respond within a few seconds.
|
||||
6
.claude/skills/add-telegram-v2/REMOVE.md
Normal file
6
.claude/skills/add-telegram-v2/REMOVE.md
Normal file
@@ -0,0 +1,6 @@
|
||||
# Remove Telegram
|
||||
|
||||
1. Comment out `import './telegram.js'` in `src/channels/index.ts`
|
||||
2. Remove `TELEGRAM_BOT_TOKEN` from `.env`
|
||||
3. `npm uninstall @chat-adapter/telegram`
|
||||
4. Rebuild and restart
|
||||
@@ -3,15 +3,15 @@ name: add-telegram-v2
|
||||
description: Add Telegram channel integration to NanoClaw v2 via Chat SDK.
|
||||
---
|
||||
|
||||
# Add Telegram Channel (v2)
|
||||
# Add Telegram Channel
|
||||
|
||||
This skill adds Telegram support to NanoClaw v2 using the Chat SDK bridge.
|
||||
Adds Telegram bot support to NanoClaw v2 using the Chat SDK bridge.
|
||||
|
||||
## Phase 1: Pre-flight
|
||||
## Pre-flight
|
||||
|
||||
Check if `src/channels/telegram.ts` exists and the import is uncommented in `src/channels/index.ts`. If both are in place, skip to Phase 3.
|
||||
Check if `src/channels/telegram.ts` exists and the import is uncommented in `src/channels/index.ts`. If both are in place, skip to Credentials.
|
||||
|
||||
## Phase 2: Apply Code Changes
|
||||
## Install
|
||||
|
||||
### Install the adapter package
|
||||
|
||||
@@ -33,22 +33,20 @@ import './telegram.js';
|
||||
npm run build
|
||||
```
|
||||
|
||||
## Phase 3: Setup
|
||||
## Credentials
|
||||
|
||||
### Create Telegram Bot (if needed)
|
||||
### Create Telegram Bot
|
||||
|
||||
> 1. Open Telegram and search for `@BotFather`
|
||||
> 2. Send `/newbot` and follow the prompts:
|
||||
> - Bot name: Something friendly (e.g., "NanoClaw Assistant")
|
||||
> - Bot username: Must end with "bot" (e.g., "nanoclaw_bot")
|
||||
> 3. Copy the bot token (looks like `123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11`)
|
||||
1. Open Telegram and search for `@BotFather`
|
||||
2. Send `/newbot` and follow the prompts:
|
||||
- Bot name: Something friendly (e.g., "NanoClaw Assistant")
|
||||
- Bot username: Must end with "bot" (e.g., "nanoclaw_bot")
|
||||
3. Copy the bot token (looks like `123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11`)
|
||||
|
||||
### Disable Group Privacy (for group chats)
|
||||
**Important for group chats**: By default, Telegram bots only see @mentions and commands in groups. To let the bot see all messages:
|
||||
|
||||
> **Important for group chats**: By default, Telegram bots only see @mentions and commands in groups. To let the bot see all messages:
|
||||
>
|
||||
> 1. Open `@BotFather` > `/mybots` > select your bot
|
||||
> 2. **Bot Settings** > **Group Privacy** > **Turn off**
|
||||
1. Open `@BotFather` > `/mybots` > select your bot
|
||||
2. **Bot Settings** > **Group Privacy** > **Turn off**
|
||||
|
||||
### Configure environment
|
||||
|
||||
@@ -60,23 +58,17 @@ TELEGRAM_BOT_TOKEN=your-bot-token
|
||||
|
||||
Sync to container: `mkdir -p data/env && cp .env data/env/env`
|
||||
|
||||
### Build and restart
|
||||
## Next Steps
|
||||
|
||||
```bash
|
||||
npm run build
|
||||
launchctl kickstart -k gui/$(id -u)/com.nanoclaw # macOS
|
||||
# systemctl --user restart nanoclaw # Linux
|
||||
```
|
||||
If you're in the middle of `/setup`, return to the setup flow now.
|
||||
|
||||
## Phase 4: Verify
|
||||
Otherwise, run `/manage-channels` to wire this channel to an agent group.
|
||||
|
||||
> Send a message to your bot in Telegram (search for its username).
|
||||
> For groups: add the bot to a group and send a message.
|
||||
> The bot should respond within a few seconds.
|
||||
## Channel Info
|
||||
|
||||
## Removal
|
||||
|
||||
1. Comment out `import './telegram.js'` in `src/channels/index.ts`
|
||||
2. Remove `TELEGRAM_BOT_TOKEN` from `.env`
|
||||
3. `npm uninstall @chat-adapter/telegram`
|
||||
4. Rebuild and restart
|
||||
- **type**: `telegram`
|
||||
- **terminology**: Telegram calls them "groups" and "chats." A "group" has multiple members; a "chat" is a 1:1 conversation with the bot.
|
||||
- **how-to-find-id**: Send a message in the group/chat, then visit `https://api.telegram.org/bot<TOKEN>/getUpdates` — the `chat.id` field is the platform ID. Group IDs are negative numbers.
|
||||
- **supports-threads**: no
|
||||
- **typical-use**: Interactive chat — direct messages or small groups
|
||||
- **default-isolation**: Same agent group if you're the only participant across multiple chats. Separate agent group if different people are in different groups.
|
||||
|
||||
3
.claude/skills/add-telegram-v2/VERIFY.md
Normal file
3
.claude/skills/add-telegram-v2/VERIFY.md
Normal file
@@ -0,0 +1,3 @@
|
||||
# Verify Telegram
|
||||
|
||||
Send a message to your bot in Telegram (search for its username), or add the bot to a group and send a message there. The bot should respond within a few seconds.
|
||||
6
.claude/skills/add-webex-v2/REMOVE.md
Normal file
6
.claude/skills/add-webex-v2/REMOVE.md
Normal file
@@ -0,0 +1,6 @@
|
||||
# Remove Webex Channel
|
||||
|
||||
1. Comment out `import './webex.js'` in `src/channels/index.ts`
|
||||
2. Remove `WEBEX_BOT_TOKEN` and `WEBEX_WEBHOOK_SECRET` from `.env`
|
||||
3. `npm uninstall @bitbasti/chat-adapter-webex`
|
||||
4. Rebuild and restart
|
||||
@@ -3,46 +3,37 @@ name: add-webex-v2
|
||||
description: Add Webex channel integration to NanoClaw v2 via Chat SDK.
|
||||
---
|
||||
|
||||
# Add Webex Channel (v2)
|
||||
# Add Webex Channel
|
||||
|
||||
This skill adds Cisco Webex support to NanoClaw v2 using the Chat SDK bridge.
|
||||
Adds Cisco Webex support to NanoClaw v2 using the Chat SDK bridge.
|
||||
|
||||
## Phase 1: Pre-flight
|
||||
## Pre-flight
|
||||
|
||||
Check if `src/channels/webex.ts` exists and the import is uncommented in `src/channels/index.ts`. If both are in place, skip to Phase 3.
|
||||
Check if `src/channels/webex.ts` exists and the import is uncommented in `src/channels/index.ts`. If both are in place, skip to Credentials.
|
||||
|
||||
## Phase 2: Apply Code Changes
|
||||
|
||||
### Install the adapter package
|
||||
## Install
|
||||
|
||||
```bash
|
||||
npm install @bitbasti/chat-adapter-webex
|
||||
```
|
||||
|
||||
### Enable the channel
|
||||
|
||||
Uncomment the Webex import in `src/channels/index.ts`:
|
||||
|
||||
```typescript
|
||||
import './webex.js';
|
||||
```
|
||||
|
||||
### Build
|
||||
|
||||
```bash
|
||||
npm run build
|
||||
```
|
||||
|
||||
## Phase 3: Setup
|
||||
## Credentials
|
||||
|
||||
### Create Webex Bot
|
||||
|
||||
> 1. Go to [developer.webex.com](https://developer.webex.com/my-apps/new/bot)
|
||||
> 2. Create a new bot and copy the **Bot Access Token**
|
||||
> 3. Set up a webhook:
|
||||
> - Use the Webex API to create a webhook pointing to `https://your-domain/webhook/webex`
|
||||
> - Or use the Webex Developer Portal
|
||||
> - Set a webhook secret for signature verification
|
||||
1. Go to [developer.webex.com](https://developer.webex.com/my-apps/new/bot) and create a new bot
|
||||
2. Copy the **Bot Access Token**
|
||||
3. Set up a webhook:
|
||||
- Use the Webex API or Developer Portal to create a webhook pointing to `https://your-domain/webhook/webex`
|
||||
- Set a webhook secret for signature verification
|
||||
|
||||
### Configure environment
|
||||
|
||||
@@ -55,21 +46,17 @@ WEBEX_WEBHOOK_SECRET=your-webhook-secret
|
||||
|
||||
Sync to container: `mkdir -p data/env && cp .env data/env/env`
|
||||
|
||||
### Build and restart
|
||||
## Next Steps
|
||||
|
||||
```bash
|
||||
npm run build
|
||||
launchctl kickstart -k gui/$(id -u)/com.nanoclaw # macOS
|
||||
# systemctl --user restart nanoclaw # Linux
|
||||
```
|
||||
If you're in the middle of `/setup`, return to the setup flow now.
|
||||
|
||||
## Phase 4: Verify
|
||||
Otherwise, run `/manage-channels` to wire this channel to an agent group.
|
||||
|
||||
> Add the bot to a Webex space or send it a direct message. The bot should respond within a few seconds.
|
||||
## Channel Info
|
||||
|
||||
## Removal
|
||||
|
||||
1. Comment out `import './webex.js'` in `src/channels/index.ts`
|
||||
2. Remove `WEBEX_BOT_TOKEN` and `WEBEX_WEBHOOK_SECRET` from `.env`
|
||||
3. `npm uninstall @bitbasti/chat-adapter-webex`
|
||||
4. Rebuild and restart
|
||||
- **type**: `webex`
|
||||
- **terminology**: Webex has "spaces." A space can be a group conversation or a 1:1 direct message with the bot.
|
||||
- **how-to-find-id**: Open the space in Webex, click the space name > Settings — the Space ID is listed there. Or use the Webex API (`GET /rooms`) to list spaces and their IDs.
|
||||
- **supports-threads**: yes
|
||||
- **typical-use**: Interactive chat — team spaces or direct messages
|
||||
- **default-isolation**: Same agent group for spaces where you're the primary user. Separate agent group for spaces with different teams or sensitive information.
|
||||
|
||||
3
.claude/skills/add-webex-v2/VERIFY.md
Normal file
3
.claude/skills/add-webex-v2/VERIFY.md
Normal file
@@ -0,0 +1,3 @@
|
||||
# Verify Webex Channel
|
||||
|
||||
Add the bot to a Webex space or send it a direct message. The bot should respond within a few seconds.
|
||||
6
.claude/skills/add-whatsapp-cloud-v2/REMOVE.md
Normal file
6
.claude/skills/add-whatsapp-cloud-v2/REMOVE.md
Normal file
@@ -0,0 +1,6 @@
|
||||
# Remove WhatsApp Cloud API Channel
|
||||
|
||||
1. Comment out `import './whatsapp-cloud.js'` in `src/channels/index.ts`
|
||||
2. Remove `WHATSAPP_ACCESS_TOKEN`, `WHATSAPP_PHONE_NUMBER_ID`, `WHATSAPP_APP_SECRET`, `WHATSAPP_VERIFY_TOKEN` from `.env`
|
||||
3. `npm uninstall @chat-adapter/whatsapp`
|
||||
4. Rebuild and restart
|
||||
@@ -1,52 +1,46 @@
|
||||
---
|
||||
name: add-whatsapp-cloud-v2
|
||||
description: Add WhatsApp Business Cloud API channel to NanoClaw v2 via Chat SDK. Official Meta API (not Baileys).
|
||||
description: Add WhatsApp Business Cloud API channel to NanoClaw v2 via Chat SDK. Official Meta API.
|
||||
---
|
||||
|
||||
# Add WhatsApp Cloud API Channel (v2)
|
||||
# Add WhatsApp Cloud API Channel
|
||||
|
||||
This skill adds WhatsApp support via the official Meta WhatsApp Business Cloud API. This is different from the Baileys-based WhatsApp adapter (which uses WhatsApp Web protocol).
|
||||
Connect NanoClaw to WhatsApp via the official Meta WhatsApp Business Cloud API.
|
||||
|
||||
## Phase 1: Pre-flight
|
||||
## Pre-flight
|
||||
|
||||
Check if `src/channels/whatsapp-cloud.ts` exists and the import is uncommented in `src/channels/index.ts`. If both are in place, skip to Phase 3.
|
||||
Check if `src/channels/whatsapp-cloud.ts` exists and the import is uncommented in `src/channels/index.ts`. If both are in place, skip to Credentials.
|
||||
|
||||
## Phase 2: Apply Code Changes
|
||||
|
||||
### Install the adapter package
|
||||
## Install
|
||||
|
||||
```bash
|
||||
npm install @chat-adapter/whatsapp
|
||||
```
|
||||
|
||||
### Enable the channel
|
||||
|
||||
Uncomment the WhatsApp Cloud API import in `src/channels/index.ts`:
|
||||
|
||||
```typescript
|
||||
import './whatsapp-cloud.js';
|
||||
```
|
||||
|
||||
### Build
|
||||
Build:
|
||||
|
||||
```bash
|
||||
npm run build
|
||||
```
|
||||
|
||||
## Phase 3: Setup
|
||||
## Credentials
|
||||
|
||||
### Create WhatsApp Business App
|
||||
|
||||
> 1. Go to [Meta for Developers](https://developers.facebook.com/apps/) and create an app (type: Business)
|
||||
> 2. Add the **WhatsApp** product
|
||||
> 3. Go to **WhatsApp** > **API Setup**:
|
||||
> - Note the **Phone Number ID** (not the phone number itself)
|
||||
> - Generate a **permanent System User access token** with `whatsapp_business_messaging` permission
|
||||
> 4. Go to **WhatsApp** > **Configuration**:
|
||||
> - Set webhook URL: `https://your-domain/webhook/whatsapp`
|
||||
> - Set a **Verify Token** (any random string you choose)
|
||||
> - Subscribe to webhook fields: `messages`
|
||||
> 5. Copy the **App Secret** from **Settings** > **Basic**
|
||||
1. Go to [Meta for Developers](https://developers.facebook.com/apps/) and create an app (type: Business).
|
||||
2. Add the **WhatsApp** product.
|
||||
3. Go to **WhatsApp** > **API Setup**:
|
||||
- Note the **Phone Number ID** (not the phone number itself).
|
||||
- Generate a **permanent System User access token** with `whatsapp_business_messaging` permission.
|
||||
4. Go to **WhatsApp** > **Configuration**:
|
||||
- Set webhook URL: `https://your-domain/webhook/whatsapp`.
|
||||
- Set a **Verify Token** (any random string you choose).
|
||||
- Subscribe to webhook fields: `messages`.
|
||||
5. Copy the **App Secret** from **Settings** > **Basic**.
|
||||
|
||||
### Configure environment
|
||||
|
||||
@@ -61,22 +55,17 @@ WHATSAPP_VERIFY_TOKEN=your-verify-token
|
||||
|
||||
Sync to container: `mkdir -p data/env && cp .env data/env/env`
|
||||
|
||||
### Build and restart
|
||||
## Next Steps
|
||||
|
||||
```bash
|
||||
npm run build
|
||||
launchctl kickstart -k gui/$(id -u)/com.nanoclaw # macOS
|
||||
# systemctl --user restart nanoclaw # Linux
|
||||
```
|
||||
If you're in the middle of `/setup`, return to the setup flow now.
|
||||
|
||||
## Phase 4: Verify
|
||||
Otherwise, run `/manage-channels` to wire this channel to an agent group.
|
||||
|
||||
> Send a message to your WhatsApp Business number. The bot should respond within a few seconds.
|
||||
> Note: WhatsApp Cloud API only supports 1:1 DMs, not group chats.
|
||||
## Channel Info
|
||||
|
||||
## Removal
|
||||
|
||||
1. Comment out `import './whatsapp-cloud.js'` in `src/channels/index.ts`
|
||||
2. Remove `WHATSAPP_ACCESS_TOKEN`, `WHATSAPP_PHONE_NUMBER_ID`, `WHATSAPP_APP_SECRET`, `WHATSAPP_VERIFY_TOKEN` from `.env`
|
||||
3. `npm uninstall @chat-adapter/whatsapp`
|
||||
4. Rebuild and restart
|
||||
- **type**: `whatsapp-cloud`
|
||||
- **terminology**: WhatsApp Cloud API supports 1:1 conversations only (no group chats). Each conversation is with a phone number.
|
||||
- **how-to-find-id**: The platform ID is the Phone Number ID from the Meta Business dashboard (not the phone number itself). Find it under WhatsApp > API Setup.
|
||||
- **supports-threads**: no
|
||||
- **typical-use**: Interactive 1:1 chat -- direct messages only
|
||||
- **default-isolation**: Same agent group if you're the only person messaging the bot. Each additional person who messages gets their own conversation automatically, but they share the agent's workspace and memory -- use a separate agent group if you need information isolation between different contacts.
|
||||
|
||||
3
.claude/skills/add-whatsapp-cloud-v2/VERIFY.md
Normal file
3
.claude/skills/add-whatsapp-cloud-v2/VERIFY.md
Normal file
@@ -0,0 +1,3 @@
|
||||
# Verify WhatsApp Cloud API Channel
|
||||
|
||||
Send a message to your WhatsApp Business number. The bot should respond within a few seconds. Note: WhatsApp Cloud API only supports 1:1 DMs, not group chats.
|
||||
81
.claude/skills/manage-channels/SKILL.md
Normal file
81
.claude/skills/manage-channels/SKILL.md
Normal file
@@ -0,0 +1,81 @@
|
||||
---
|
||||
name: manage-channels
|
||||
description: Wire channels to agent groups, manage isolation levels, add new channel groups. Use after adding a channel, during setup, or standalone to reconfigure.
|
||||
---
|
||||
|
||||
# Manage Channels
|
||||
|
||||
Wire messaging channels to agent groups. See `docs/v2-isolation-model.md` for the full isolation model.
|
||||
|
||||
## Assess Current State
|
||||
|
||||
Read the v2 central DB (`data/v2.db`) — query `agent_groups`, `messaging_groups`, and `messaging_group_agents` tables. Also check `.env` for channel tokens and `src/channels/index.ts` for uncommented imports.
|
||||
|
||||
Categorize channels as: **wired** (has DB entities), **configured but unwired** (has credentials + barrel import, no DB entities), or **not configured**.
|
||||
|
||||
## First Channel (No Agent Groups Exist)
|
||||
|
||||
1. Ask the assistant name (default: project name or "Andy")
|
||||
2. Ask which channel is the primary/admin channel
|
||||
3. Ask for the platform ID — read the channel's SKILL.md `## Channel Info` > `how-to-find-id` to guide them
|
||||
4. Register:
|
||||
|
||||
```bash
|
||||
npx tsx setup/index.ts --step register -- \
|
||||
--platform-id "<id>" --name "<name>" --folder "main" \
|
||||
--channel "<type>" --is-main --no-trigger-required \
|
||||
--assistant-name "<name>" --session-mode "shared"
|
||||
```
|
||||
|
||||
5. Continue to "Wire New Channel" for any remaining configured channels.
|
||||
|
||||
## Wire New Channel
|
||||
|
||||
For each unwired channel:
|
||||
|
||||
1. Read its SKILL.md `## Channel Info` for terminology, how-to-find-id, typical-use, and default-isolation
|
||||
2. Ask for the platform ID using the platform's terminology
|
||||
3. Ask the isolation question (see below)
|
||||
4. Register with the appropriate flags
|
||||
|
||||
### Isolation Question
|
||||
|
||||
Present a multiple-choice with a contextual recommendation. The three options:
|
||||
|
||||
- **Same conversation** (`--session-mode "agent-shared"` + existing folder) — all messages land in one session. Recommend for webhook + chat combos (GitHub + Slack).
|
||||
- **Same agent, separate conversations** (`--session-mode "shared"` + existing folder) — shared workspace/memory, independent threads. Recommend for same user across platforms.
|
||||
- **Separate agent** (new `--folder`) — full isolation. Recommend when different people are involved.
|
||||
|
||||
Use the channel's `typical-use` and `default-isolation` fields to pick the recommendation. Offer to explain more if the user is unsure — reference `docs/v2-isolation-model.md` for the detailed explanation.
|
||||
|
||||
### Register Command
|
||||
|
||||
```bash
|
||||
npx tsx setup/index.ts --step register -- \
|
||||
--platform-id "<id>" --name "<name>" \
|
||||
--folder "<folder>" --channel "<type>" \
|
||||
--session-mode "<shared|agent-shared>" \
|
||||
--assistant-name "<name>"
|
||||
```
|
||||
|
||||
For separate agents, also ask for a folder name and optionally a different assistant name.
|
||||
|
||||
## Add Channel Group
|
||||
|
||||
When adding another group/chat on an already-configured platform (e.g. a second Telegram group):
|
||||
|
||||
1. Read the channel's SKILL.md `## Channel Info` for terminology and how-to-find-id
|
||||
2. Ask for the new group/chat ID
|
||||
3. Ask the isolation question
|
||||
4. Register — no package or credential changes needed
|
||||
|
||||
## Change Wiring
|
||||
|
||||
1. Show current wiring
|
||||
2. Ask which channel to move and to which agent group
|
||||
3. Delete the old `messaging_group_agents` entry, create a new one
|
||||
4. Note: existing sessions stay with the old agent group; new messages route to the new one
|
||||
|
||||
## Show Configuration
|
||||
|
||||
Display a readable summary showing agent groups with their wired channels, configured-but-unwired channels, and unconfigured channels.
|
||||
@@ -260,7 +260,7 @@ AskUserQuestion (multiSelect): Which messaging channels do you want to enable?
|
||||
|
||||
For each selected channel, invoke its skill:
|
||||
|
||||
- **Discord:** Invoke `/add-discord`
|
||||
- **Discord:** Invoke `/add-discord-v2`
|
||||
- **Slack:** Invoke `/add-slack-v2`
|
||||
- **Telegram:** Invoke `/add-telegram-v2`
|
||||
- **GitHub:** Invoke `/add-github-v2`
|
||||
@@ -286,7 +286,18 @@ Each skill will:
|
||||
npm install && npm run build
|
||||
```
|
||||
|
||||
If the build fails, read the error output and fix it (usually a missing dependency). Then continue to step 6.
|
||||
If the build fails, read the error output and fix it (usually a missing dependency). Then continue to step 5a.
|
||||
|
||||
## 5a. Wire Channels to Agent Groups
|
||||
|
||||
Invoke `/manage-channels` to wire the installed channels to agent groups. This step:
|
||||
1. Creates the agent group(s) and assigns a name to the assistant
|
||||
2. Asks for each channel's platform-specific ID (guided by channel-specific instructions)
|
||||
3. Decides the isolation level — whether channels share an agent, session, or are fully separate
|
||||
|
||||
The `/manage-channels` skill reads each channel's `## Channel Info` section from its SKILL.md for platform-specific guidance (terminology, how to find IDs, recommended isolation).
|
||||
|
||||
**This step is required.** Without it, channels are installed but not wired — messages will be silently dropped because the router has no agent group to route to.
|
||||
|
||||
## 6. Mount Allowlist
|
||||
|
||||
@@ -334,7 +345,7 @@ Run `npx tsx setup/index.ts --step verify` and parse the status block.
|
||||
- SERVICE=not_found → re-run step 7
|
||||
- CREDENTIALS=missing → re-run step 4 (Docker: check `onecli secrets list`; Apple Container: check `.env` for credentials)
|
||||
- CHANNEL_AUTH shows `not_found` for any channel → re-invoke that channel's skill (e.g. `/add-telegram`)
|
||||
- REGISTERED_GROUPS=0 → re-invoke the channel skills from step 5
|
||||
- REGISTERED_GROUPS=0 → re-invoke `/manage-channels` from step 5a
|
||||
- MOUNT_ALLOWLIST=missing → `npx tsx setup/index.ts --step mounts -- --empty`
|
||||
|
||||
Tell user to test: send a message in their registered chat. Show: `tail -f logs/nanoclaw.log`
|
||||
|
||||
Reference in New Issue
Block a user