hummingbot-developer
Developer workflow skill for building and running the full Hummingbot stack from source.
Commands (run as /hummingbot-developer <command>):
| Command | Description |
|---|
| INLINECODE1 | Check dev environment status |
| INLINECODE2 |
Pick branches for all 3 repos |
|
install-all | Install all 3 repos in order |
|
build-all | Build wheel + all Docker images |
|
verify-build | Verify builds are correct + in sync |
|
run-dev-stack | Start full stack from source |
|
setup-hummingbot | Install Hummingbot from source |
|
run-hummingbot | Run Hummingbot CLI from source |
|
build-hummingbot | Build wheel + Docker image |
|
setup-gateway | Install Gateway from source |
|
run-gateway | Run Gateway in dev mode |
|
build-gateway | Build Gateway Docker image |
|
setup-api-dev | Wire API to local Hummingbot source |
|
run-api-dev | Run API from source with hot-reload |
|
test-integration | Smoke test the full stack |
Typical dev workflow:
CODEBLOCK0
Repo locations (all in workspace):
| Repo | Path |
|---|
| hummingbot | INLINECODE16 |
| gateway |
~/.openclaw/workspace/hummingbot-gateway |
| hummingbot-api |
~/.openclaw/workspace/hummingbot-api |
Override with env vars: HUMMINGBOT_DIR, GATEWAY_DIR, HUMMINGBOT_API_DIR, or WORKSPACE.
Command: install-deps
Auto-install all missing dev dependencies. Safe to re-run — skips anything already installed.
CODEBLOCK1
Installs (only if missing):
- - Homebrew (macOS)
- Xcode Command Line Tools (macOS — needed for Cython
build_ext) - Miniconda (conda)
- Node.js v22 (via nvm, Homebrew, or installs nvm)
- pnpm (via npm or Homebrew)
- Git
- Docker Desktop (macOS — via Homebrew cask or opens download page)
Options:
CODEBLOCK2
After installing, restart your terminal (or source ~/.zshrc) to apply PATH changes, then run check_env.sh to confirm.
Command: select-branches
Interactively pick a branch for each repo, checkout, and save to .dev-branches.
CODEBLOCK3
Non-interactive options:
CODEBLOCK4
Branch selections are saved to $WORKSPACE/.dev-branches and automatically loaded by install_all.sh, build_all.sh, and verify_build.sh.
Command: install-all
Install all three repos in the correct order. Requires select-branches first (or pass --defaults).
CODEBLOCK5
What it does (in order):
- 1. Removes
solders from environment.yml (pip-only) - INLINECODE35 in hummingbot → INLINECODE36
- INLINECODE37 into hummingbot env
- INLINECODE38 for gateway
- INLINECODE39 for hummingbot-api
- INLINECODE40 → wires local source into API env
Options:
--skip-hbot # skip hummingbot conda install
--skip-gateway # skip gateway pnpm install
--skip-api # skip hummingbot-api install
--no-local-hbot # use PyPI hummingbot in API env instead of local source
Command: build-all
Build hummingbot wheel and all Docker images in the correct order.
CODEBLOCK7
Build order:
- 1.
hummingbot wheel (dist/*.whl) via INLINECODE43 - INLINECODE44 Docker image
- INLINECODE45 Docker image (also rebuilds dist/)
- INLINECODE46 Docker image
Each image is also tagged with the branch name (e.g., hummingbot/gateway:core-2.7).
Options:
--wheel-only # only build hummingbot wheel, no Docker
--no-docker # skip all Docker builds
--no-hbot # skip hummingbot builds
--no-gateway # skip gateway builds
--no-api # skip hummingbot-api builds
--tag <name> # Docker tag (default: dev)
Command: verify-build
Verify that all builds are correct and in sync.
CODEBLOCK9
Checks:
- 1. Each repo is on the expected branch (from
.dev-branches) - Hummingbot wheel exists in INLINECODE49
- Gateway
dist/ is built and not stale vs source - Local hummingbot source is active in hummingbot-api env
- Docker images exist with correct branch labels
- Running services (API + Gateway) are reachable
- API → Gateway connectivity
CODEBLOCK10
Command: run-dev-stack
Start the full dev stack from source.
CODEBLOCK11
Start order:
- 1. Docker infra (postgres + EMQX) via INLINECODE51
- Gateway from source in background (
node dist/index.js --passphrase=hummingbot --dev) - Hummingbot API from source in foreground (
uvicorn main:app --reload)
Options:
CODEBLOCK12
Logs:
- - Gateway logs: INLINECODE54
- API logs: printed to terminal (foreground)
Command: start
Check the full dev environment and show a status summary.
Step 1: Run environment check
CODEBLOCK13
Step 2: Check repo branches
CODEBLOCK14
Step 3: Check running services
CODEBLOCK15
Step 4: Show status checklist
Present a checklist like:
CODEBLOCK16
Adapt to actual state. If all good, show the test command.
Command: setup-hummingbot
Install Hummingbot from source on the development branch.
Step 1: Check prereqs
CODEBLOCK17
Step 2: Checkout development branch
CODEBLOCK18
Step 3: Remove solders from environment.yml (pip-only package)
CODEBLOCK19
Step 4: Install conda environment
CODEBLOCK20
This creates the hummingbot conda env. Takes 3-10 minutes on first run.
Step 5: Install solders via pip (not on conda)
CODEBLOCK21
Interpreting output
| Output | Meaning | Next step |
|---|
| INLINECODE57 succeeds | Dev install registered | Proceed |
| INLINECODE58 |
Forgot step 3 | Run sed + reinstall |
|
Error: Conda is not found | conda not in PATH |
source ~/.zshrc or install Anaconda |
|
build_ext errors | Missing build tools | Install Xcode CLT:
xcode-select --install |
After setup
CODEBLOCK22
Command: run-hummingbot
Run the Hummingbot CLI from source.
CODEBLOCK23
Or via make:
CODEBLOCK24
Note: This opens the interactive Hummingbot CLI. Use exit to quit.
To run with a specific config:
make run ARGS="--config-file-name conf_pure_mm_1.yml"
Command: build-hummingbot
Build a Hummingbot wheel and/or Docker image from source.
Build wheel (for local pip installs)
CODEBLOCK26
Wheel is output to dist/hummingbot-*.whl.
Important: The wheel must be built with Python 3.12 to match hummingbot-api's environment.
Use this wheel to install into other envs:
CODEBLOCK27
Build Linux wheel for Docker
When building hummingbot-api Docker images, you need a Linux wheel (not macOS/Windows). Build inside Docker to ensure compatibility:
CODEBLOCK28
Platform wheel suffixes:
- -
linux_x86_64 — Linux AMD/Intel 64-bit - INLINECODE66 — Linux ARM64 (Apple Silicon Docker, AWS Graviton)
- INLINECODE67 — macOS Apple Silicon (native only, NOT for Docker)
- INLINECODE68 — macOS Intel (native only, NOT for Docker)
Build Docker image
CODEBLOCK29
Or with make (also cleans first):
CODEBLOCK30
Tag for use with hummingbot-api:
CODEBLOCK31
Interpreting output
| Output | Meaning |
|---|
| INLINECODE69 + wheel path | Wheel ready in INLINECODE70 |
| INLINECODE71 |
Docker image ready |
|
build_ext error | Cython compile issue — check conda env is active |
| OOM during Docker build | Add
--memory 4g flag |
Command: setup-gateway
Install and configure Gateway from source.
Step 1: Check prereqs
Requires Node.js 20+, pnpm, and git.
CODEBLOCK32
Step 2: Checkout development branch
CODEBLOCK33
Step 3: Install dependencies
CODEBLOCK34
If you see USB HID errors on macOS:
CODEBLOCK35
Step 4: Build TypeScript
CODEBLOCK36
Step 5: Run setup
CODEBLOCK37
Setup creates:
- -
conf/ — chain, connector, token, and RPC configs - INLINECODE75 — TLS certificates (self-signed for dev)
Interpreting output
| Output | Meaning | Next step |
|---|
| INLINECODE76 | Ready to start | INLINECODE77 |
| INLINECODE78 errors |
TypeScript compile error | Check Node version (
node --version ≥ 20) |
|
pnpm: command not found | pnpm not installed |
npm install -g pnpm |
|
ENOSPC | Disk space | Free up space |
Command: run-gateway
Run Gateway from source in dev mode (HTTP, no TLS).
CODEBLOCK38
Default passphrase matches hummingbot-api setup: INLINECODE83
CODEBLOCK39
What --dev does:
- - Runs in HTTP mode (no TLS) on port 15888
- Enables verbose logging
- Hummingbot API auto-connects at INLINECODE85
Verify it's running:
CODEBLOCK40
Watch logs for startup sequence:
CODEBLOCK41
Configure custom RPC (recommended to avoid rate limits):
# After gateway is running, update RPC via API
curl -X POST http://localhost:15888/network/config \
-H "Content-Type: application/json" \
-d '{"chain": "solana", "network": "mainnet-beta", "nodeURL": "https://your-rpc.com"}'
Command: build-gateway
Build a Gateway Docker image from source.
CODEBLOCK43
Tag as development for use with hummingbot-api:
CODEBLOCK44
Verify image:
docker run --rm hummingbot/gateway:dev node -e "console.log('OK')"
Command: setup-api-dev
Configure Hummingbot API to use a local Hummingbot source build instead of the PyPI package.
This lets you make changes to Hummingbot and immediately test them via the API without rebuilding Docker images.
Step 1: Install hummingbot-api conda environment
CODEBLOCK46
This creates the hummingbot-api conda env with the PyPI version of hummingbot.
Step 2: Install local Hummingbot into hummingbot-api env
Option A — Editable install (recommended for active development):
CODEBLOCK47
Changes to hummingbot source are reflected immediately (no reinstall needed).
Option B — Wheel install (for testing a specific build):
CODEBLOCK48
Step 3: Verify local version is active
CODEBLOCK49
Should print a path inside <HUMMINGBOT_DIR>, not site-packages.
Step 4: Install solders
CODEBLOCK50
Interpreting output
| Output | Meaning |
|---|
| Path inside your hummingbot dir | ✅ Local source active |
| Path inside INLINECODE89 |
❌ Still using PyPI version |
|
ImportError: No module named hummingbot | pip install failed — retry |
Command: run-api-dev
Run Hummingbot API from source with hot-reload, using local Hummingbot.
Step 1: Start infrastructure (postgres + EMQX via Docker)
CODEBLOCK51
Verify they're healthy:
CODEBLOCK52
Step 2: Run the API with uvicorn hot-reload
CODEBLOCK53
Or via make:
CODEBLOCK54
API is available at http://localhost:8000
Swagger UI at INLINECODE92
What hot-reload means: Changes to *.py files in hummingbot-api are applied immediately. Changes to hummingbot source (editable install) are also picked up on reload.
Step 3: Confirm local hummingbot is in use
CODEBLOCK55
Check API logs for hummingbot version on startup.
Useful dev commands
CODEBLOCK56
Command: test-integration
Smoke test the full dev stack — API, Gateway, and Hummingbot connectivity.
CODEBLOCK57
What gets tested
| Test | Checks |
|---|
| API health | INLINECODE94 returns 200 |
| API version |
Confirms hummingbot source path (not PyPI) |
| Gateway health |
GET / on port 15888 returns 200 |
| API→Gateway | API can reach Gateway (
/gateway/status) |
| Connectors | At least one connector visible via API |
| Wallets | Gateway wallet list accessible |
Interpreting results
| Output | Meaning | Fix |
|---|
| INLINECODE97 | API up | — |
| INLINECODE98 |
Gateway up | — |
|
✓ API→Gateway connected | Full stack wired | — |
|
✗ API not running | Start with
run-api-dev | — |
|
✗ Gateway not running | Start with
run-gateway | — |
|
✗ API→Gateway: connection refused | Gateway URL mismatch | Check
.env GATEWAY_URL=http://localhost:15888 |
|
✗ Local hummingbot not active | Using PyPI version | Run
setup-api-dev |
Docker-Based API Development
For testing with Docker containers (instead of source), build a custom hummingbot-api image with your hummingbot wheel.
Step 1: Build Linux wheel for Docker
CODEBLOCK58
Step 2: Build hummingbot-api Docker image
CODEBLOCK59
Step 3: Deploy with docker-compose.dev.yml
CODEBLOCK60
Step 4: Verify development features
CODEBLOCK61
Deploying Bots with Custom Images
When deploying bots via the API, specify which hummingbot Docker image to use.
Deploy with development image
CODEBLOCK62
Available hummingbot images
| Image | Description |
|---|
| INLINECODE109 | Stable PyPI release (default) |
| INLINECODE110 |
Development branch from Docker Hub |
|
hummingbot/hummingbot:dev | Locally built image |
DEX connectors require Gateway
For connectors like meteora/clmm, Gateway must be running:
CODEBLOCK63
Quick Reference
Full Dev Setup (first time)
CODEBLOCK64
Testing a Hummingbot Change
CODEBLOCK65
Repo Paths (defaults)
| Component | Default path |
|---|
| Hummingbot | INLINECODE113 |
| Gateway |
~/.openclaw/workspace/hummingbot-gateway |
| Hummingbot API |
~/.openclaw/workspace/hummingbot-api |
Override by setting env vars:
CODEBLOCK66
Scripts Reference
| Script | Purpose |
|---|
| INLINECODE116 | Verify prereqs (conda, node, pnpm, docker, git) |
| INLINECODE117 |
Show branch + build status for each repo |
|
check_api.sh | Check if Hummingbot API is running |
|
check_gateway.sh | Check if Gateway is running |
|
test_integration.py | End-to-end smoke tests |
hummingbot-developer
用于从源码构建和运行完整 Hummingbot 堆栈的开发者工作流技能。
命令（以 /hummingbot-developer 形式运行）：
| 命令 | 描述 |
|---|
| start | 检查开发环境状态 |
| select-branches |
为所有 3 个仓库选择分支 |
| install-all | 按顺序安装所有 3 个仓库 |
| build-all | 构建 wheel + 所有 Docker 镜像 |
| verify-build | 验证构建是否正确且同步 |
| run-dev-stack | 从源码启动完整堆栈 |
| setup-hummingbot | 从源码安装 Hummingbot |
| run-hummingbot | 从源码运行 Hummingbot CLI |
| build-hummingbot | 构建 wheel + Docker 镜像 |
| setup-gateway | 从源码安装 Gateway |
| run-gateway | 以开发模式运行 Gateway |
| build-gateway | 构建 Gateway Docker 镜像 |
| setup-api-dev | 将 API 连接到本地 Hummingbot 源码 |
| run-api-dev | 从源码运行 API，支持热重载 |
| test-integration | 对完整堆栈进行冒烟测试 |
典型开发工作流：
install-deps → select-branches → install-all → build-all → verify-build → run-dev-stack → test-integration
仓库位置（均在工作区中）：
| 仓库 | 路径 |
|---|
| hummingbot | ~/.openclaw/workspace/hummingbot |
| gateway |
~/.openclaw/workspace/hummingbot-gateway |
| hummingbot-api | ~/.openclaw/workspace/hummingbot-api |
可通过环境变量覆盖：HUMMINGBOTDIR、GATEWAYDIR、HUMMINGBOTAPIDIR 或 WORKSPACE。
命令：install-deps
自动安装所有缺失的开发依赖项。可安全重复运行——会跳过已安装的内容。
bash
bash scripts/install_deps.sh
安装项（仅在缺失时安装）：
- - Homebrew（macOS）
- Xcode 命令行工具（macOS——Cython build_ext 所需）
- Miniconda（conda）
- Node.js v22（通过 nvm、Homebrew 或安装 nvm）
- pnpm（通过 npm 或 Homebrew）
- Git
- Docker Desktop（macOS——通过 Homebrew cask 或打开下载页面）
选项：
bash
--check # 仅检查，不安装任何内容
--conda # 仅安装 conda
--node # 仅安装 node + nvm
--pnpm # 仅安装 pnpm
安装后，重新启动终端（或执行 source ~/.zshrc）以应用 PATH 更改，然后运行 check_env.sh 进行确认。
命令：select-branches
交互式地为每个仓库选择分支，检出并保存到 .dev-branches。
bash
bash scripts/select_branches.sh
非交互式选项：
bash
全部使用 development 分支
bash scripts/select_branches.sh --defaults
指定每个分支
bash scripts/select_branches.sh \
--hummingbot development \
--gateway core-2.7 \
--api development
分支选择结果保存到 $WORKSPACE/.dev-branches，并由 installall.sh、buildall.sh 和 verify_build.sh 自动加载。
命令：install-all
按正确顺序安装所有三个仓库。需要先执行 select-branches（或传递 --defaults）。
bash
bash scripts/install_all.sh
执行内容（按顺序）：
- 1. 从 environment.yml 中移除 solders（仅 pip 安装）
- 在 hummingbot 中执行 make install → conda env hummingbot
- 将 pip install solders>=0.19.0 安装到 hummingbot 环境
- 为 gateway 执行 pnpm install && pnpm build && pnpm run setup:with-defaults
- 为 hummingbot-api 执行 conda env create
- 执行 pip install -e --no-deps → 将本地源码连接到 API 环境
选项：
bash
--skip-hbot # 跳过 hummingbot conda 安装
--skip-gateway # 跳过 gateway pnpm 安装
--skip-api # 跳过 hummingbot-api 安装
--no-local-hbot # 在 API 环境中使用 PyPI 上的 hummingbot 而非本地源码
命令：build-all
按正确顺序构建 hummingbot wheel 和所有 Docker 镜像。
bash
bash scripts/build_all.sh
构建顺序：
- 1. 通过 python setup.py bdist_wheel 构建 hummingbot wheel（dist/*.whl）
- 构建 hummingbot/hummingbot:dev Docker 镜像
- 构建 hummingbot/gateway:dev Docker 镜像（同时重建 dist/）
- 构建 hummingbot/hummingbot-api:dev Docker 镜像
每个镜像还会用分支名称打标签（例如 hummingbot/gateway:core-2.7）。
选项：
bash
--wheel-only # 仅构建 hummingbot wheel，不构建 Docker
--no-docker # 跳过所有 Docker 构建
--no-hbot # 跳过 hummingbot 构建
--no-gateway # 跳过 gateway 构建
--no-api # 跳过 hummingbot-api 构建
--tag # Docker 标签（默认：dev）
命令：verify-build
验证所有构建是否正确且同步。
bash
bash scripts/verify_build.sh
检查项：
- 1. 每个仓库都在预期的分支上（来自 .dev-branches）
- Hummingbot wheel 存在于 dist/ 中
- Gateway dist/ 已构建且相对于源码未过时
- 本地 hummingbot 源码在 hummingbot-api 环境中处于活动状态
- Docker 镜像存在且带有正确的分支标签
- 运行中的服务（API + Gateway）可访问
- API → Gateway 连接性
bash
bash scripts/verify_build.sh --no-docker # 跳过 Docker 检查
bash scripts/verify_build.sh --no-running # 跳过服务检查
bash scripts/verify_build.sh --json # JSON 输出
命令：run-dev-stack
从源码启动完整的开发堆栈。
bash
bash scripts/rundevstack.sh
启动顺序：
- 1. 通过 docker compose up emqx postgres -d 启动 Docker 基础设施（postgres + EMQX）
- 在后台从源码启动 Gateway（node dist/index.js --passphrase=hummingbot --dev）
- 在前台从源码启动 Hummingbot API（uvicorn main:app --reload）
选项：
bash
--no-gateway # 跳过 gateway 启动
--passphrase # gateway 密码短语（默认：hummingbot）
--stop # 停止所有内容
--status # 显示运行状态
日志：
- - Gateway 日志：tail -f ~/.openclaw/workspace/.gateway.log
- API 日志：打印到终端（前台）
命令：start
检查完整的开发环境并显示状态摘要。
步骤 1：运行环境检查
bash
bash scripts/check_env.sh --json
步骤 2：检查仓库分支
bash
bash scripts/check_repos.sh --json
步骤 3：检查运行中的服务
bash
bash scripts/check_api.sh --json
bash scripts/check_gateway.sh --json
步骤 4：显示状态清单
显示如下清单：
开发环境状态
======================
[x] 前提条件 — conda、node、pnpm、docker、git 正常
[x] Hummingbot 仓库 — 分支：development，环境：hummingbot（已安装）
[x] Gateway 仓库 — 分支：development，已构建：是
[x] Hummingbot API — 运行于 http://localhost:8000
[x] Gateway — 运行于 http://localhost:15888
[ ] 本地 hummingbot — hummingbot-api 未使用本地源码
下一步：运行 /hummingbot-developer setup-api-dev 将 API 连接到本地源码
