b47fcdfc14
- messaging/channels-setup.md: comprehensive guide covering all 3 channels (Telegram, Discord, iMessage), bun install, plugin setup, session persistence workarounds, and enterprise admin settings - messaging/imessage-setup.md: macOS-specific iMessage setup with Full Disk Access, /imessage access allow, and known quirks - messaging/README.md: rewritten with 3-way distinction table (Channels=event-based, Dispatch=message-based, RC=direct control) - examples/12: expanded from 2 options to 3 with clear trigger model - feature-map.md: row 9 updated to include iMessage - README.md: session persistence warning added as top-level section Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
106 lines
3.5 KiB
Markdown
106 lines
3.5 KiB
Markdown
# Channels Setup Guide
|
|
|
|
Channels let external chat apps push messages into a running
|
|
Claude Code session. Your agent reacts to messages as if you
|
|
typed them locally. This is Claude Code's answer to OpenClaw's
|
|
15+ native messaging integrations.
|
|
|
|
## Supported channels (March 2026)
|
|
|
|
| Channel | Plugin | Platform requirement |
|
|
|---------|--------|---------------------|
|
|
| Telegram | `@anthropic-ai/claude-code-telegram` | Any OS |
|
|
| Discord | `@anthropic-ai/claude-code-discord` | Any OS |
|
|
| iMessage | `@anthropic-ai/claude-code-imessage` | macOS only |
|
|
|
|
## Prerequisites
|
|
|
|
1. **Bun** (JavaScript runtime, required for channel plugins):
|
|
```bash
|
|
curl -fsSL https://bun.sh/install | bash
|
|
```
|
|
|
|
2. **Full Disk Access** (macOS, required for iMessage):
|
|
System Settings > Privacy & Security > Full Disk Access >
|
|
Add your terminal app (Terminal.app or VS Code)
|
|
|
|
3. **Claude Code** v2.1.80+ (channels were introduced here)
|
|
|
|
## Install a channel plugin
|
|
|
|
```bash
|
|
# In a Claude Code session, run:
|
|
/install @anthropic-ai/claude-code-telegram
|
|
# or
|
|
/install @anthropic-ai/claude-code-discord
|
|
# or
|
|
/install @anthropic-ai/claude-code-imessage
|
|
```
|
|
|
|
Verify with `/plugins` to see installed plugins.
|
|
|
|
## Launch Claude Code in channel mode
|
|
|
|
```bash
|
|
claude --channels
|
|
```
|
|
|
|
You should see: `Listening for channel messages from plugin [channel-name]`
|
|
|
|
Claude Code now receives messages from the configured channel
|
|
and responds through it. Every tool, skill, and agent you have
|
|
configured works exactly as if you were typing locally.
|
|
|
|
## Permission approval from your phone
|
|
|
|
When Claude Code needs to run a sensitive action, it sends a
|
|
permission request through the channel. You can reply "yes" or
|
|
"no" from your phone to approve or deny.
|
|
|
|
To avoid constant prompts, launch with Auto Mode:
|
|
```bash
|
|
claude --channels --enable-auto-mode
|
|
```
|
|
|
|
## The critical limitation: session persistence
|
|
|
|
**If the Claude Code session closes, the channel stops working.**
|
|
Messages sent to the channel will not reach Claude Code until
|
|
you start a new session with `--channels`.
|
|
|
|
This is the biggest practical difference from OpenClaw, which
|
|
runs as a daemon and stays alive indefinitely.
|
|
|
|
### Workarounds for always-on
|
|
|
|
| Approach | How | Reliability |
|
|
|----------|-----|-------------|
|
|
| tmux/screen | `tmux new -s claude && claude --channels` | Good, survives SSH disconnect |
|
|
| Mac Mini | Dedicated machine, disable sleep | Very good |
|
|
| macOS VPS | Cloud Mac (e.g., MacStadium, AWS EC2 Mac) | Best, but expensive |
|
|
| /schedule | Remote triggers via claude.ai (no channel) | Different approach |
|
|
|
|
For iMessage specifically, you need macOS. A Linux VPS with
|
|
tmux works for Telegram and Discord but not iMessage.
|
|
|
|
## Channels vs Dispatch vs Remote Control
|
|
|
|
These three features all let you interact with Claude Code
|
|
remotely, but they work differently:
|
|
|
|
| Feature | Trigger model | Best for |
|
|
|---------|--------------|----------|
|
|
| **Channels** | Event-based: chat apps push messages into session | Reacting to messages, CI events, chat commands |
|
|
| **Dispatch** | Message-based: you send a task from mobile app | Delegating work while away |
|
|
| **Remote Control** | Direct control: you steer an active session | Guiding in-progress work from another device |
|
|
|
|
**Channels** = "my agent listens to a chat app"
|
|
**Dispatch** = "I send my agent a job"
|
|
**Remote Control** = "I take the wheel remotely"
|
|
|
|
## Enterprise and Team plans
|
|
|
|
Channel use must be enabled by an admin:
|
|
Organization Settings > Claude Code > Channels > Enable
|
|
|
|
By default, channels are disabled on Team and Enterprise plans.
|