github.com/NJX-njx/opensoul @v0.2.4

你的 AI 灵魂伴侣 — 聊天、协作、创造

自托管 AI 智能体网关，支持 WhatsApp、Telegram、Discord、Slack、iMessage 等 30+ 渠道。

一个网关连接多渠道，兼顾数据掌控、路由能力与可扩展性。

项目简介 • 最近进展 • 功能概览 • 架构 • 仓库结构 • 技术栈 • 快速开始 • 配置说明 • 开发工作流 • 测试 • 扩展开发 • 故障排查 • 文档

项目简介

OpenSoul 是一个自托管 AI 智能体网关。你只需要运行一个网关进程，就可以在 WhatsApp、Telegram、Discord、Slack、iMessage 等多个渠道中使用同一个 AI 智能体。

它采用本地优先控制平面：将渠道适配层统一接入一个运行时，由你掌控模型路由、长期记忆、工具调用与安全边界。

最近进展

基于 CHANGELOG 的近期更新：

• Onboarding 与 Control UI 的国际化覆盖更完整。
• Windows 桌面端交互细节与连接稳定性提升。
• 网关连接与健康检查韧性增强。
• 扩展插件版本节奏与核心发布保持一致。

功能概览

🌐 30+ 渠道

🧠 智能体运行时

• 多模型路由（OpenAI、Anthropic、Gemini、Bedrock、Ollama、MiniMax、OpenRouter 等）
• 按发送者/工作区隔离会话
• 基于向量检索的长期记忆
• 工具执行、沙箱与插件扩展机制

🛠️ 技能与工具

• skills/ 提供 50+ 内置技能
• 支持 GitHub、Notion、Obsidian、Canvas、tmux、浏览器自动化等集成
• 提供公开插件 SDK，可扩展渠道、工具、Hook、Provider

📱 跨平台客户端

• macOS、iOS、Android、Windows 原生应用
• Web Control UI + CLI/TUI 工作流

架构

flowchart LR
  A["渠道 / 渠道插件"] --> B["Gateway"]
  B --> C["智能体运行时 (pi-ai)"]
  B --> D["记忆与存储"]
  B --> E["技能与工具"]
  B --> F["Web 控制台"]
  B --> G["CLI / TUI"]
  B --> H["原生应用"]

核心模块

仓库结构

src/           核心网关、运行时、路由、配置、插件
extensions/    外部渠道/Provider/Hook 扩展
ui/            Web 控制台资源与前端应用
skills/        内置技能
docs/          用户与参考文档
apps/          原生客户端（Android/iOS/macOS/Windows）
scripts/       构建、发布、测试与工具脚本

技术栈

快速开始

前置要求

• Node.js >= 22
• pnpm

安装

git clone https://github.com/NJX-njx/opensoul.git
cd opensoul
pnpm install
pnpm build

启动网关（开发模式）

# 跳过需要外部凭证的渠道
export OPENSOUL_SKIP_CHANNELS=1
export OPENSOUL_GATEWAY_TOKEN=dev-token
pnpm gateway:dev

Windows（PowerShell）启动

$env:OPENSOUL_SKIP_CHANNELS = "1"; $env:OPENSOUL_GATEWAY_TOKEN = "dev-token"; node scripts/run-node.mjs --dev gateway

生产运行

opensoul onboard
opensoul gateway run

配置说明

环境变量模板

可放在 .env 或 ~/.opensoul/.env：

OPENAI_API_KEY=
ANTHROPIC_API_KEY=
OPENROUTER_API_KEY=
GEMINI_API_KEY=
MINIMAX_API_KEY=
OPENCODE_API_KEY=
ZAI_API_KEY=
OPENSOUL_GATEWAY_TOKEN=

加载顺序与优先级见 Environment。

关键说明

• 网关启动必须有 OPENSOUL_GATEWAY_TOKEN（或 gateway.auth.token）。
• 本地开发建议默认使用 OPENSOUL_SKIP_CHANNELS=1。
• 配置支持 JSON5、include 与 ${ENV} 变量替换。

开发工作流

常用命令

pnpm install
pnpm build
pnpm dev
pnpm gateway:dev
pnpm check
pnpm test

UI 改动流程

修改 ui/ 后：

1. 执行 pnpm ui:build
2. 重启网关，刷新 Control UI 静态资源

质量门禁

• pnpm check = 类型检查 + lint + 格式检查
• pnpm check:loc 使用仓库阈值：--max 2000 --max-function 150

测试

• 主入口：pnpm test
• 关键配置：vitest.config.ts、vitest.e2e.config.ts、vitest.gateway.config.ts、vitest.extensions.config.ts、vitest.live.config.ts
• Docker / e2e 套件位于 scripts/e2e/ 与 test:docker:* 脚本

扩展开发

• 扩展目录：extensions/<name>/
• 外部扩展请使用 opensoul/plugin-sdk 作为公开 API
• 不要从外部扩展直接导入内部 src/* 模块
• 通常包含 opensoul.plugin.json 与 index.ts

故障排查

文档

• 入门指南
• 网关配置
• 渠道
• 技能与工具
• 模型提供商
• Web 控制台

API 参考

• Gateway RPC
• 参考索引

贡献

• 贡献指南
• 行为准则
• 维护者：NJX-njx
• 贡献者：GitHub Contributors

许可证

MIT License — 详见 LICENSE。基于 OpenClaw（MIT）构建。

如果 OpenSoul 对你有帮助，欢迎在 GitHub 点亮 ⭐。