hummingbot-developer

hummingbot-developer

用于从源代码构建和运行完整 Hummingbot 技术栈的开发工作流技能。

命令（以 /hummingbot-developer <command> 的形式运行）：

命令	描述
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

可通过环境变量覆盖：HUMMINGBOT_DIR、GATEWAY_DIR、HUMMINGBOT_API_DIR 或 WORKSPACE。

---

命令：install-deps

自动安装所有缺失的开发依赖。可安全重复运行——已安装的项目会跳过。

bash scripts/install_deps.sh

安装项（仅在缺失时安装）：

• Homebrew（macOS）
• Xcode Command Line Tools（macOS — build_ext 所需的 Cython 工具）
• Miniconda（conda）
• Node.js v22（通过 nvm、Homebrew 安装，或安装 nvm）
• pnpm（通过 npm 或 Homebrew 安装）
• Git
• Docker Desktop（macOS — 通过 Homebrew cask 安装，或打开下载页面）

选项：

--check         # check only, don't install anything
--conda         # only install conda
--node          # only install node + nvm
--pnpm          # only install pnpm

安装后，重启终端（或运行 source ~/.zshrc）以应用 PATH 更改，然后运行 check_env.sh 进行确认。

---

命令：select-branches

交互式地为每个仓库选择一个分支、切换到该分支，并保存到 .dev-branches。

bash scripts/select_branches.sh

非交互式选项：

# Use development for all
bash scripts/select_branches.sh --defaults

# Specify each branch
bash scripts/select_branches.sh \
  --hummingbot development \
  --gateway core-2.7 \
  --api development

所选分支会保存到 $WORKSPACE/.dev-branches，并由 install_all.sh、build_all.sh 和 verify_build.sh 自动加载。

---

命令：install-all

按正确顺序安装全部三个仓库。需要先运行 select-branches（或传入 --defaults）。

bash scripts/install_all.sh

执行内容（按顺序）：

1. 从 environment.yml 中移除 solders（仅支持 pip 安装）
2. 在 hummingbot 中运行 make install → conda env hummingbot
3. 将 solders>=0.19.0 安装到 hummingbot 环境中
4. 为 gateway 运行 pnpm install && pnpm build && pnpm run setup:with-defaults
5. 为 hummingbot-api 创建 conda env
6. 运行 pip install -e <hummingbot_dir> --no-deps → 将本地源代码接入 API 环境

选项：

--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

---

命令：build-all

按正确顺序构建 hummingbot wheel 和所有 Docker 镜像。

bash scripts/build_all.sh

构建顺序：

