CloddsBot 是一个开源的 AI 交易终端，可以自主在预测市场、加密货币和期货市场运行。它的部署方式很灵活，对于大多数用户，官方推荐用 npm 全局安装，这是最快的方式；如果你需要更稳定的运行环境，Docker 是更好的选择。

📦 方式一：npm 全局安装（官方推荐，最快上手）

这是官方文档首推的方式，适合快速体验。

前提条件：需要 Node.js 22 或更新版本（Node.js 20 不支持，依赖安装可能会失败）。

1
2
3
4
5
# 全局安装
npm install -g clodds --loglevel=error

# 运行引导式设置向导
clodds onboard

clodds onboard 是一个交互式向导，会引导你完成 API Key 配置、消息通道选择，并自动启动网关服务。设置完成后，WebChat 界面会自动在浏览器中打开 http://localhost:18789/webchat。

🐳 方式二：Docker 部署（适合生产/长期运行）

如果你希望服务在后台稳定运行，或者不想在主机上安装 Node.js 环境，Docker 是更合适的选择。

单容器运行：

1
2
3
4
5
6
7
8
9
10
11
# 构建镜像（如果你从源码开始）
docker build -t clodds .

# 运行容器
docker run --rm \
  -p 18789:18789 \
  -e ANTHROPIC_API_KEY=sk-ant-... \
  -e TELEGRAM_BOT_TOKEN=... \
  -e WEBCHAT_TOKEN=... \
  -v clodds_data:/data \
  clodds

容器会自动将状态目录设为 /data，数据库会保存在 /data/clodds.db，备份文件在 /data/backups/。

Docker Compose（推荐）：
对于长期运行的服务，用 Compose 管理更方便。在项目根目录创建 docker-compose.yml：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
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:

然后执行 docker compose up -d --build 即可启动。

⚙️ 方式三：从源码构建（适合开发者）

如果你需要修改代码或深度定制，可以从源码开始。

1
2
3
4
5
6
7
8
9
10
11
12
13
# 克隆仓库
git clone https://github.com/alsk1992/CloddsBot.git
cd CloddsBot

# 安装依赖（建议用 npm ci 确保版本一致）
npm ci

# 复制环境变量模板
cp .env.example .env

# 编辑 .env，填入必要的 API Key（至少需要 ANTHROPIC_API_KEY）
# 然后构建并启动
npm run build && npm start

🔑 核心配置说明

无论用哪种方式部署，以下环境变量是必需的或强烈建议配置的：

变量 说明 必需性
ANTHROPIC_API_KEY Claude API 密钥，CloddsBot 的核心 AI 能力依赖它 必需
TELEGRAM_BOT_TOKEN Telegram 机器人令牌（如果你想通过 Telegram 交互） 按需
WEBCHAT_TOKEN WebChat 界面的访问令牌，用于保护你的终端不被他人访问 建议配置
SOLANA_PRIVATE_KEY Solana 钱包私钥（如果你要进行链上交易） 按需

数据默认存储在 ~/.clodds/ 目录下（SQLite 数据库会自动创建）。

🛡️ 安全要点

由于 CloddsBot 涉及真实的交易和资金操作，安全配置非常重要：

  • 从模拟运行开始：官方建议先用 dry-run 模式测试，确认策略无误后再开启真实交易。
  • 使用独立钱包：不要用你的主钱包来运行交易机器人，建议新建一个专用钱包，只存放必要的交易资金。
  • 保护 API Key：所有密钥都放在 .env 文件中，并确保该文件不会被提交到 Git 仓库。
  • 启用访问控制：如果 WebChat 需要对外访问，务必设置 WEBCHAT_TOKEN，并考虑启用 HTTPS（CLODDS_FORCE_HTTPS=true）。

✅ 验证部署

服务启动后，可以通过以下方式验证是否正常运行：

bash

1
2
# 检查系统健康状况（会检查 AI 提供商、消息通道、交易平台等）
clodds doctor

如果所有配置都正确，doctor 命令会显示各项服务的连接状态。你也可以直接访问 http://localhost:18789/health 查看服务的健康检查端点。