内容
# 纳米克劳网络聊天
[](https://github.com/Artificer-Innovations/nanoclaw-webchat/actions/workflows/ci.yml)
[](https://www.npmjs.com/package/nanoclaw-webchat)
[](./LICENSE)
**从本地浏览器标签与您的纳米克劳代理进行对话** — 支持群聊 `@提及`、单个代理私聊、线程、附件和可选的 Cursor MCP 服务器。
**→ [快速开始 — QUICKSTART.md](./QUICKSTART.md)**
前提条件：**Node.js 22 LTS**、pnpm 和一个可用的纳米克劳分叉。参见 [QUICKSTART.md](./QUICKSTART.md#前提条件)。
```bash
pnpm add nanoclaw-webchat ws
pnpm exec nanoclaw-webchat install
# 重建并重启您的纳米克劳主机，然后打开 http://127.0.0.1:3200
```
## 为什么存在该项目
纳米克劳运行多个 AI 代理，配备有实际的工具和持久的工作空间。您需要一个 **本地优先的聊天台** 来与它们通信 — 不需要 Slack，不需要托管的 SaaS 小部件，也不需要另一个独立的代理运行时。
nanoclaw-webchat 是现有纳米克劳分叉的 **特定渠道插件**：
- **仅限本地主机** — 绑定到 `127.0.0.1`，由主机注入的秘密令牌
- **多代理群聊** — `@sarah` 样式的路由，带有 **已参与代理**，在提及后继续监听
- **单个代理私聊** — 直接 1:1 聊天室，当您不想要共享群聊时
- **线程** — 每个聊天室的多个对话线程，保存在 SQLite 中
- **相同的交付路径** — 消息通过纳米克劳的正常路由器流动，而不是通过侧通道
该软件包提供了浏览器 UI、渠道适配器模板、安装技能、CLI 和 MCP 服务器。**您仍然需要一个可用的纳米克劳分叉** — 这不是纳米克劳本身。
## 截图
| 群聊与 `@提及` 和已参与代理 | 边栏：聊天室、私聊、线程 |
|---|---|
|  |  |
| 私聊 | 附件预览抽屉 |
|---|---|
|  |  |
## 功能
| 领域 | 详情 |
|------|---------|
| **群聊** | 共享聊天室；使用 `@文件夹` 提及路由到代理；已参与代理的芯片在被忽略前保持活跃 |
| **私聊** | 每个代理一个聊天室 (`dm:<文件夹>`) |
| **线程** | 为每个聊天室创建、重命名、删除线程；在边栏中显示未读徽章 |
| **消息** | Markdown（GFM）、代码块、`@提及` 高亮 |
| **附件** | 拖放文件；可调整大小的预览抽屉（图片、PDF、代码、CSV、Markdown） |
| **主题** | 浅色 / 深色 / 系统 |
| **持久性** | 主机 `data/webchat.db` 中的历史记录 |
| **CLI** | `install`、`upgrade`、`sync-skill`、`verify`、`uninstall` |
| **MCP** | 捆绑的 `nanoclaw-webchat-mcp` 二进制文件 — 列出渠道，从 Cursor 读取/发送消息 |
| **技能** | `/add-webchat` 克劳德代码安装流程 |
## 快速安装
需要 Node.js ≥ 20、pnpm 和一个 **正在运行的纳米克劳分叉**。
```bash
cd /path/to/your-nanoclaw-fork
pnpm add nanoclaw-webchat ws
pnpm exec nanoclaw-webchat sync-skill
/add-webchat # 在克劳德代码中，或：pnpm exec nanoclaw-webchat install
pnpm run build && 重启主机
open http://127.0.0.1:3200
```
完整的操作指南： **[QUICKSTART.md](./QUICKSTART.md)**
## 配置
| 变量 | 必需 | 默认值 | 描述 |
|----------|----------|---------|-------------|
| `WEBCHAT_ENABLED` | 是 | — | 设置 `true` 以启动渠道 |
| `WEBCHAT_PORT` | 否 | `3200` | HTTP/WebSocket 端口 |
| `WEBCHAT_SECRET` | 是 | — | Bearer令牌（注入到提供的HTML中） |
| `WEBCHAT_USER_ID` | 否 | `web:local` | outbound 消息的用户ID |
| `WEBCHAT_DISPLAY_NAME` | 否 | `Local` | UI中的显示名称 |
| `WEBCHAT_TEAM_FOLDER` | 否 | — | `@team` 提及的代理文件夹 |
参见 [QUICKSTART.md](./QUICKSTART.md) 和 [api-contract.md](./api-contract.md) 以获取完整的API和MCP设置。
## 架构
```
浏览器UI ←HTTP/WS→ web.ts 适配器（在您的分叉中） → 纳米克劳路由器 → 代理
MCP服务器 ←REST──→ 相同的适配器
```
```
packages/client → React SPA（dist/client/）
packages/adapter → 渠道适配器模板 → 复制到主机src/
packages/cli → nanoclaw-webchat 二进制文件
packages/mcp → nanoclaw-webchat-mcp 二进制文件（捆绑）
packages/shared → 共享类型（内部）
skills/add-webchat → /add-webchat 安装技能
```
## 安全
该网络渠道设计用于 **本地受信任使用**：
- 适配器仅监听 **`127.0.0.1`** — 请勿在未替换身份验证的情况下绑定到 `0.0.0.0`
- `WEBCHAT_SECRET` 嵌入到提供的页面中；请像对待会话令牌一样对待它
- 参见 [SECURITY.md](./SECURITY.md) 以报告漏洞
## 开发
```bash
pnpm install
pnpm run typecheck
pnpm run test:coverage
pnpm run build
pnpm --filter @nanoclaw-webchat/client dev # Vite → 代理 /api 到 :3200
```
在不发布的情况下，对本地纳米克劳分叉进行测试：
```bash
cd ../your-nanoclaw-fork
pnpm add file:../nanoclaw-webchat
pnpm exec nanoclaw-webchat install
```
参见 [CONTRIBUTING.md](./CONTRIBUTING.md) 以获取分支流程、变更集和 monorepo 布局。
## 分支和发布
| 分支 | 角色 |
|--------|------|
| **`develop`** | 集成 — 功能和修复的PR在此处合并 |
| **`main`** | 发布 — 将 `develop` 合并到 `main` 发布到npm并创建GitHub发布 |
版本控制使用 [变更集](https://github.com/changesets/changesets)。发布说明： [CHANGELOG.md](./CHANGELOG.md)
## 许可证
MIT — 版权所有 (c) 2026 [Artificer Innovations, LLC](https://github.com/Artificer-Innovations)
参见 [LICENSE](./LICENSE)。
