convez.ai
MCP ServerAutomaçãoAvançado
while-coder

sbot — Servidor de Agentes IA Auto-hospedado

while-coder/sbot

Plataforma modular para agentes IA com múltiplos canais e ferramentas MCP

Ver no GitHub
BomPluginScore · de 0 a 100

Framework open-source para construir agentes IA multi-LLM (OpenAI, Claude, Ollama) com suporte a ferramentas MCP, memória de longo prazo, arquitetura ReAct multi-agente e integrações com Lark, Feishu, WeChat. Oferece UI web integrada e controle total via servidor próprio, sem aprisionamento por vendor.

Instalação

$npx convez-ai while-coder/sbot

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
8
Forks
1
Acompanhando
0
Saúde
42%
Último commit
há 1 mês
Versão
sbot-v0.3.0
Issues abertas
1
Contribuidores
3

Casos de uso

  • Executar agentes IA privados em infraestrutura própria
  • Integrar múltiplos LLMs (OpenAI, Claude, Ollama) em um único agente
  • Orquestrar comunicação via Slack, WeChat, Lark e outros canais
  • Construir assistentes com memória persistente e raciocínio multi-agente

Veredito

sbot é uma solução robusta para quem precisa de controle total sobre agentes IA em produção. Destaca-se pela modularidade (modelos, memória, ferramentas plugáveis) e suporte a MCP, mas exige experiência com TypeScript e DevOps para aproveitar plenamente.

README

A tradução para o português deste README ainda está na fila.

sbot — Self-hosted AI Agent Server

English | 中文

npm version npm downloads Node.js License: MIT

Open-source, self-hosted AI agent framework. Modular by design: models, memory, tools, and channels are independent building blocks you mix and match to assemble agents — run on your own server with multi-channel integrations, MCP tool support, and a built-in web UI, no vendor lock-in.


Quick Start

npm

# Install
npm install -g @qingfeng346/sbot

# Start (foreground), then open http://localhost:5500
sbot

# Start in the background (survives terminal close)
sbot -d

# Start on a specific port (when 5500 is taken; -p and -d can be combined)
sbot -p 3000
sbot -d -p 3000

# Save the port only, do not start
sbot port 3000

Full command reference:

CommandDescription
sbotStart the service (foreground)
sbot -d / --daemonStart in the background (survives terminal close)
sbot -p <port> / --portStart on the given port, e.g. sbot -p 3000
sbot port <port>Save the port without starting
sbot stopStop the running service
sbot statusShow running state, port, auto-start, version, config directory
sbot -v / --versionShow version and check for updates
sbot startup enableEnable launch at boot
sbot startup disableDisable launch at boot
sbot startup statusCheck auto-start status

If npm install -g fails with EACCES: permission denied, don't fix it with sudo — it leads to tangled file ownership later. The clean fix is to point npm at a directory inside your home folder, so global installs never touch system paths.

One-liner (recommended, auto-detects zsh / bash — paste the whole block into your terminal):

mkdir -p ~/.npm-global && \
npm config set prefix '~/.npm-global' && \
RC_FILE=$([ "${SHELL##*/}" = "bash" ] && echo ~/.bash_profile || echo ~/.zshrc) && \
grep -q '.npm-global/bin' "$RC_FILE" 2>/dev/null || echo 'export PATH=~/.npm-global/bin:$PATH' >> "$RC_FILE" && \
source "$RC_FILE" && \
echo "✓ Done. You can now run: npm install -g @qingfeng346/sbot"

Manual steps (if you want to understand each step):

# 1. Create a user-level global directory
mkdir ~/.npm-global

# 2. Point npm to it (so global installs go here instead of system paths)
npm config set prefix '~/.npm-global'

# 3. Add it to your PATH so the shell can find global commands
#    zsh (default on macOS):
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.zshrc && source ~/.zshrc
#    bash:
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bash_profile && source ~/.bash_profile

