CloddsBot 详细部署教程

项目概述

CloddsBot 是一个开源的、自托管的 AI 交易代理，由 Claude 驱动，能够在 1000+ 个市场中自主运行。它集成了预测市场、加密货币现货、永续合约（带杠杆）、代币发行和 Bittensor 子网挖矿等功能，并可通过 21 种消息平台进行交互。

核心特性：

功能模块 说明
消息平台 21 个平台（Telegram、Discord、Slack、WhatsApp、WebChat 等）
预测市场 10 个平台（Polymarket、Kalshi、Betfair 等）
永续合约 7 个交易所（Binance、Bybit、Hyperliquid 等），最高 200x 杠杆
交易策略 118+ 种策略（动量、均值回归、DCA、鲸鱼追踪等）
风险管理 统一风险引擎，含熔断、VaR/CVaR、凯利公式等
WebChat 内置浏览器界面，支持无限历史记录和上下文压缩
技能系统 119 个内置技能，可按需懒加载
AI 系统 8 个 LLM 提供商，4 个专业代理，语义记忆
数据持久化 SQLite（本地）、LanceDB（语义记忆）、PostgreSQL（分析）

技术栈：Node.js + TypeScript + Claude API

部署前准备

系统要求

项目 最低要求 推荐配置
CPU 2 核 4 核+
内存 4 GB 8 GB+
存储 10 GB 20 GB+
操作系统 Linux / macOS / Windows (WSL2) Ubuntu 22.04

前置依赖

1
2
3
4
5
# 检查 Node.js 版本（需要 18+）
node --version

# 检查 npm
npm --version

必需的 API 密钥

根据官方部署文档，ANTHROPIC_API_KEY 是必需的：

密钥 用途 是否必需
ANTHROPIC_API_KEY Claude AI 核心 必需
SOLANA_PRIVATE_KEY Solana 交易 如需交易
TELEGRAM_BOT_TOKEN Telegram 通道 可选
DISCORD_BOT_TOKEN Discord 通道 可选
POLYMARKET_API_KEY Polymarket 交易 可选

方案一：npm 全局安装（推荐）

这是最简单的部署方式，使用交互式设置向导完成配置。

步骤 1：安装 CloddsBot

1
npm install -g clodds --loglevel=error

步骤 2：运行交互式设置向导

1
clodds onboard

向导会引导你完成 API 密钥设置、消息通道选择和配置生成。设置完成后，WebChat 将在 http://localhost:18789/webchat 打开。

步骤 3：启动网关

1
clodds start

常用 CLI 命令

根据用户指南，常用命令如下：

命令 说明
clodds onboard 交互式设置向导
clodds start 启动网关
clodds repl 交互式 REPL
clodds doctor 系统诊断
clodds secure 安全加固
clodds locale set zh 切换语言（支持 10 种语言）

方案二：从源码部署

如果你需要最新开发版本或进行二次开发，可以从源码构建。

步骤 1：克隆仓库

1
2
git clone https://github.com/alsk1992/CloddsBot.git
cd CloddsBot

步骤 2：安装依赖

1
npm ci

步骤 3：配置环境变量

1
cp .env.example .env

编辑 .env 文件，至少配置 ANTHROPIC_API_KEY：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
# 必需
ANTHROPIC_API_KEY=sk-ant-...

# 通道（任选）
TELEGRAM_BOT_TOKEN=...
DISCORD_BOT_TOKEN=...
WEBCHAT_TOKEN=...

# 交易
POLYMARKET_API_KEY=...
SOLANA_PRIVATE_KEY=...

# 数据库（默认自动创建）
CLODDS_DB_PATH=~/.clodds/clodds.db

步骤 4：构建并启动

1
2
3
4
npm run build
npm start
# 或
node dist/index.js

方案三：Docker 部署（单容器）

Docker 部署适合隔离环境或生产部署。

步骤 1：构建镜像

1
docker build -t clodds .

步骤 2：运行容器

1
2
3
4
5
6
7
docker run --rm \
  -p 18789:18789 \
  -e ANTHROPIC_API_KEY=sk-ant-... \
  -e TELEGRAM_BOT_TOKEN=... \
  -e WEBCHAT_TOKEN=... \
  -v clodds_data:/data \
  clodds

容器会设置 CLODDS_STATE_DIR=/data，因此：

  • 数据库：/data/clodds.db
  • 备份：/data/backups

方案四：Docker Compose 部署（推荐用于生产）

这是最适合生产环境的部署方式。

步骤 1：创建 docker-compose.yml

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
version: '3.8'

services:
  clodds:
    build: .
    ports:
      - "18789:18789"
    environment:
      - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}
      - TELEGRAM_BOT_TOKEN=${TELEGRAM_BOT_TOKEN}
      - WEBCHAT_TOKEN=${WEBCHAT_TOKEN}
    volumes:
      - clodds_data:/data
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:18789/health"]
      interval: 30s
      timeout: 10s
      retries: 3

volumes:
  clodds_data:

步骤 2：创建 .env 文件

1
2
3
ANTHROPIC_API_KEY=sk-ant-...
TELEGRAM_BOT_TOKEN=...
WEBCHAT_TOKEN=...

步骤 3：启动服务

1
docker compose up -d --build

步骤 4：更新服务

1
2
docker compose pull
docker compose up -d

配置说明

数据库配置

1
2
3
4
5
6
7
# SQLite（默认，自动创建）
CLODDS_DB_PATH=~/.clodds/clodds.db

