Your lightweight open-source personal agent.
Python agent-frameworkai-agentai-agentschatbotchatopsdiscord-botllm-agentsllmslocal-llmmcpmodel-context-protocolmulti-agentopenai-compatibleopenclawpersonal-ai-assistantpythonself-hostedtelegram-bot-ai-assistantwebuiworkflow-automation
docs: add high-usage chat app guides
chengyongru7204d88a4cdb
diff --git a/docs/README.md b/docs/README.mdindex 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.mdindex 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.mdindex 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.mdindex 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.mdnew file mode 100644index 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.mdnew file mode 100644index 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.mdnew file mode 100644index 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)