Then re-run npm install -g @qingfeng346/sbot.

Docker

docker pull qingfeng346/sbot
docker run -d \
  -p 5500:5500 \
  -v ~/.sbot:/root/.sbot \
  --name sbot \
  qingfeng346/sbot
# Open http://localhost:5500

Configuration and data are persisted in ~/.sbot on the host.

Docker Compose

For long-running deployments where you want pinned versions and one-command upgrades. Create docker-compose.yml:

services:
  sbot:
    image: qingfeng346/sbot
    container_name: sbot
    ports:
      - "5500:5500"
    volumes:
      - ~/.sbot:/root/.sbot
    environment:
      - TZ=Asia/Shanghai
      - LOG_LEVEL=INFO
    restart: unless-stopped

Common commands:

docker compose up -d            # start in background
docker compose logs -f          # follow logs
docker compose down             # stop & remove container (data stays in ~/.sbot)
docker compose pull && docker compose up -d   # upgrade to latest image

Features

  • Modular composition — Models, memory, tools, channels, and skills are independent building blocks you mix and match to assemble agents
  • One-command deployment — npm install -g or docker run, native cross-platform with no extra system dependencies
  • Full Web UI management — All configuration done in the browser, no manual file editing required
  • Multiple LLM providers — OpenAI, Anthropic Claude, Google Gemini, Ollama, and any OpenAI-compatible API (Azure OpenAI, Groq, Mistral, DeepSeek, etc.); automatic retry with exponential backoff on transient failures
  • Multi-agent orchestration — Single, ReAct (recursive task decomposition), and Generative (multimodal) modes; agents can be nested and composed
  • ACP agent support — Agent Client Protocol integration with persistent and transient agent modes
  • Knowledge base — Built-in wiki system with hybrid keyword + semantic search, referenced by agents during conversations
  • Long-term memory — Vector-embedding semantic search for persistent context recall (OpenAI, Google, Ollama, Cohere, VoyageAI)
  • Conversation compaction — Automatic conversation summarization when token usage exceeds threshold, preserving continuity while reducing consumption
  • Insight system — Per-agent silent post-turn extractor that distills user preferences and lessons learned into reusable Markdown notes; auto-marks notes stale and archives them based on usage
  • Heartbeat — Configurable periodic self-activation lets agents run scheduled prompts proactively across any channel
  • MCP tools — Standard MCP protocol (stdio/SSE), connect to any MCP tool ecosystem; per-agent and global servers with auto-restart
  • Multiple channels — Web UI, CLI, Lark/Feishu, Slack, WeCom, WeChat, DingTalk, QQ (official bot), OneBot (v11 reverse WebSocket), XiaoAI, REST API, WebSocket
  • Built-in tools — Shell execution, file system, archive operations, media file read, Python/PowerShell inline execution, web fetch/download, cron scheduler, todo
  • Skills — Installable prompt modules with remote install from Clawhub, skills.sh, and skillhub.cn
  • Agent Store — Browse and install pre-packaged agents (model + prompt + tools + skills + MCP servers) from configurable sources
  • Token usage tracking — Per-model consumption statistics, model response caching with hit/miss metrics
  • Unattended-session safety — Configurable approval and ask timeouts on channels for autonomous operation
  • Flexible config — Global and per-session overrides from a single settings.json; customizable prompts with hot reload

Usage Guide

Open http://localhost:5500 after starting sbot. Follow these steps:

1. Add a Model — sidebar → Models → New

Fill in provider, API key, base URL, and model name. Supported providers: OpenAI, Anthropic, Google Gemini, Ollama, and any OpenAI-compatible endpoint (Azure OpenAI, Groq, Mistral, DeepSeek, etc.).


2. Create a Saver — sidebar → Savers → New

Choose a backend for storing conversation history:

BackendDescription
FileJSON files per conversation thread (recommended)
SQLiteLocal SQLite database
MemoryCleared after conversation ends, no persistence, suitable for one-off conversations or Q&A assistants

