Skip to content

Your lightweight open-source personal agent.

docs: add high-usage chat app guides

chengyongru7204d88a4cdb
diff --git a/docs/README.md b/docs/README.md
index aec1660e8..9eb2c32ed 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -52,7 +52,10 @@ Platform-specific chat guides:
[`Telegram`](./guides/telegram-ai-agent.md),
[`Discord`](./guides/discord-ai-agent.md),
[`Slack`](./guides/slack-ai-agent.md),
+[`Feishu`](./guides/feishu-ai-agent.md),
+[`WhatsApp`](./guides/whatsapp-ai-agent.md),
[`WeChat`](./guides/wechat-ai-agent.md),
+[`QQ`](./guides/qq-ai-agent.md),
[`Email`](./guides/email-ai-agent.md), and
[`Mattermost`](./guides/mattermost-ai-agent.md).
diff --git a/docs/chat-apps.md b/docs/chat-apps.md
index 15abea475..70f9c5335 100644
--- a/docs/chat-apps.md
+++ b/docs/chat-apps.md
@@ -9,7 +9,10 @@ a focused setup path for one platform, start with a guide:
| Telegram | [Build a Telegram AI Agent with nanobot](./guides/telegram-ai-agent.md) |
| Discord | [Build a Discord AI Agent with nanobot](./guides/discord-ai-agent.md) |
| Slack | [Build a Slack AI Agent with nanobot](./guides/slack-ai-agent.md) |
+| Feishu | [Build a Feishu AI Agent with nanobot](./guides/feishu-ai-agent.md) |
+| WhatsApp | [Build a WhatsApp AI Agent with nanobot](./guides/whatsapp-ai-agent.md) |
| WeChat | [Build a WeChat AI Agent with nanobot](./guides/wechat-ai-agent.md) |
+| QQ | [Build a QQ AI Agent with nanobot](./guides/qq-ai-agent.md) |
| Email | [Build an Email AI Agent with nanobot](./guides/email-ai-agent.md) |
| Mattermost | [Build a Mattermost AI Agent with nanobot](./guides/mattermost-ai-agent.md) |
diff --git a/docs/guides/README.md b/docs/guides/README.md
index 7925379e8..df2a406ee 100644
--- a/docs/guides/README.md
+++ b/docs/guides/README.md
@@ -23,7 +23,10 @@ edge cases.
| Connect Telegram | [Telegram AI agent](./telegram-ai-agent.md) |
| Connect Discord | [Discord AI agent](./discord-ai-agent.md) |
| Connect Slack | [Slack AI agent](./slack-ai-agent.md) |
+| Connect Feishu | [Feishu AI agent](./feishu-ai-agent.md) |
+| Connect WhatsApp | [WhatsApp AI agent](./whatsapp-ai-agent.md) |
| Connect WeChat | [WeChat AI agent](./wechat-ai-agent.md) |
+| Connect QQ | [QQ AI agent](./qq-ai-agent.md) |
| Connect Email | [Email AI agent](./email-ai-agent.md) |
| Connect Mattermost | [Mattermost AI agent](./mattermost-ai-agent.md) |
| Run from Python | [Python AI agent SDK](./python-ai-agent-sdk.md) |
diff --git a/docs/guides/chat-app-ai-agent.md b/docs/guides/chat-app-ai-agent.md
index 83cb43b09..22bf48805 100644
--- a/docs/guides/chat-app-ai-agent.md
+++ b/docs/guides/chat-app-ai-agent.md
@@ -29,7 +29,10 @@ Then choose one platform guide:
- [Telegram AI agent](./telegram-ai-agent.md)
- [Discord AI agent](./discord-ai-agent.md)
- [Slack AI agent](./slack-ai-agent.md)
+- [Feishu AI agent](./feishu-ai-agent.md)
+- [WhatsApp AI agent](./whatsapp-ai-agent.md)
- [WeChat AI agent](./wechat-ai-agent.md)
+- [QQ AI agent](./qq-ai-agent.md)
- [Email AI agent](./email-ai-agent.md)
- [Mattermost AI agent](./mattermost-ai-agent.md)
diff --git a/docs/guides/feishu-ai-agent.md b/docs/guides/feishu-ai-agent.md
new file mode 100644
index 000000000..b7b0f3876
--- /dev/null
+++ b/docs/guides/feishu-ai-agent.md
@@ -0,0 +1,120 @@
+# Build a Feishu AI Agent with nanobot
+
+This guide connects nanobot to Feishu or Lark through the `feishu` channel. The
+channel uses a WebSocket long connection, so the first setup does not require a
+public webhook URL.
+
+## What this guide builds
+
+- a Feishu/Lark bot app connected to nanobot
+- the `feishu` channel enabled in `config.json`
+- one pairing-approved Feishu or Lark user
+- mention-only group behavior for first deployment
+
+## Prerequisites
+
+- A working local nanobot reply:
+
+```bash
+nanobot agent -m "Hello!"
+```
+
+- A Feishu or Lark account that can create or approve bot apps.
+- Permission to run `nanobot gateway` continuously.
+
+## Install nanobot
+
+```bash
+python -m pip install nanobot-ai
+nanobot onboard --wizard
+```
+
+## Enable the Feishu channel
+
+Install the optional channel dependency:
+
+```bash
+nanobot plugins enable feishu
+```
+
+The easiest path is QR login:
+
+```bash
+nanobot channels login feishu
+```
+
+Open the printed URL or scan the QR code. nanobot writes the generated `appId`,
+`appSecret`, `domain`, and `enabled` fields into the active config.
+
+If QR login is unavailable, create a Feishu/Lark app manually and merge this
+shape into `~/.nanobot/config.json`:
+
+```json
+{
+ "channels": {
+ "feishu": {
+ "enabled": true,
+ "appId": "cli_xxx",
+ "appSecret": "xxx",
+ "groupPolicy": "mention",
+ "streaming": true,
+ "domain": "feishu"
+ }
+ }
+}
+```
+
+Omitting `allowFrom` enables pairing-only mode. A new user should DM the bot,
+get a pairing code, and be approved before using the bot normally.
+
+For manual apps, enable the Bot capability, receive-message events, and Long
+Connection mode. If your app cannot get the `cardkit:card:write` permission,
+set `"streaming": false`.
+
+## Run nanobot gateway
+
+```bash
+nanobot channels status
+nanobot gateway
+```
+
+## Test a message
+
+DM the bot first. It should return a pairing code. Approve it from a trusted
+local surface:
+
+```bash
+nanobot agent -m "/pairing approve ABCD-EFGH"
+```
+
+After approval, DM the bot again or mention it in a group chat:
+
+```text
+@nanobot Hello from Feishu
+```
+
+## Security notes
+
+- Prefer pairing-only mode for first setup. Add `allowFrom` only when you want a
+ static allowlist.
+- Keep `groupPolicy` as `"mention"` before inviting the bot into busy groups.
+- Store app secrets through environment variables for deployed services.
+- Review file, shell, and web tool access before adding more users.
+
+## Troubleshooting
+
+- If QR login is unavailable, use manual app setup from the full chat-apps
+ reference.
+- If streaming cards fail, confirm `cardkit:card:write` or set
+ `"streaming": false`.
+- If no messages arrive, check Feishu/Lark event permissions, Long Connection
+ mode, and `nanobot gateway --verbose`.
+- If a first DM returns a pairing code, approve it before testing normal
+ replies.
+
+## Next: memory, automations, MCP tools
+
+- [Chat Apps reference](../chat-apps.md)
+- [Pairing](../configuration.md#pairing)
+- [AI Agent Memory](./ai-agent-memory.md)
+- [Configure MCP tools](./configure-mcp-tools.md)
diff --git a/docs/guides/qq-ai-agent.md b/docs/guides/qq-ai-agent.md
new file mode 100644
index 000000000..9ff110e48
--- /dev/null
+++ b/docs/guides/qq-ai-agent.md
@@ -0,0 +1,102 @@
+# Build a QQ AI Agent with nanobot
+
+This guide connects nanobot to QQ through the official `qq` channel. The
+official channel uses the botpy SDK and currently focuses on private messages.
+For QQ group chat and OneBot v11 workflows, use the Napcat section in the full
+chat-apps reference.
+
+## What this guide builds
+
+- a QQ bot application
+- the `qq` channel enabled in nanobot
+- one pairing-approved QQ private sender
+- a running nanobot gateway
+
+## Prerequisites
+
+- A working local nanobot reply:
+
+```bash
+nanobot agent -m "Hello!"
+```
+
+- Access to the QQ Open Platform.
+- A QQ account added to the bot sandbox for testing.
+
+## Install nanobot
+
+```bash
+python -m pip install nanobot-ai
+nanobot onboard --wizard
+```
+
+## Enable the QQ channel
+
+Install the optional channel dependency:
+
+```bash
+nanobot plugins enable qq
+```
+
+In the QQ Open Platform, create a bot application and copy the AppID and
+AppSecret. Add your QQ account to the sandbox test members, then merge this
+snippet into `~/.nanobot/config.json`:
+
+```json
+{
+ "channels": {
+ "qq": {
+ "enabled": true,
+ "appId": "YOUR_APP_ID",
+ "secret": "YOUR_APP_SECRET",
+ "msgFormat": "plain"
+ }
+ }
+}
+```
+
+Omitting `allowFrom` enables pairing-only mode. A new private sender should get
+a pairing code before normal agent access.
+
+## Run nanobot gateway
+
+```bash
+nanobot channels status
+nanobot gateway
+```
+
+## Test a message
+
+Send the QQ bot a private message from a sandbox account. It should return a
+pairing code. Approve it from a trusted local surface:
+
+```bash
+nanobot agent -m "/pairing approve ABCD-EFGH"
+```
+
+Send the message again after approval.
+
+## Security notes
+
+- Prefer pairing-only mode for first setup. Add `allowFrom` only when you want a
+ static allowlist.
+- Keep sandbox testing separate from production publishing.
+- Store QQ AppSecret through environment variables for deployed services.
+- Use Napcat only when you intentionally need a QQ account bridge and group chat
+ features.
+
+## Troubleshooting
+
+- If private messages do not arrive, confirm the sender is in the QQ bot sandbox
+ and the gateway is running.
+- If output formatting is unreliable, keep `msgFormat` as `"plain"`.
+- If a first private message returns a pairing code, approve it before testing
+ normal replies.
+- If you need QQ groups, see the Napcat section in the full chat-apps reference.
+
+## Next: memory, automations, MCP tools
+
+- [Chat Apps reference](../chat-apps.md)
+- [Pairing](../configuration.md#pairing)
+- [AI Agent Memory](./ai-agent-memory.md)
+- [Configure MCP tools](./configure-mcp-tools.md)
diff --git a/docs/guides/whatsapp-ai-agent.md b/docs/guides/whatsapp-ai-agent.md
new file mode 100644
index 000000000..8c1748c9e
--- /dev/null
+++ b/docs/guides/whatsapp-ai-agent.md
@@ -0,0 +1,107 @@
+# Build a WhatsApp AI Agent with nanobot
+
+This guide connects nanobot to WhatsApp through the `whatsapp` channel. The
+channel links as a WhatsApp device and uses the same nanobot agent runtime,
+tools, memory, and workspace as the CLI and WebUI.
+
+## What this guide builds
+
+- WhatsApp optional dependencies installed
+- a linked WhatsApp device session
+- the `whatsapp` channel enabled in `config.json`
+- one pairing-approved WhatsApp sender
+
+## Prerequisites
+
+- A working local nanobot reply:
+
+```bash
+nanobot agent -m "Hello!"
+```
+
+- A WhatsApp account that can link a new device.
+- A machine that can keep `nanobot gateway` running.
+
+## Install nanobot
+
+```bash
+python -m pip install nanobot-ai
+nanobot onboard --wizard
+```
+
+## Enable the WhatsApp channel
+
+Install the optional channel dependency:
+
+```bash
+nanobot plugins enable whatsapp
+```
+
+Link WhatsApp as a device:
+
+```bash
+nanobot channels login whatsapp
+```
+
+Scan the QR code from WhatsApp -> Settings -> Linked Devices.
+
+Merge this snippet into `~/.nanobot/config.json`:
+
+```json
+{
+ "channels": {
+ "whatsapp": {
+ "enabled": true,
+ "groupPolicy": "mention"
+ }
+ }
+}
+```
+
+Omitting `allowFrom` enables pairing-only mode for private chats. `groupPolicy`
+defaults to `"open"` in the channel, but `"mention"` is safer for a first
+deployment.
+
+## Run nanobot gateway
+
+```bash
+nanobot channels status
+nanobot gateway
+```
+
+## Test a message
+
+Send the bot a private WhatsApp message. It should return a pairing code.
+Approve it from a trusted local surface:
+
+```bash
+nanobot agent -m "/pairing approve ABCD-EFGH"
+```
+
+Send the message again after approval. The reply should use the same model and
+workspace as your local CLI check.
+
+## Security notes
+
+- Treat the WhatsApp session database as account access.
+- Prefer pairing-only mode for first setup. Add `allowFrom` only when you want a
+ static allowlist.
+- Keep `groupPolicy` as `"mention"` before adding the bot to groups.
+- Avoid `allowFrom: ["*"]` unless the bot is intentionally public or isolated.
+
+## Troubleshooting
+
+- If QR linking fails, rerun `nanobot channels login whatsapp`.
+- If you are migrating from the old bridge, remove `bridgeUrl` and
+ `bridgeToken`, then re-login.
+- If a sender appears as a LID instead of a phone number, let nanobot learn the
+ mapping at runtime or use `lidMappings` in the full reference.
+- If a first private message returns a pairing code, approve it before testing
+ normal replies.
+
+## Next: memory, automations, MCP tools
+
+- [Chat Apps reference](../chat-apps.md)
+- [Pairing](../configuration.md#pairing)
+- [Secure local AI agent](./secure-local-ai-agent.md)
+- [Deployment](../deployment.md)