1. 通过 python setup.py bdist_wheel 构建 hummingbot wheel（dist/*.whl）
2. 构建 hummingbot/hummingbot:dev Docker 镜像
3. 构建 hummingbot/gateway:dev Docker 镜像（同时重新构建 dist/）
4. 构建 hummingbot/hummingbot-api:dev Docker 镜像

每个镜像还会使用分支名称打标签（例如，hummingbot/gateway:core-2.7）。

选项：

--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)

---

命令：verify-build

验证所有构建是否正确且同步。

bash scripts/verify_build.sh

检查项：

1. 每个仓库是否处于预期分支（来自 .dev-branches）
2. dist/ 中是否存在 Hummingbot wheel
3. Gateway 的 dist/ 是否已构建，且与源代码相比不是过时版本
4. hummingbot-api 环境中是否启用了本地 hummingbot 源代码
5. Docker 镜像是否存在且带有正确的分支标签
6. 运行中的服务（API + Gateway）是否可访问
7. API → Gateway 连接是否正常

bash scripts/verify_build.sh --no-docker   # skip Docker checks
bash scripts/verify_build.sh --no-running  # skip service checks
bash scripts/verify_build.sh --json        # JSON output

---

命令：run-dev-stack

从源代码启动完整的开发栈。

bash scripts/run_dev_stack.sh

启动顺序：

1. 通过 docker compose up emqx postgres -d 启动 Docker 基础设施（postgres + EMQX）
2. 在后台从源代码启动 Gateway（node dist/index.js --passphrase=hummingbot --dev）
3. 在前台从源代码启动 Hummingbot API（uvicorn main:app --reload）

选项：

--no-gateway           # skip gateway start
--passphrase <pass>    # gateway passphrase (default: hummingbot)
--stop                 # stop everything
--status               # show running status

日志：

• Gateway 日志：tail -f ~/.openclaw/workspace/.gateway.log
• API 日志：输出到终端（前台）

---

命令：start

检查完整的开发环境并显示状态摘要。

步骤 1：运行环境检查

bash scripts/check_env.sh --json

步骤 2：检查仓库分支

bash scripts/check_repos.sh --json

步骤 3：检查正在运行的服务

bash scripts/check_api.sh --json
bash scripts/check_gateway.sh --json

步骤 4：显示状态清单

显示类似以下的清单：

Dev Environment Status
======================
  [x] Prerequisites     — conda, node, pnpm, docker, git OK
  [x] Hummingbot repo   — branch: development, env: hummingbot (installed)
  [x] Gateway repo      — branch: development, built: yes
  [x] Hummingbot API    — running at http://localhost:8000
  [x] Gateway           — running at http://localhost:15888
  [ ] Local hummingbot  — hummingbot-api NOT using local source

Next: run /hummingbot-developer setup-api-dev to wire API to local source

根据实际状态调整。如果一切正常，显示测试命令。

---

命令：setup-hummingbot

从源代码的 development 分支安装 Hummingbot。

步骤 1：检查前置条件

bash scripts/check_env.sh

步骤 2：切换到 development 分支

cd <HUMMINGBOT_DIR>
git fetch origin
git checkout development
git pull origin development

步骤 3：从 environment.yml 中移除 solders（仅限 pip 的软件包）

sed -i '' '/solders/d' setup/environment.yml 2>/dev/null || sed -i '/solders/d' setup/environment.yml

步骤 4：安装 conda 环境

make install

这会创建 hummingbot conda 环境。首次运行需要 3-10 分钟。

步骤 5：通过 pip 安装 solders（conda 中没有）

conda run -n hummingbot pip install "solders>=0.19.0"

输出解读

输出	含义	后续步骤
conda develop . 成功	已注册开发安装	继续
PackagesNotFoundError: solders	忘记了步骤 3	运行 sed 并重新安装
Error: Conda is not found	conda 不在 PATH 中	source ~/.zshrc 或安装 Anaconda
build_ext 错误	缺少构建工具	安装 Xcode CLT：xcode-select --install

设置完成后

  [x] conda env "hummingbot" created
  [x] solders installed via pip
  Run hummingbot: /hummingbot-developer run-hummingbot
  Build image:    /hummingbot-developer build-hummingbot

---

命令：run-hummingbot

从源代码运行 Hummingbot CLI。

cd <HUMMINGBOT_DIR>
conda activate hummingbot
./bin/hummingbot_quickstart.py

或者通过 make 运行：

cd <HUMMINGBOT_DIR>
make run

注意： 这会打开交互式 Hummingbot CLI。使用 exit 退出。

使用指定配置运行：

make run ARGS="--config-file-name conf_pure_mm_1.yml"

---

命令：build-hummingbot

从源代码构建 Hummingbot wheel 和/或 Docker 镜像。

构建 wheel（用于本地 pip 安装）

cd <HUMMINGBOT_DIR>
conda activate hummingbot
pip install build wheel  # if not already installed
python -m build --wheel --no-isolation

Wheel 输出到 dist/hummingbot-*.whl。

重要： 必须使用 Python 3.12 构建 wheel，以匹配 hummingbot-api 的环境。

使用此 wheel 安装到其他环境：

pip install dist/hummingbot-*.whl --force-reinstall --no-deps

为 Docker 构建 Linux wheel

构建 hummingbot-api Docker 镜像时，需要 Linux wheel（而非 macOS/Windows 版本）。请在 Docker 中构建以确保兼容性：

cd <HUMMINGBOT_DIR>

# Build Linux wheel using Docker (Python 3.12 to match hummingbot-api)
docker run --rm -v $(pwd):/hummingbot -w /hummingbot continuumio/miniconda3 bash -c "
  apt-get update -qq && apt-get install -y -qq gcc g++ build-essential > /dev/null 2>&1 &&
  conda create -n build python=3.12 cython numpy -y -q &&
  conda run -n build pip install -q build wheel &&
  conda run -n build python -m build --wheel
"

# Verify the Linux wheel was created
ls dist/*linux*.whl
# Example: hummingbot-20260126-cp312-cp312-linux_aarch64.whl

平台 wheel 后缀：

• linux_x86_64 — Linux AMD/Intel 64 位
• linux_aarch64 — Linux ARM64（Apple Silicon Docker、AWS Graviton）
• macosx_11_0_arm64 — macOS Apple Silicon（仅限原生环境，不适用于 Docker）
• macosx_10_9_x86_64 — macOS Intel（仅限原生环境，不适用于 Docker）

构建 Docker 镜像

cd <HUMMINGBOT_DIR>
docker build -t hummingbot/hummingbot:dev -f Dockerfile .

或者使用 make（也会先清理）：

make build TAG=:dev

用于 hummingbot-api 的标签：

docker build -t hummingbot/hummingbot:development -f Dockerfile .

输出解读

输出	含义
Successfully built + wheel 路径	wheel 已就绪，位于 dist/
Successfully tagged hummingbot/hummingbot:dev	Docker 镜像已就绪
build_ext 错误	Cython 编译问题 — 检查 conda 环境是否已激活
Docker 构建期间发生 OOM	添加 --memory 4g 标志

---

命令：setup-gateway

从源代码安装并配置 Gateway。

步骤 1：检查前置条件

需要 Node.js 20+、pnpm 和 git。

bash scripts/check_env.sh

步骤 2：切换到 development 分支

cd <GATEWAY_DIR>
git fetch origin
git checkout development
git pull origin development

步骤 3：安装依赖项

cd <GATEWAY_DIR>
pnpm install

如果在 macOS 上遇到 USB HID 错误：

pnpm install --force

步骤 4：构建 TypeScript

pnpm build

步骤 5：运行设置

# Non-interactive with defaults (recommended for dev)
pnpm run setup:with-defaults

# Interactive (choose which configs to update)
pnpm run setup

设置过程会创建：

• conf/ — 链、连接器、代币和 RPC 配置
• certs/ — TLS 证书（开发环境使用自签名证书）

解读输出

输出	含义	下一步
Gateway setup complete	已准备就绪，可以启动	run-gateway
tsc errors	TypeScript 编译错误	检查 Node 版本（node --version ≥ 20）
pnpm: command not found	未安装 pnpm	npm install -g pnpm
ENOSPC	磁盘空间不足	释放空间

---

命令：run-gateway

以开发模式从源代码运行 Gateway（HTTP，无 TLS）。

cd <GATEWAY_DIR>
pnpm start --passphrase=<PASSPHRASE> --dev

默认密码短语与 hummingbot-api 设置一致：hummingbot

pnpm start --passphrase=hummingbot --dev

--dev 的作用：

• 在端口 15888 上以 HTTP 模式运行（无 TLS）
• 启用详细日志记录
• Hummingbot API 自动连接到 http://localhost:15888

验证是否正在运行：

curl http://localhost:15888/

查看日志中的启动流程：

Gateway listening on port 15888
Solana mainnet-beta initialized
...

配置自定义 RPC（建议配置以避免触发速率限制）：

# 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"}'

---

命令：build-gateway

从源代码构建 Gateway Docker 镜像。

cd <GATEWAY_DIR>
docker build \
  --build-arg BRANCH=$(git rev-parse --abbrev-ref HEAD) \
  --build-arg COMMIT=$(git rev-parse HEAD) \
  --build-arg BUILD_DATE=$(date -u +%Y-%m-%dT%H:%M:%SZ) \
  -t hummingbot/gateway:dev \
  -f Dockerfile .

标记为开发版本，以便与 hummingbot-api 配合使用：

docker tag hummingbot/gateway:dev hummingbot/gateway:development

验证镜像：

docker run --rm hummingbot/gateway:dev node -e "console.log('OK')"

---

命令：setup-api-dev

配置 Hummingbot API，使其使用本地构建的 Hummingbot 源代码，而非 PyPI 包。

这样，你可以修改 Hummingbot 并通过 API 立即测试，无需重新构建 Docker 镜像。

步骤 1：安装 hummingbot-api conda 环境

cd <HUMMINGBOT_API_DIR>
make install

这会创建 hummingbot-api conda 环境，其中包含 PyPI 版本的 hummingbot。

步骤 2：将本地 Hummingbot 安装到 hummingbot-api 环境中

选项 A — 可编辑安装（推荐用于活跃开发）：

conda run -n hummingbot-api pip install -e <HUMMINGBOT_DIR> --no-deps

对 hummingbot 源代码所做的更改会立即生效（无需重新安装）。

选项 B — Wheel 安装（用于测试特定构建）：

# First build the wheel
cd <HUMMINGBOT_DIR> && conda run -n hummingbot python setup.py bdist_wheel

# Install into hummingbot-api env
conda run -n hummingbot-api pip install <HUMMINGBOT_DIR>/dist/hummingbot-*.whl --force-reinstall --no-deps

步骤 3：验证本地版本已启用

conda run -n hummingbot-api python -c "import hummingbot; print(hummingbot.__file__)"

应输出 <HUMMINGBOT_DIR> 内的路径，而不是 site-packages。

步骤 4：安装 solders

conda run -n hummingbot-api pip install "solders>=0.19.0"

解读输出

输出	含义
hummingbot 目录内的路径	✅ 已启用本地源代码
anaconda3/.../site-packages 内的路径	❌ 仍在使用 PyPI 版本
ImportError: No module named hummingbot	pip 安装失败 — 请重试

---

命令：run-api-dev

使用本地 Hummingbot，通过热重载从源代码运行 Hummingbot API。

步骤 1：启动基础设施（通过 Docker 运行 postgres + EMQX）

cd <HUMMINGBOT_API_DIR>
docker compose up emqx postgres -d

验证它们是否正常运行：

docker compose ps

步骤 2：使用 uvicorn 热重载运行 API

cd <HUMMINGBOT_API_DIR>
conda run --no-capture-output -n hummingbot-api uvicorn main:app --reload

也可以通过 make 运行：

make run

API 可通过 http://localhost:8000 访问 Swagger UI 可通过 http://localhost:8000/docs 访问

热重载的含义： 对 hummingbot-api 中 *.py 文件的更改会立即生效。重新加载时，hummingbot 源代码（可编辑安装）中的更改也会生效。

步骤 3：确认正在使用本地 hummingbot

curl -s http://localhost:8000/health | python3 -m json.tool

检查 API 日志中的 hummingbot 启动版本信息。

实用开发命令

# Watch logs
conda run -n hummingbot-api uvicorn main:app --reload --log-level debug

# Run on different port
conda run -n hummingbot-api uvicorn main:app --reload --port 8001

# Check what's running
docker compose ps
curl http://localhost:8000/health

---

命令：test-integration

对完整开发环境进行冒烟测试 — API、Gateway 和 Hummingbot 的连接情况。

bash scripts/check_api.sh
bash scripts/check_gateway.sh
python scripts/test_integration.py

测试内容

测试	检查项
API 健康状态	GET /health 返回 200
API 版本	确认使用 hummingbot 源代码路径（非 PyPI）
Gateway 健康状态	端口 15888 上的 GET / 返回 200
API→Gateway	API 可以访问 Gateway（/gateway/status）
连接器	至少有一个连接器可通过 API 查看
钱包	可以访问 Gateway 钱包列表

解读结果

输出	含义	修复方法
✓ API running	API 正在运行	—
✓ Gateway running	Gateway 正在运行	—
✓ API→Gateway connected	整个环境已连通	—
✗ API not running	使用 run-api-dev 启动	—
✗ Gateway not running	使用 run-gateway 启动	—
✗ API→Gateway: connection refused	Gateway URL 不匹配	检查 .env 中的 GATEWAY_URL=http://localhost:15888
✗ Local hummingbot not active	正在使用 PyPI 版本	运行 setup-api-dev

---

基于 Docker 的 API 开发

使用 Docker 容器进行测试（而非使用源码）时，请使用你的 hummingbot wheel 构建自定义 hummingbot-api 镜像。

步骤 1：为 Docker 构建 Linux wheel

cd <HUMMINGBOT_DIR>

# Build Linux wheel using Docker (Python 3.12)
docker run --rm -v $(pwd):/hummingbot -w /hummingbot continuumio/miniconda3 bash -c "
  apt-get update -qq && apt-get install -y -qq gcc g++ build-essential > /dev/null 2>&1 &&
  conda create -n build python=3.12 cython numpy -y -q &&
  conda run -n build pip install -q build wheel &&
  conda run -n build python -m build --wheel
"

ls dist/*linux*.whl

步骤 2：构建 hummingbot-api Docker 镜像

cd <HUMMINGBOT_API_DIR>

# Copy wheel to API directory
cp <HUMMINGBOT_DIR>/dist/hummingbot-*-cp312-*-linux_*.whl .

# Update environment.docker.yml with wheel filename
# Then build using Dockerfile.dev
docker build -f Dockerfile.dev -t hummingbot/hummingbot-api:dev .

步骤 3：使用 docker-compose.dev.yml 部署

cd <HUMMINGBOT_API_DIR>
docker compose -f docker-compose.dev.yml up -d

步骤 4：验证开发功能

# Check lp_executor is available (only in development hummingbot)
curl -s -u admin:admin http://localhost:8000/executors/types/available | grep lp_executor

---

使用自定义镜像部署机器人

通过 API 部署机器人时，请指定要使用的 hummingbot Docker 镜像。

使用开发镜像部署

curl -X POST http://localhost:8000/bot-orchestration/deploy-v2-controllers \
  -u admin:admin \
  -H "Content-Type: application/json" \
  -d '{
    "instance_name": "my-bot",
    "credentials_profile": "master_account",
    "controllers_config": ["my_controller.yml"],
    "image": "hummingbot/hummingbot:development"
  }'

可用的 hummingbot 镜像

镜像	说明
hummingbot/hummingbot:latest	稳定的 PyPI 版本（默认）
hummingbot/hummingbot:development	来自 Docker Hub 的开发分支
hummingbot/hummingbot:dev	本地构建的镜像

DEX 连接器需要 Gateway

对于 meteora/clmm 等连接器，必须运行 Gateway：

docker run -d --name gateway -p 15888:15888 \
  -e GATEWAY_PASSPHRASE=admin \
  hummingbot/gateway:development

---

快速参考

完整开发环境设置（首次）

# 1. Setup repos
cd ~/Documents/hummingbot && git checkout development && git pull
cd ~/.openclaw/workspace/hummingbot-gateway && git checkout development && git pull

# 2. Install hummingbot
cd ~/Documents/hummingbot
sed -i '' '/solders/d' setup/environment.yml
make install
conda run -n hummingbot pip install "solders>=0.19.0"

# 3. Install gateway
cd ~/.openclaw/workspace/hummingbot-gateway
pnpm install && pnpm build && pnpm run setup:with-defaults

# 4. Wire hummingbot-api to local source
cd ~/.openclaw/workspace/hummingbot-api
make install
conda run -n hummingbot-api pip install -e ~/Documents/hummingbot --no-deps
conda run -n hummingbot-api pip install "solders>=0.19.0"

# 5. Start everything
cd ~/.openclaw/workspace/hummingbot-gateway
pnpm start --passphrase=hummingbot --dev &

cd ~/.openclaw/workspace/hummingbot-api
docker compose up emqx postgres -d
make run

测试 Hummingbot 更改

# 1. Make changes in hummingbot source
# 2. If editable install: just save the file (hot-reload picks it up)
# 3. If wheel install: rebuild and reinstall
cd ~/Documents/hummingbot
conda run -n hummingbot python setup.py bdist_wheel
conda run -n hummingbot-api pip install dist/hummingbot-*.whl --force-reinstall --no-deps
# 4. Restart API
# 5. Run tests
python scripts/test_integration.py

仓库路径（默认值）

组件	默认路径
Hummingbot	~/Documents/hummingbot
Gateway	~/.openclaw/workspace/hummingbot-gateway
Hummingbot API	~/.openclaw/workspace/hummingbot-api

设置环境变量以覆盖默认值：

export HUMMINGBOT_DIR=~/code/hummingbot
export GATEWAY_DIR=~/code/gateway
export HUMMINGBOT_API_DIR=~/code/hummingbot-api

脚本参考

脚本	用途
check_env.sh	验证前置条件（conda、node、pnpm、docker、git）
check_repos.sh	显示每个仓库的分支和构建状态
check_api.sh	检查 Hummingbot API 是否正在运行
check_gateway.sh	检查 Gateway 是否正在运行
test_integration.py	端到端冒烟测试