3. Create an Agent — sidebar → Agents → New

Choose a mode:

  • Single — select a model, write a system prompt, optionally attach MCP tools and skills
  • ReAct — select a think model, then add sub-agents (each with an id and description for task dispatch). The think model decomposes tasks and dispatches sub-tasks recursively; each sub-agent has read-only access to shared memory
  • Generative — select a multimodal model for mixed text and image content generation

→ MCP Tools · Skills


4. Start chatting — choose your entry point

  • Session — sidebar → Chat → New Session, select agent + saver + memory; optionally configure a working directory
  • Channel (IM) — sidebar → Channels → New → Channel Setup; optionally configure a working directory

5. (Optional) Enable Wiki Knowledge Base — sidebar → Wiki → New

Built-in knowledge base. Create pages manually (title + content + tags). Assign wikis to a session or channel; agents can search, read, write, and update pages via built-in tools. An optional embedding model enables semantic search alongside keyword matching.

FieldDescription
NameWiki identifier
EmbeddingOptional — enables semantic search; without it, falls back to keyword search

6. (Optional) Enable Memory — sidebar → Memories → New

A vector store the agent can write to and search via tool calls. Requires an embedding model first (sidebar → Embeddings → New), then assign the memory to a session or channel. Entries are time-decay weighted on retrieval and de-duplicated on insert.

FieldDescription
NameMemory identifier
EmbeddingEmbedding model for semantic search (OpenAI, Google, Ollama, Cohere, VoyageAI)

7. (Optional) Enable Insight on an agent — Agent edit page → Insight section

Insight is a silent post-turn extractor that runs after every conversation turn and distills durable knowledge — user preferences, project facts, lessons learned — into reusable Markdown notes (SKILL.md files under ~/.sbot/insights/). Relevant insights are auto-injected back into the system prompt on subsequent turns via hybrid keyword + semantic search.

FieldDescription
ScopeDisabled / Per Agent (shared across all sessions of this agent) / Per Session (isolated per thread)
Extraction ModelModel used to run the post-turn extraction (typically a cheap, fast model)
Extraction PromptPrompt file from ~/.sbot/prompts/insight/extractor/ controlling what is extracted

The extractor can create, patch, or delete insights based on conversation evolution. Stale notes (default 30 days unused) are marked, and unused notes (default 90 days) are auto-archived.


8. (Optional) Install pre-packaged agents — sidebar → Agent Store

Browse and install agents from configurable registries. Each package bundles model selection, system prompt, skills, and MCP server configuration in one click. Add custom registry URLs in Settings.


Add MCP Tools

Sidebar → MCP → New

Add a server:

  • stdio — command + args (e.g. npx -y some-mcp-package)
  • sse — remote URL + optional headers

Supports global servers shared across all agents and per-agent overrides. Servers auto-restart on failure. Then open an agent → MCP tab to attach the servers you want it to use.


Manage Skills

Sidebar → Skills

Skill files (Markdown) are stored in ~/.sbot/skills/. Search and install from remote hubs (Clawhub, skills.sh, skillhub.cn) on the Skills page, or drop files manually. In an agent → Skills tab, select specific skills to load, or leave empty to load all.


Customize Prompts

Sidebar → Prompts

View and edit any built-in prompt (system prompts, agent prompts, tool descriptions, etc.). Saved overrides are stored in ~/.sbot/prompts/ and take precedence over the defaults, effective immediately without restart. Supports {varName} placeholders substituted at runtime.


Heartbeat (Proactive Activation)

Sidebar → Heartbeat

Configure periodic prompts that wake an agent on a fixed interval — useful for monitoring, daily summaries, or scheduled outreach. Each heartbeat targets a specific channel or session and runs a prompt template. Combine with the Scheduler tool for one-off tasks.


Channel Setup