# 备份设置
CLODDS_DB_BACKUP_ENABLED=true
CLODDS_DB_BACKUP_INTERVAL=86400000
CLODDS_DB_BACKUP_KEEP=7

市场索引

1
2
3
MARKET_INDEX_ENABLED=true
MARKET_INDEX_SYNC_INTERVAL=300000
MARKET_INDEX_LIMIT_PER_PLATFORM=1000

安全配置

1
2
3
4
5
6
CLODDS_FORCE_HTTPS=false
CLODDS_HSTS_ENABLED=false

# Webhook
CLODDS_WEBHOOK_SECRET=your-webhook-secret
CLODDS_WEBHOOK_REQUIRE_SIGNATURE=1

遥测配置

1
2
3
4
5
OTEL_ENABLED=true
OTEL_SERVICE_NAME=clodds
OTEL_ENDPOINT=http://localhost:4318
OTEL_METRICS_PORT=9090
OTEL_SAMPLE_RATE=1.0

WebChat 使用

CloddsBot 内置浏览器界面，无需设置，无第三方依赖：

  • 访问地址：http://localhost:18789/webchat
  • Claude 风格侧边栏：Chats、Projects、Artifacts、Code 四个标签页
  • 无限历史：每条消息存储在专用数据库表中，无消息上限
  • 上下文压缩：旧消息自动摘要，AI 不会完全忘记讨论内容
  • 会话管理：通过 REST API 创建、重命名、删除对话

安全注意事项

根据官方安全策略：

凭据安全

  • 永不提交凭据——使用环境变量
  • 使用 .env 文件——保持在 .gitignore 中
  • 定期轮换 API 密钥
  • 限制权限——尽可能使用只读密钥

交易安全

  • 从模拟模式开始——实盘交易前先测试
  • 设置损失限制——配置熔断机制
  • 使用独立钱包——不要使用主钱包
  • 监控仓位——设置大额交易警报

沙箱与动态代码执行

以下功能默认禁用：

功能 环境变量 默认值
JavaScript 沙箱 ALLOW_UNSAFE_SANDBOX false
Canvas JS 执行 CANVAS_ALLOW_JS_EVAL false

MCP 服务器安全

控制项 环境变量
工具黑名单 CLODDS_MCP_BLOCKED_TOOLS
工具白名单 CLODDS_MCP_ALLOWED_TOOLS
速率限制 CLODDS_MCP_RATE_LIMIT

常用功能命令

MCP 服务器命令

1
2
clodds mcp         # 启动 MCP 服务器（用于 Claude Desktop/Code）
clodds mcp install # 自动配置 Claude Desktop/Code

QMD（量化市场数据）命令

1
2
3
4
5
clodds qmd get <target>         # 获取市场数据
clodds qmd polymarket <query>   # 搜索 Polymarket
clodds qmd kalshi <query>       # 搜索 Kalshi
clodds qmd metaculus <query>    # 搜索 Metaculus
clodds qmd manifold <query>     # 搜索 Manifold

交易账本命令

1
2
3
4
clodds ledger stats              # 显示决策统计
clodds ledger calibration        # 置信度与准确度分析
clodds ledger verify <id>        # 验证记录完整性
clodds ledger anchor <id>        # 锚定哈希到 Solana

启用账本：

1
clodds config set ledger.enabled true

Bittensor 挖矿命令

1
2
3
4
clodds bittensor setup           # 交互式向导
clodds bittensor status          # 检查挖矿状态
clodds bittensor wallet balance  # 检查 TAO 余额
clodds bittensor register 64     # 注册到 Chutes (SN64)

常见问题排查

问题 解决方案
缺少 ANTHROPIC_API_KEY 这是必需项，在 .env 中配置
配置更改不生效 编辑 .env 或 clodds.json 后重启机器人
WebChat 无法访问 检查端口 18789 是否被占用，确认容器运行状态
模型列表过时 已知问题，等待更新或手动配置模型
Docker 容器无法启动 检查环境变量是否正确传递
数据丢失 确保 clodds_data 卷正确挂载

诊断命令

1
2
3
4
5
# 系统诊断
clodds doctor

# 详细诊断
clodds doctor --verbose

clodds doctor 会检查 AI 提供商、消息通道、交易平台、外部服务和 Bittensor 依赖。

数据持久化

数据默认存储在 ~/.clodds/ 目录：

文件 说明
clodds.db SQLite 数据库（WebChat、交易历史）
backups/ 自动备份

备份建议：定期备份 ~/.clodds/ 目录，尤其是包含 SOLANA_PRIVATE_KEY 的配置文件。

总结

部署方式 适用场景 难度 推荐度
npm 全局安装 快速上手 ⭐ ⭐⭐⭐⭐⭐
从源码部署 开发/定制 ⭐⭐⭐ ⭐⭐⭐
Docker 单容器 隔离环境 ⭐⭐ ⭐⭐⭐⭐
Docker Compose 生产环境 ⭐⭐ ⭐⭐⭐⭐⭐

对于大多数用户，npm 全局安装是最简单直接的选择：

1
2
3
4
5
6
7
8
9
10
# 安装
npm install -g clodds --loglevel=error

# 配置
clodds onboard

# 启动
clodds start

# 访问 http://localhost:18789/webchat

对于生产环境，推荐使用 Docker Compose 部署，便于管理和更新。务必配置 ANTHROPIC_API_KEY，并根据需要添加交易平台的 API 密钥。请始终使用独立钱包并启用模拟模式进行测试。