Piagent

轻量级多通道 AI 智能体网关 - OpenClaw 的简洁替代方案

简介

Piagent 是一个轻量级多通道 AI 智能体网关，功能类似于 OpenClaw，但设计更简洁、部署更轻量。它让你的 AI 代理能够无缝连接各种即时通讯平台（Telegram、Discord、Slack 等），并提供统一的 Web 管理界面。

与 OpenClaw 对比

| 特性 | Piagent | OpenClaw | |------|---------|----------| | 架构复杂度 | 极简，单进程运行 | 微服务架构，多组件 | | 资源占用 | 轻量，适合边缘部署 | 需要更多服务器资源 | | 配置方式 | 单文件 YAML 配置 | 多配置文件，环境变量 | | 部署难度 | 一行命令启动 | 需要 Docker/K8s 编排 | | 扩展方式 | 插件式频道适配器 | 完整的插件系统 | | 核心功能 | 多平台接入、智能路由、会话管理 | 相同 |

选择 Piagent，如果你需要：

• 快速部署一个 AI 网关，无需复杂的基础设施
• 在资源受限的环境（如 VPS、边缘设备）运行
• 简单的配置文件管理，不牺牲核心功能
• 轻量级但功能完整的多通道 AI 代理方案

功能特性

• 🤖 多代理管理 - 配置和管理多个 AI 代理，每个代理可独立配置模型、技能和工具
• 📱 多平台支持 - 同时连接 Telegram、Discord、Slack 等即时通讯平台
• 🔒 访问控制 - 灵活的访问控制策略（配对模式、白名单、开放访问）
• 🌐 Web 管理界面 - 内置 Web UI 用于管理和监控网关状态
• 🔌 WebSocket 实时通信 - 支持实时双向通信
• 💾 会话管理 - 自动会话历史管理和压缩
• 🛠️ 工具调用 - 支持 AI 代理执行各种工具任务
• 📦 可选沙箱 - 按需启用代码执行沙箱环境
• ⚡ 一键启动 - 无需依赖外部服务，单命令启动完整网关

快速开始

安装

# 使用 npm 全局安装
npm install -g piagent

# 或使用 npx 直接运行
npx piagent config init

1. 初始化配置

piagent config init

这将在 ~/.piagent/piagent.yaml 创建默认配置文件。

2. 配置 AI 代理

编辑配置文件 ~/.piagent/piagent.yaml：

agents:
  - id: my-assistant
    name: 智能助手
    model:
      provider: anthropic
      model: claude-3-5-sonnet-20241022
    systemPrompt: 你是一个 helpful 的 AI 助手
    skills:
      - coding
      - file-management

3. 添加通讯频道

Telegram 频道

piagent channel add telegram

然后在配置文件中添加 Bot Token。

Discord 频道

piagent channel add discord

Slack 频道

piagent channel add slack

4. 启动网关

piagent gateway start

网关将在 http://localhost:18789 启动，WebSocket 路径为 /ws。

CLI 命令

网关管理

piagent gateway start    # 启动网关服务器
piagent gateway status   # 查看网关状态

配置管理

piagent config init      # 初始化配置
piagent config show      # 显示当前配置
piagent config validate  # 验证配置
piagent config path      # 显示配置文件路径

代理管理

piagent agent create <id>    # 创建新代理
piagent agent list           # 列出所有代理
piagent agent delete <id>    # 删除代理

频道管理

piagent channel add <type>     # 添加频道 (telegram/discord/slack)
piagent channel list           # 列出所有频道
piagent channel remove <type>  # 移除频道

诊断工具

piagent doctor           # 运行诊断检查

配置文件详解

完整的配置示例：

version: "1.0"

gateway:
  port: 18789                    # 网关端口
  wsPath: /ws                    # WebSocket 路径
  publicDir: ./public            # 静态文件目录
  sessionDir: ~/.piagent/sessions  # 会话存储目录
  debug: false                   # 调试模式
  corsOrigins: ["*"]             # CORS 允许的来源

# 节点发现配置（可选）
node:
  enabled: false
  discovery:
    mdns: true                   # mDNS 发现
    tailnet: false               # Tailscale 发现

# 代理定义
agents:
  - id: assistant
    name: AI 助手
    description: 通用 AI 助手
    model:
      provider: anthropic
      model: claude-3-5-sonnet-20241022
    systemPrompt: 你是一个 helpful 的 AI 助手
    skills:
      - coding
      - web-search
    tools:
      allow: ["read_file", "write_file", "execute_command"]
    sandbox:
      enabled: true
      workspace: ./workspace
    session:
      historyLimit: 100          # 历史消息限制
      idleMinutes: 60            # 空闲超时（分钟）
      compression: summary       # 历史压缩模式
      queuing: sequential        # 消息队列模式