In Channels → New, select the type and fill in the credentials, then assign agent + saver + memory. Every user/group chat is isolated automatically.

TypeRequired fields
Lark / FeishuApp ID, App Secret
SlackBot Token (xoxb-...), App Token (xapp-...)
WeComBot ID, Secret
WeChatQR code login (credentials auto-populated)
DingTalkClient ID, Client Secret (a.k.a. AppKey / AppSecret, Stream mode)
QQApp ID, Client Secret (QQ Bot Open Platform, WebSocket Gateway)
OneBotWS port (default 6700), optional Access Token; reverse WebSocket, pairs with NapCat / go-cqhttp

Setting up Lark / Feishu:

  1. Create a bot app in the Feishu Developer Console (or Lark Developer Console for international)
  2. Enable Bot capability
  3. Grant the following permissions under Permissions & Scopes (or use Batch Import with the JSON below):
PermissionDescription
im:message:send_as_botSend messages as bot
im:message.p2p_msg:readonlyReceive direct messages
im:message.group_at_msg:readonlyReceive group @bot messages
im:message.group_msgReceive all group messages
im:message:readonlyRead message content
im:chat:readonlyRead chat/group info
im:resourceRead files and images in messages
contact:user.base:readonlyRead basic user info
contact:contact.base:readonlyRead basic contact info
{
  "scopes": {
    "tenant": [
      "contact:contact.base:readonly",
      "contact:user.base:readonly",
      "im:chat:readonly",
      "im:message.group_at_msg:readonly",
      "im:message.group_msg",
      "im:message.p2p_msg:readonly",
      "im:message:readonly",
      "im:message:send_as_bot",
      "im:resource"
    ],
    "user": []
  }
}
  1. Under Events & Callbacks, set the subscription mode to Long Connection
  2. In Web UI → Channels, create a Lark channel and fill in App ID and App Secret

Supports event deduplication, interactive cards, per-user context isolation, and file/image send and receive.

Setting up WeCom:

  1. Create an AI app in the WeCom Admin Console and obtain the Bot ID and Secret
  2. In Web UI → Channels, create a WeCom channel and fill in Bot ID and Secret

Connects via WebSocket for real-time messaging, with file and image support.

Setting up WeChat:

  1. In Web UI → Channels, create a WeChat channel
  2. Click QR login and scan the code with WeChat to authenticate
  3. Credentials are saved automatically once authenticated, and the channel goes live immediately

WeChat integration connects via the iLink Bot API, with file and image support.


Built-in Tools

Command Execution

  • Shell commands and scripts
  • Inline Python and PowerShell execution
  • File-referenced script execution
  • Configurable timeout per command

File System

  • Read, write, edit files
  • Search with regex (grep)
  • Find files by pattern (glob)
  • Directory listing, create, remove, move, copy
  • Read media files (images, etc.)
  • Optional read-only mode per agent

Archive

  • Compress and extract archive files
  • List archive contents
  • Read files directly from within archives

Web

  • Fetch URLs and convert HTML to clean Markdown
  • Download files from the web

Scheduler

  • Standard 6-field cron expressions (second minute hour day month weekday), persisted across restarts
  • Tasks can target a channel user, a web session, or a working directory
  • Optional max run count with auto-cleanup
  • Manageable via the Web UI or by asking the agent directly

Todo

  • A post-turn extractor automatically detects todos from conversations and applies create / patch / done / delete actions
  • Agents can query current todos via the todo_list tool (read-only)
  • Web UI provides a Todo management page

Ask

  • Agents can pause mid-task and ask the user structured questions
  • Supported question types: single-select, multi-select, text input
  • Works across Web UI and Lark; the agent resumes automatically after the user responds

Keywords

ai agent self-hosted llm server open source mcp acp model context protocol multi-agent react agent openai claude anthropic gemini ollama chatbot lark feishu onebot qq long-term memory vector search typescript node.js

Ver o original no GitHub

Bom para

Relacionados