@seeed-studio/meshtastic 0.1.1 → 0.2.1

package/README.pt.md

@@ -0,0 +1,337 @@
+# MeshClaw: Plugin de Canal Meshtastic para OpenClaw
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@seeed-studio/meshtastic">
+    <img alt="versão do npm" src="https://img.shields.io/npm/v/@seeed-studio/meshtastic.svg" />
+  </a>
+  <a href="https://www.npmjs.com/package/@seeed-studio/meshtastic">
+    <img alt="licença" src="https://img.shields.io/npm/l/@seeed-studio/meshtastic.svg" />
+  </a>
+</p>
+
+<!-- LANG_SWITCHER_START -->
+<p align="center">
+  <a href="README.md">English</a> | <a href="README.zh-CN.md">中文</a> | <a href="README.ja.md">日本語</a> | <a href="README.fr.md">Français</a> | <b>Português</b> | <a href="README.es.md">Español</a>
+</p>
+<!-- LANG_SWITCHER_END -->
+
+O MeshClaw é um plugin de canal do OpenClaw que permite ao seu gateway de IA enviar e receber mensagens via Meshtastic — sem internet, sem torres de celular, apenas ondas de rádio. Converse com seu assistente de IA das montanhas, do oceano ou de qualquer lugar onde a rede não chega.
+
+⭐ Dê uma estrela no GitHub — isso nos motiva muito!
+
+> [!IMPORTANT]
+> Este é um plugin de canal para o gateway de IA [OpenClaw](https://github.com/openclaw/openclaw) — não é um aplicativo independente. Você precisa de uma instância do OpenClaw em execução (Node.js 22+) para usá-lo.
+
+[Documentação][docs] · [Guia de Hardware](#hardware-recomendado) · [Reportar Problema][issues] · [Solicitar Recurso][issues]
+
+## Sumário
+
+- [Como Funciona](#como-funciona)
+- [Hardware Recomendado](#hardware-recomendado)
+- [Recursos](#recursos)
+- [Capacidades e Roteiro](#capacidades-e-roteiro)
+- [Demonstração](#demonstração)
+- [Início Rápido](#início-rápido)
+- [Assistente de Configuração](#assistente-de-configuração)
+- [Configuração](#1-transporte)
+- [Solução de Problemas](#2-região-lora)
+- [Desenvolvimento](#3-nome-do-nó)
+- [Contribuindo](#4-acesso-a-canais-grouppolicy)
+
+## Como Funciona
+
+```mermaid
+flowchart LR
+    subgraph mesh ["📻 LoRa Mesh Network"]
+        N["Meshtastic Nodes"]
+    end
+    subgraph gw ["⚙️ OpenClaw Gateway"]
+        P["Meshtastic Plugin"]
+        AI["AI Agent"]
+    end
+    N -- "Serial (USB)" --> P
+    N -- "HTTP (WiFi)" --> P
+    N -. "MQTT (Broker)" .-> P
+    P <--> AI
+```
+
+O plugin faz a ponte entre dispositivos LoRa Meshtastic e o agente de IA do OpenClaw. Ele suporta três modos de transporte:
+
+- Serial — conexão USB direta com um dispositivo Meshtastic local
+- HTTP — conecta-se a um dispositivo via Wi-Fi / rede local
+- MQTT — assina um broker MQTT do Meshtastic, sem necessidade de hardware local
+
+Mensagens de entrada passam por controle de acesso (política de DM, política de grupo, exigência de menção) antes de chegar à IA. As respostas de saída têm a formatação Markdown removida (os dispositivos LoRa não a renderizam) e são fragmentadas para caber nos limites de tamanho dos pacotes de rádio.
+
+## Hardware Recomendado
+
+<p align="center">
+  <img src="media/XIAOclaw.png" width="760" alt="Dispositivo Meshtastic com módulo Seeed XIAO" />
+</p>
+
+| Dispositivo                    | Melhor para              | Link            |
+| ----------------------------- | ------------------------ | --------------- |
+| XIAO ESP32S3 + Wio-SX1262 kit | Desenvolvimento inicial  | [Comprar][hw-xiao]     |
+| Wio Tracker L1 Pro            | Gateway de campo portátil | [Comprar][hw-wio]      |
+| SenseCAP Card Tracker T1000-E | Rastreador compacto      | [Comprar][hw-sensecap] |
+
+Sem hardware? O transporte via MQTT conecta-se através do broker — nenhum dispositivo local é necessário.
+
+Qualquer dispositivo compatível com Meshtastic funciona.
+
+## Recursos
+
+- Integração com Agente de IA — Faz a ponte entre agentes de IA do OpenClaw e redes de malha LoRa Meshtastic. Habilita comunicação inteligente sem dependência da nuvem.
+
+- Três Modos de Transporte — Suporte a Serial (USB), HTTP (Wi-Fi) e MQTT
+
+- Canais de DM e Grupo com Controle de Acesso — Suporta ambos os modos de conversa com listas de permissão para DMs, regras de resposta por canal e exigência de menção
+
+- Suporte a Múltiplas Contas — Execute várias conexões independentes simultaneamente
+
+- Comunicação Resiliente na Malha — Reconexão automática com tentativas configuráveis. Lida bem com quedas de conexão.
+
+## Capacidades e Roteiro
+
+O plugin trata o Meshtastic como um canal de primeira classe — como Telegram ou Discord — permitindo conversas com IA e invocação de habilidades inteiramente via rádio LoRa, sem dependência de internet.
+
+| Consultar Informações Offline                               | Ponte entre Canais: Envie fora da rede, receba em qualquer lugar | 🔜 Próximos passos:                                           |
+| ----------------------------------------------------------- | --------------------------------------------------------------- | ------------------------------------------------------------- |
+| <img src="media/image1.png" alt="Consultar Informações Offline" /> | <img src="media/image2.png" alt="Ponte entre Canais" />          | Planejamos ingerir dados em tempo real dos nós (localização GPS, sensores ambientais, status do dispositivo) no contexto do OpenClaw, permitindo que a IA monitore a saúde da rede de malha e transmita alertas proativos sem esperar por perguntas dos usuários. |
+
+## Demonstração
+
+<div align="center">
+
+https://github.com/user-attachments/assets/837062d9-a5bb-4e0a-b7cf-298e4bdf2f7c
+
+</div>
+
+Alternativa: [media/demo.mp4](media/demo.mp4)
+
+## Início Rápido
+
+```bash
+# 1. Install plugin
+openclaw plugins install @seeed-studio/meshtastic
+
+# 2. Guided setup — walks you through transport, region, and access policy
+openclaw onboard
+
+# 3. Verify
+openclaw channels status --probe
+```
+
+<p align="center">
+  <img src="media/setup-screenshot.png" width="700" alt="Assistente de configuração do OpenClaw" />
+</p>
+
+## Assistente de Configuração
+
+Executar `openclaw onboard` inicia um assistente interativo que guia você por cada etapa de configuração. Abaixo está o significado de cada etapa e como escolher.
+
+### 1. Transporte
+
+Como o gateway se conecta à malha Meshtastic:
+
+| Opção             | Descrição                                                     | Requisitos                                        |
+| ----------------- | ------------------------------------------------------------- | ------------------------------------------------- |
+| Serial (USB)      | Conexão USB direta a um dispositivo local. Detecta portas automaticamente. | Dispositivo Meshtastic conectado via USB          |
+| HTTP (Wi-Fi)      | Conecta a um dispositivo na rede local.                       | IP ou hostname do dispositivo (ex.: `meshtastic.local`) |
+| MQTT (broker)     | Conecta à malha via um broker MQTT — sem necessidade de hardware local. | Endereço do broker, credenciais e tópico de assinatura |
+
+### 2. Região LoRa
+
+> Somente Serial e HTTP. O MQTT obtém a região a partir do tópico de assinatura.
+
+Define a região de frequência de rádio no dispositivo. Deve corresponder às regulamentações locais e aos outros nós da malha. Opções comuns:
+
+| Região   | Frequência          |
+| -------- | ------------------- |
+| US       | 902–928 MHz         |
+| EU_868   | 869 MHz             |
+| CN       | 470–510 MHz         |
+| JP       | 920 MHz             |
+| UNSET    | Manter padrão do dispositivo |
+
+Veja a [documentação de regiões do Meshtastic](https://meshtastic.org/docs/getting-started/initial-config/#lora) para a lista completa.
+
+### 3. Nome do Nó
+
+O nome de exibição do dispositivo na malha. Também é usado como o gatilho de @menção em canais de grupo — outros usuários enviam `@OpenClaw` para falar com seu bot.
+
+- Serial / HTTP: opcional — detecta automaticamente do dispositivo conectado se deixar em branco.
+- MQTT: obrigatório — não há dispositivo físico do qual ler o nome.
+
+### 4. Acesso a Canais (groupPolicy)
+
+Controla se e como o bot responde em canais de grupo da malha (por exemplo, LongFast, Emergency):
+
+| Política            | Comportamento                                                |
+| ------------------- | ------------------------------------------------------------ |
+| `disabled` (padrão) | Ignora todas as mensagens de canais de grupo. Somente DMs são processadas. |
+| `open`              | Responde em todos os canais da malha.                       |
+| `allowlist`         | Responde apenas nos canais listados. Você será solicitado a informar os nomes dos canais (separados por vírgulas, ex.: `LongFast, Emergency`). Use `*` como curinga para corresponder a todos. |
+
+### 5. Exigir Menção
+
+> Aparece apenas quando o acesso a canais está habilitado (não `disabled`).
+
+Quando habilitado (padrão: sim), o bot só responde em canais de grupo quando alguém menciona seu nome de nó (ex.: `@OpenClaw como está o tempo?`). Isso evita que o bot responda a todas as mensagens do canal.
+
+Quando desabilitado, o bot responde a todas as mensagens nos canais permitidos.
+
+### 6. Política de Acesso a DM (dmPolicy)
+
+Controla quem pode enviar mensagens diretas ao bot:
+
+| Política           | Comportamento                                                 |
+| ------------------ | ------------------------------------------------------------- |
+| `pairing` (padrão) | Novos remetentes disparam um pedido de pareamento que deve ser aprovado antes de poderem conversar. |
+| `open`             | Qualquer pessoa na malha pode enviar DMs livremente.         |
+| `allowlist`        | Somente nós listados em `allowFrom` podem enviar DM. Todos os outros são ignorados. |
+
+### 7. Lista de Permissões de DM (allowFrom)
+
+> Aparece apenas quando `dmPolicy` é `allowlist`, ou quando o assistente determina que é necessário.
+
+Uma lista de IDs de Usuário Meshtastic autorizados a enviar mensagens diretas. Formato: `!aabbccdd` (ID de usuário em hex). Entradas múltiplas são separadas por vírgulas.
+
+<p align="center">
+  <img src="media/image3.jpg" width="400" />
+</p>
+
+### 8. Nomes de Exibição das Contas
+
+> Aparece apenas para configurações com várias contas. Opcional.
+
+Atribui nomes amigáveis às suas contas. Por exemplo, uma conta com ID `home` pode ser exibida como "Estação Casa". Se ignorado, o ID bruto da conta é usado como está. Isso é puramente cosmético e não afeta a funcionalidade.
+
+## Configuração
+
+A configuração guiada (`openclaw onboard`) cobre tudo abaixo. Veja o [Assistente de Configuração](#assistente-de-configuração) para um passo a passo. Para configurar manualmente, edite com `openclaw config edit`.
+
+### Serial (USB)
+
+```yaml
+channels:
+  meshtastic:
+    transport: serial
+    serialPort: /dev/ttyUSB0
+    nodeName: OpenClaw
+```
+
+### HTTP (Wi-Fi)
+
+```yaml
+channels:
+  meshtastic:
+    transport: http
+    httpAddress: meshtastic.local
+    nodeName: OpenClaw
+```
+
+### MQTT (broker)
+
+```yaml
+channels:
+  meshtastic:
+    transport: mqtt
+    nodeName: OpenClaw
+    mqtt:
+      broker: mqtt.meshtastic.org
+      username: meshdev
+      password: large4cats
+      topic: "msh/US/2/json/#"
+```
+
+### Várias contas
+
+```yaml
+channels:
+  meshtastic:
+    accounts:
+      home:
+        transport: serial
+        serialPort: /dev/ttyUSB0
+      remote:
+        transport: mqtt
+        mqtt:
+          broker: mqtt.meshtastic.org
+          topic: "msh/US/2/json/#"
+```
+
+<details>
+<summary><b>Referência de Todas as Opções</b></summary>
+
+| Chave               | Tipo                           | Padrão               | Observações                                                |
+| ------------------- | ------------------------------ | -------------------- | ---------------------------------------------------------- |
+| `transport`         | `serial \| http \| mqtt`       | `serial`             |                                                            |
+| `serialPort`        | `string`                       | —                    | Obrigatório para serial                                    |
+| `httpAddress`       | `string`                       | `meshtastic.local`   | Obrigatório para HTTP                                      |
+| `httpTls`           | `boolean`                      | `false`              |                                                            |
+| `mqtt.broker`       | `string`                       | `mqtt.meshtastic.org`|                                                            |
+| `mqtt.port`         | `number`                       | `1883`               |                                                            |
+| `mqtt.username`     | `string`                       | `meshdev`            |                                                            |
+| `mqtt.password`     | `string`                       | `large4cats`         |                                                            |
+| `mqtt.topic`        | `string`                       | `msh/US/2/json/#`    | Tópico de assinatura                                       |
+| `mqtt.publishTopic` | `string`                       | derivado             |                                                            |
+| `mqtt.tls`          | `boolean`                      | `false`              |                                                            |
+| `region`            | enum                           | `UNSET`              | `US`, `EU_868`, `CN`, `JP`, `ANZ`, `KR`, `TW`, `RU`, `IN`, `NZ_865`, `TH`, `EU_433`, `UA_433`, `UA_868`, `MY_433`, `MY_919`, `SG_923`, `LORA_24`. Apenas Serial/HTTP. |
+| `nodeName`          | `string`                       | auto-detect          | Nome de exibição e gatilho de @menção. Obrigatório para MQTT. |
+| `dmPolicy`          | `open \| pairing \| allowlist` | `pairing`            | Quem pode enviar mensagens diretas. Veja [Política de Acesso a DM](#6-política-de-acesso-a-dm-dmpolicy). |
+| `allowFrom`         | `string[]`                     | —                    | IDs de nós para a lista de permissões de DM, ex.: `["!aabbccdd"]` |
+| `groupPolicy`       | `open \| allowlist \| disabled`| `disabled`           | Política de resposta em canais de grupo. Veja [Acesso a Canais](#4-acesso-a-canais-grouppolicy). |
+| `channels`          | `Record<string, object>`       | —                    | Substituições por canal: `requireMention`, `allowFrom`, `tools` |
+
+</details>
+
+<details>
+<summary><b>Substituições por Variáveis de Ambiente</b></summary>
+
+Estas substituem a configuração da conta padrão (o YAML tem precedência para contas nomeadas):
+
+| Variável                   | Chave de config equivalente |
+| ------------------------- | --------------------------- |
+| `MESHTASTIC_TRANSPORT`    | `transport`                 |
+| `MESHTASTIC_SERIAL_PORT`  | `serialPort`                |
+| `MESHTASTIC_HTTP_ADDRESS` | `httpAddress`               |
+| `MESHTASTIC_MQTT_BROKER`  | `mqtt.broker`               |
+| `MESHTASTIC_MQTT_TOPIC`   | `mqtt.topic`                |
+
+</details>
+
+## Solução de Problemas
+
+| Sintoma              | Verifique                                                    |
+| -------------------- | ------------------------------------------------------------ |
+| Serial não conecta   | Caminho do dispositivo correto? O host tem permissão?        |
+| HTTP não conecta     | `httpAddress` acessível? `httpTls` corresponde ao do dispositivo? |
+| MQTT não recebe nada | Região em `mqtt.topic` correta? Credenciais do broker válidas? |
+| Sem respostas em DM  | `dmPolicy` e `allowFrom` configurados? Veja [Política de Acesso a DM](#6-política-de-acesso-a-dm-dmpolicy). |
+| Sem respostas em grupo | `groupPolicy` habilitada? Canal na lista de permissões? Menção exigida? Veja [Acesso a Canais](#4-acesso-a-canais-grouppolicy). |
+
+Encontrou um bug? [Abra uma issue][issues] com o tipo de transporte, configuração (redija segredos) e a saída de `openclaw channels status --probe`.
+
+## Desenvolvimento
+
+```bash
+git clone https://github.com/Seeed-Solution/MeshClaw.git
+cd MeshClaw
+npm install
+openclaw plugins install -l ./MeshClaw
+```
+
+Sem etapa de build — o OpenClaw carrega o código-fonte TypeScript diretamente. Use `openclaw channels status --probe` para verificar.
+
+## Contribuindo
+
+- [Abra uma issue][issues] para bugs ou pedidos de recursos
+- Pull requests são bem-vindos — mantenha o código alinhado com as convenções existentes de TypeScript
+
+<!-- Links em estilo de referência -->
+[docs]: https://meshtastic.org/docs/
+[issues]: https://github.com/Seeed-Solution/MeshClaw/issues
+[hw-xiao]: https://www.seeedstudio.com/Wio-SX1262-with-XIAO-ESP32S3-p-5982.html
+[hw-wio]: https://www.seeedstudio.com/Wio-Tracker-L1-Pro-p-6454.html
+[hw-sensecap]: https://www.seeedstudio.com/SenseCAP-Card-Tracker-T1000-E-for-Meshtastic-p-5913.html

package/README.zh-CN.md

@@ -0,0 +1,337 @@
+# MeshClaw：OpenClaw Meshtastic 频道插件
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@seeed-studio/meshtastic">
+    <img alt="npm 版本" src="https://img.shields.io/npm/v/@seeed-studio/meshtastic.svg" />
+  </a>
+  <a href="https://www.npmjs.com/package/@seeed-studio/meshtastic">
+    <img alt="许可证" src="https://img.shields.io/npm/l/@seeed-studio/meshtastic.svg" />
+  </a>
+</p>
+
+<!-- LANG_SWITCHER_START -->
+<p align="center">
+  <a href="README.md">English</a> | <b>中文</b> | <a href="README.ja.md">日本語</a> | <a href="README.fr.md">Français</a> | <a href="README.pt.md">Português</a> | <a href="README.es.md">Español</a>
+</p>
+<!-- LANG_SWITCHER_END -->
+
+MeshClaw 是一个 OpenClaw 频道插件，让你的 AI 网关通过 Meshtastic 发送和接收消息——无需互联网、无需蜂窝网络，只靠电波。在山里、海上，或任何不在电网覆盖范围的地方，都能与 AI 助手沟通。
+
+⭐ 欢迎在 GitHub 上为我们点 Star——这对我们很有激励！
+
+> [!IMPORTANT]
+> 这是用于 [OpenClaw](https://github.com/openclaw/openclaw) AI 网关的“频道插件”，并非独立应用。使用前需要一个已运行的 OpenClaw 实例（Node.js 22+）。
+
+[文档][docs] · [硬件指南](#recommended-hardware) · [提交 Bug][issues] · [功能请求][issues]
+
+## 目录
+
+- [工作原理](#工作原理)
+- [推荐硬件](#推荐硬件)
+- [功能](#功能)
+- [能力与路线图](#能力与路线图)
+- [演示](#演示)
+- [快速开始](#快速开始)
+- [设置向导](#设置向导)
+- [配置](#1-传输方式)
+- [故障排查](#2-lora-区域)
+- [开发](#3-节点名称)
+- [贡献](#4-频道访问grouppolicy)
+
+## 工作原理
+
+```mermaid
+flowchart LR
+    subgraph mesh ["📻 LoRa Mesh Network"]
+        N["Meshtastic Nodes"]
+    end
+    subgraph gw ["⚙️ OpenClaw Gateway"]
+        P["Meshtastic Plugin"]
+        AI["AI Agent"]
+    end
+    N -- "Serial (USB)" --> P
+    N -- "HTTP (WiFi)" --> P
+    N -. "MQTT (Broker)" .-> P
+    P <--> AI
+```
+
+该插件在 Meshtastic LoRa 设备与 OpenClaw AI 代理之间建立桥接。支持三种传输模式：
+
+- 串口（Serial）——通过 USB 直连本地 Meshtastic 设备
+- HTTP ——通过 WiFi/局域网连接设备
+- MQTT ——订阅 Meshtastic MQTT 代理，无需本地硬件
+
+入站消息会经过访问控制（私信策略、群组策略、@提及门槛）后再交给 AI。出站回复会移除 Markdown 格式（LoRa 设备无法渲染），并按无线电数据包大小限制进行分片发送。
+
+## 推荐硬件
+
+<p align="center">
+  <img src="media/XIAOclaw.png" width="760" alt="搭载 Seeed XIAO 模组的 Meshtastic 设备" />
+</p>
+
+| 设备                         | 最佳用途               | 链接               |
+| ---------------------------- | ---------------------- | ------------------ |
+| XIAO ESP32S3 + Wio-SX1262 套件 | 入门级开发             | [购买][hw-xiao]    |
+| Wio Tracker L1 Pro           | 便携式现场网关         | [购买][hw-wio]     |
+| SenseCAP Card Tracker T1000-E | 小型追踪器             | [购买][hw-sensecap] |
+
+没有硬件？可使用 MQTT 传输通过代理连接——无需本地设备。
+
+任何兼容 Meshtastic 的设备都可以使用。
+
+## 功能
+
+- AI 代理集成——将 OpenClaw AI 代理与 Meshtastic LoRa Mesh 网络桥接，实现无云依赖的智能通信。
+
+- 三种传输模式——支持串口（USB）、HTTP（WiFi）与 MQTT
+
+- 私信与群组频道的访问控制——支持两种会话模式，提供私信白名单、频道响应规则与@提及门槛
+
+- 多账号支持——可同时运行多个独立连接
+
+- 稳健的 Mesh 通信——可配置自动重连与重试，优雅应对掉线与中断
+
+## 能力与路线图
+
+该插件将 Meshtastic 视为一等公民的通讯渠道——就像 Telegram 或 Discord 一样——使 AI 对话与工具调用完全通过 LoRa 无线电进行，无需依赖互联网。
+
+| 离线查询信息                                            | 跨渠道桥接：离网发送，任意处接收                        | 🔜 接下来：                                                |
+| ------------------------------------------------------- | ------------------------------------------------------- | --------------------------------------------------------- |
+| <img src="media/image1.png" alt="离线查询信息" />       | <img src="media/image2.png" alt="跨渠道桥接" />         | 我们计划将实时节点数据（GPS 位置、环境传感、设备状态）注入 OpenClaw 上下文，让 AI 能监控 Mesh 网络健康状况，并主动广播告警，而无需等待用户发问。 |
+
+## 演示
+
+<div align="center">
+
+https://github.com/user-attachments/assets/837062d9-a5bb-4e0a-b7cf-298e4bdf2f7c
+
+</div>
+
+备用视频： [media/demo.mp4](media/demo.mp4)
+
+## 快速开始
+
+```bash
+# 1. Install plugin
+openclaw plugins install @seeed-studio/meshtastic
+
+# 2. Guided setup — walks you through transport, region, and access policy
+openclaw onboard
+
+# 3. Verify
+openclaw channels status --probe
+```
+
+<p align="center">
+  <img src="media/setup-screenshot.png" width="700" alt="OpenClaw 设置向导" />
+</p>
+
+## 设置向导
+
+运行 `openclaw onboard` 会启动交互式向导，引导你完成每一步配置。下面解释每一步的含义与选择建议。
+
+### 1. 传输方式
+
+网关如何连接到 Meshtastic Mesh：
+
+| 选项               | 说明                                                          | 要求                                           |
+| ------------------ | ------------------------------------------------------------- | ---------------------------------------------- |
+| 串口（Serial，USB） | 通过 USB 直连本地设备。可自动检测可用端口。                    | 通过 USB 连接的 Meshtastic 设备                |
+| HTTP（WiFi）       | 通过局域网连接设备。                                           | 设备 IP 或主机名（如 `meshtastic.local`）      |
+| MQTT（代理）       | 通过 MQTT 代理接入 Mesh——无需本地硬件。                         | 代理地址、凭据与订阅主题                       |
+
+### 2. LoRa 区域
+
+> 仅适用于串口与 HTTP。MQTT 会根据订阅主题推导区域。
+
+设置设备的无线频段区域。必须符合当地法规，并与 Mesh 上其他节点一致。常见选项：
+
+| 区域     | 频段               |
+| -------- | ------------------ |
+| `US`     | 902–928 MHz        |
+| `EU_868` | 869 MHz            |
+| `CN`     | 470–510 MHz        |
+| `JP`     | 920 MHz            |
+| `UNSET`  | 保持设备默认       |
+
+完整列表参见 [Meshtastic 区域文档](https://meshtastic.org/docs/getting-started/initial-config/#lora)。
+
+### 3. 节点名称
+
+设备在 Mesh 上的显示名称。也作为群组频道中的“@提及触发词”——其他用户发送 `@OpenClaw` 与机器人对话。
+
+- 串口/HTTP：可选——若留空，将自动从连接的设备读取名称。
+- MQTT：必填——因为没有实体设备可读取名称。
+
+### 4. 频道访问（groupPolicy）
+
+控制机器人在“Mesh 群组频道”（如 LongFast、Emergency）中的响应策略：
+
+| 策略                 | 行为说明                                                     |
+| -------------------- | ------------------------------------------------------------ |
+| `disabled`（默认）   | 忽略所有群组频道消息。仅处理私信。                           |
+| `open`               | 在 Mesh 上的“所有”频道中响应。                               |
+| `allowlist`          | 仅在“列出的”频道中响应。会提示输入频道名（逗号分隔，如 `LongFast, Emergency`）。使用 `*` 作为通配符匹配全部。 |
+
+### 5. 需要 @提及
+
+> 仅当频道访问已启用（非 `disabled`）时出现。
+
+启用时（默认：是），机器人只在群组频道里被@到其节点名时才回应（例如 `@OpenClaw 天气怎么样？`）。这可避免机器人对频道中每一条消息都做出回复。
+
+若关闭，则机器人会在允许的频道中对“所有”消息回复。
+
+### 6. 私信访问策略（dmPolicy）
+
+控制谁可以给机器人发送“私信”：
+
+| 策略                 | 行为说明                                                     |
+| -------------------- | ------------------------------------------------------------ |
+| `pairing`（默认）    | 新发送者会触发配对请求，需先批准后才能聊天。                 |
+| `open`               | Mesh 上任何人都可以自由私信机器人。                          |
+| `allowlist`          | 只有 `allowFrom` 列表中的节点可以私信。其他一律忽略。        |
+
+### 7. 私信白名单（allowFrom）
+
+> 仅当 `dmPolicy` 为 `allowlist`，或向导判定需要时出现。
+
+允许发送私信的 Meshtastic 用户 ID 列表。格式：`!aabbccdd`（16 进制用户 ID）。多个条目用逗号分隔。
+
+<p align="center">
+  <img src="media/image3.jpg" width="400" />
+</p>
+
+### 8. 账号显示名称
+
+> 仅对多账号配置显示。可选。
+
+为你的账号分配易读的显示名称。比如，将 ID 为 `home` 的账号显示为 “Home Station”。若跳过，将直接使用原始账号 ID。仅用于显示，不影响功能。
+
+## 配置
+
+引导式设置（`openclaw onboard`）已覆盖以下所有内容。详见[设置向导](#setup-wizard)。若需手动配置，可用 `openclaw config edit` 编辑。
+
+### 串口（USB）
+
+```yaml
+channels:
+  meshtastic:
+    transport: serial
+    serialPort: /dev/ttyUSB0
+    nodeName: OpenClaw
+```
+
+### HTTP（WiFi）
+
+```yaml
+channels:
+  meshtastic:
+    transport: http
+    httpAddress: meshtastic.local
+    nodeName: OpenClaw
+```
+
+### MQTT（代理）
+
+```yaml
+channels:
+  meshtastic:
+    transport: mqtt
+    nodeName: OpenClaw
+    mqtt:
+      broker: mqtt.meshtastic.org
+      username: meshdev
+      password: large4cats
+      topic: "msh/US/2/json/#"
+```
+
+### 多账号
+
+```yaml
+channels:
+  meshtastic:
+    accounts:
+      home:
+        transport: serial
+        serialPort: /dev/ttyUSB0
+      remote:
+        transport: mqtt
+        mqtt:
+          broker: mqtt.meshtastic.org
+          topic: "msh/US/2/json/#"
+```
+
+<details>
+<summary><b>所有选项参考</b></summary>
+
+| 键                   | 类型                             | 默认值               | 说明                                                         |
+| -------------------- | -------------------------------- | -------------------- | ------------------------------------------------------------ |
+| `transport`          | `serial \| http \| mqtt`         | `serial`             |                                                              |
+| `serialPort`         | `string`                         | —                    | 串口模式必填                                                 |
+| `httpAddress`        | `string`                         | `meshtastic.local`   | HTTP 模式必填                                                |
+| `httpTls`            | `boolean`                        | `false`              |                                                              |
+| `mqtt.broker`        | `string`                         | `mqtt.meshtastic.org`|                                                              |
+| `mqtt.port`          | `number`                         | `1883`               |                                                              |
+| `mqtt.username`      | `string`                         | `meshdev`            |                                                              |
+| `mqtt.password`      | `string`                         | `large4cats`         |                                                              |
+| `mqtt.topic`         | `string`                         | `msh/US/2/json/#`    | 订阅主题                                                     |
+| `mqtt.publishTopic`  | `string`                         | derived              |                                                              |
+| `mqtt.tls`           | `boolean`                        | `false`              |                                                              |
+| `region`             | enum                             | `UNSET`              | `US`, `EU_868`, `CN`, `JP`, `ANZ`, `KR`, `TW`, `RU`, `IN`, `NZ_865`, `TH`, `EU_433`, `UA_433`, `UA_868`, `MY_433`, `MY_919`, `SG_923`, `LORA_24`。仅串口/HTTP。 |
+| `nodeName`           | `string`                         | auto-detect          | 显示名与 @提及触发词。MQTT 必填。                            |
+| `dmPolicy`           | `open \| pairing \| allowlist`   | `pairing`            | 谁可以发送私信。见[私信访问策略](#6-私信访问策略-dmpolicy)。 |
+| `allowFrom`          | `string[]`                       | —                    | 私信白名单节点 ID，例如 `["!aabbccdd"]`                      |
+| `groupPolicy`        | `open \| allowlist \| disabled`  | `disabled`           | 群组频道响应策略。见[频道访问](#4-频道访问-grouppolicy)。    |
+| `channels`           | `Record<string, object>`         | —                    | 按频道覆盖：`requireMention`、`allowFrom`、`tools`           |
+
+</details>
+
+<details>
+<summary><b>环境变量覆盖</b></summary>
+
+这些环境变量会覆盖“默认账号”的配置（对命名账号，以 YAML 配置为准）：
+
+| 变量名                      | 等效配置键         |
+| --------------------------- | ------------------ |
+| `MESHTASTIC_TRANSPORT`      | `transport`        |
+| `MESHTASTIC_SERIAL_PORT`    | `serialPort`       |
+| `MESHTASTIC_HTTP_ADDRESS`   | `httpAddress`      |
+| `MESHTASTIC_MQTT_BROKER`    | `mqtt.broker`      |
+| `MESHTASTIC_MQTT_TOPIC`     | `mqtt.topic`       |
+
+</details>
+
+## 故障排查
+
+| 现象                  | 检查点                                                      |
+| --------------------- | ----------------------------------------------------------- |
+| 串口无法连接          | 设备路径是否正确？主机是否有访问权限？                      |
+| HTTP 无法连接         | `httpAddress` 是否可达？`httpTls` 是否与设备设置匹配？      |
+| MQTT 没有收到消息     | `mqtt.topic` 中的区域是否正确？代理凭据是否有效？           |
+| 私信没响应            | `dmPolicy` 与 `allowFrom` 是否配置？见[私信访问策略](#6-私信访问策略-dmpolicy)。 |
+| 群组无回复            | `groupPolicy` 是否启用？频道是否在白名单？是否需要 @提及？见[频道访问](#4-频道访问-grouppolicy)。 |
+
+发现 Bug？请[提交 Issue][issues]，并附上传输类型、配置（注意去除敏感信息）以及 `openclaw channels status --probe` 的输出。
+
+## 开发
+
+```bash
+git clone https://github.com/Seeed-Solution/MeshClaw.git
+cd MeshClaw
+npm install
+openclaw plugins install -l ./MeshClaw
+```
+
+无需构建步骤——OpenClaw 会直接加载 TypeScript 源码。使用 `openclaw channels status --probe` 进行验证。
+
+## 贡献
+
+- 发现问题或需要新功能，请[提交 Issue][issues]
+- 欢迎提交 PR——请保持代码风格与现有 TypeScript 约定一致
+
+<!-- Reference-style links -->
+[docs]: https://meshtastic.org/docs/
+[issues]: https://github.com/Seeed-Solution/MeshClaw/issues
+[hw-xiao]: https://www.seeedstudio.com/Wio-SX1262-with-XIAO-ESP32S3-p-5982.html
+[hw-wio]: https://www.seeedstudio.com/Wio-Tracker-L1-Pro-p-6454.html
+[hw-sensecap]: https://www.seeedstudio.com/SenseCAP-Card-Tracker-T1000-E-for-Meshtastic-p-5913.html