# 频道配置
channels:
  - type: telegram
    name: tg-bot
    enabled: true
    config:
      botToken: "${TELEGRAM_BOT_TOKEN}"
    access:
      dmPolicy: pairing          # 私信策略: pairing/allowlist/open
      groupPolicy: mention       # 群组策略: mention/allowlist/open

  - type: discord
    name: dc-bot
    enabled: true
    config:
      botToken: "${DISCORD_BOT_TOKEN}"
      applicationId: "${DISCORD_APP_ID}"
      intents: 33281
    access:
      dmPolicy: pairing
      groupPolicy: mention

  - type: slack
    name: slack-bot
    enabled: true
    config:
      botToken: "${SLACK_BOT_TOKEN}"
      appToken: "${SLACK_APP_TOKEN}"
      socketMode: true
    access:
      dmPolicy: pairing
      groupPolicy: mention

# 频道绑定
bindings:
  - agentId: assistant
    channel: tg-bot
    bindType: default            # default/peer/guild/team/account/channel
    bindValue: "*"
    access:
      dmPolicy: pairing
      groupPolicy: mention

# 默认配置
defaults:
  agent: assistant
  model:
    provider: anthropic
    model: claude-3-5-sonnet-20241022

环境变量

Piagent 支持以下环境变量：

| 变量名 | 说明 | |--------|------| | PIAGENT_CONFIG | 配置文件路径 | | TELEGRAM_BOT_TOKEN | Telegram Bot Token | | DISCORD_BOT_TOKEN | Discord Bot Token | | DISCORD_APP_ID | Discord Application ID | | SLACK_BOT_TOKEN | Slack Bot Token (xoxb-) | | SLACK_APP_TOKEN | Slack App Token (xapp-) | | ANTHROPIC_API_KEY | Anthropic API Key | | OPENAI_API_KEY | OpenAI API Key |

编程 API

作为库使用

import { Gateway, ConfigManager, SessionManager } from 'piagent';

// 加载配置
const configManager = await ConfigManager.create();
await configManager.load();

// 创建会话管理器
const sessionManager = new SessionManager({
  sessionDir: configManager.getGatewayConfig().sessionDir,
});
await sessionManager.initialize();

// 创建并启动网关
const gateway = new Gateway({ configManager, sessionManager });
await gateway.start();

console.log(`Gateway started on port ${configManager.getGatewayConfig().port}`);

自定义频道适配器

import { BaseChannelAdapter, globalChannelRegistry } from 'piagent';

class MyCustomAdapter extends BaseChannelAdapter {
  readonly channelType = 'custom';

  async initialize(): Promise<void> {
    // 初始化逻辑
  }

  async shutdown(): Promise<void> {
    // 清理逻辑
  }

  async send(message: OutboundMessage): Promise<void> {
    // 发送消息逻辑
  }

  async getProfile(): Promise<ChannelProfile> {
    // 返回频道信息
  }
}

// 注册适配器
globalChannelRegistry.register('custom', MyCustomAdapter);

系统要求

• Node.js >= 20.0.0
• npm >= 10.0.0

平台特定配置

Telegram

1. 在 Telegram 中搜索 @BotFather
2. 发送 /newbot 创建新机器人
3. 按照提示设置名称和用户名
4. 保存获取到的 Bot Token

Discord

1. 访问 Discord Developer Portal
2. 创建新应用
3. 在 Bot 页面添加 Bot 用户
4. 获取 Bot Token 和 Application ID
5. 启用必要的 Intents（Message Content Intent 等）

Slack

1. 访问 Slack API
2. 创建新应用
3. 启用 Socket Mode
4. 添加 Bot Token Scopes: chat:write, app_mentions:read, im:history 等
5. 获取 Bot Token (xoxb-) 和 App Token (xapp-)

故障排除

检查配置

piagent doctor

常见问题

Q: 无法启动网关

• 检查端口是否被占用
• 查看配置文件语法是否正确
• 运行 piagent doctor 诊断问题

Q: Telegram 收不到消息

• 确认 Bot Token 正确
• 检查是否已向 Bot 发送 /start

Q: Discord 消息无响应

• 确认 Intents 设置正确
• 检查 Bot 是否有频道权限

Q: Slack 连接失败

• 确认使用 Socket Mode
• 检查 App Token 格式（以 xapp- 开头）

开发

# 克隆仓库
git clone https://github.com/badlogic/pi-mono.git
cd pi-mono/packages/piagent

# 安装依赖
npm install

# 构建
npm run build

# 运行测试
npm test

许可证

MIT License - 详见 LICENSE 文件

相关项目

• Pi AI - 统一的多提供商 LLM API
• Pi Agent Core - 代理运行时
• Pi Coding Agent - 交互式编码代理

作者

Mario Zechner

如有问题或建议，欢迎提交 Issue 或 PR！