hummingbot-developer

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

hummingbot-developer

HUMMINGBOT开发者工具

Developer workflow skill for building and running the full Hummingbot stack from source.

Commands (run as

/hummingbot-developer <command>

Command	Description
`start`	Check dev environment status
`select-branches`	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:

install-deps → select-branches → install-all → build-all → verify-build → run-dev-stack → test-integration

Repo locations (all in workspace):

Repo	Path
hummingbot	`~/.openclaw/workspace/hummingbot`
gateway	`~/.openclaw/workspace/hummingbot-gateway`
hummingbot-api	`~/.openclaw/workspace/hummingbot-api`

Override with env vars:

HUMMINGBOT_DIR

GATEWAY_DIR

HUMMINGBOT_API_DIR

, or

WORKSPACE

用于从源码构建和运行完整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

。

Command: install-deps

命令: install-deps

Auto-install all missing dev dependencies. Safe to re-run — skips anything already installed.

bash

bash scripts/install_deps.sh

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:

bash

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

After installing, restart your terminal (or

source ~/.zshrc

) to apply PATH changes, then run

check_env.sh

to confirm.

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

bash

bash scripts/install_deps.sh

安装内容（仅安装缺失项）：

Homebrew (macOS)
Xcode Command Line Tools (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

确认安装结果。

Command: select-branches

命令: select-branches

Interactively pick a branch for each repo, checkout, and save to

.dev-branches

bash

bash scripts/select_branches.sh

Non-interactive options:

bash

undefined

交互式为每个仓库选择分支、检出分支，并将选择保存到

.dev-branches

文件。

bash

bash scripts/select_branches.sh

非交互式选项：

bash

undefined

Use development for all

所有仓库均使用development分支

bash scripts/select_branches.sh --defaults

Specify each branch

为每个仓库指定分支

bash scripts/select_branches.sh
--hummingbot development
--gateway core-2.7
--api development


Branch selections are saved to `$WORKSPACE/.dev-branches` and automatically loaded by `install_all.sh`, `build_all.sh`, and `verify_build.sh`.

---

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` 自动加载。

---

Command: install-all

命令: install-all

Install all three repos in the correct order. Requires

select-branches

first (or pass

--defaults

bash

bash scripts/install_all.sh

What it does (in order):

Removes
```
solders
```
from
```
environment.yml
```
(pip-only)
```
make install
```
in hummingbot →
```
conda env hummingbot
```
```
pip install solders>=0.19.0
```
into hummingbot env

pnpm install && pnpm build && pnpm run setup:with-defaults

for gateway

```
conda env create
```
for hummingbot-api

pip install -e <hummingbot_dir> --no-deps

→ wires local source into API env

Options:

bash

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

按正确顺序安装所有三个仓库。需先执行

select-branches

（或传递

--defaults

参数）。

bash

bash scripts/install_all.sh

执行流程（顺序）：

从
```
environment.yml
```
中移除
```
solders
```
（仅支持pip安装）
在hummingbot目录执行
```
make install
```
→ 创建
```
conda env hummingbot
```
环境
向hummingbot环境中执行
```
pip install solders>=0.19.0
```

对gateway执行

pnpm install && pnpm build && pnpm run setup:with-defaults

为hummingbot-api执行
```
conda env create
```
执行
```
pip install -e <hummingbot_dir> --no-deps
```
→ 将本地源码关联到API环境

选项：

bash

--skip-hbot      # 跳过hummingbot的conda安装
--skip-gateway   # 跳过gateway的pnpm安装
--skip-api       # 跳过hummingbot-api的安装
--no-local-hbot  # 在API环境中使用PyPI的hummingbot而非本地源码

Command: build-all

命令: build-all

Build hummingbot wheel and all Docker images in the correct order.

bash

bash scripts/build_all.sh

Build order:

hummingbot

wheel (

dist/*.whl

) via

python setup.py bdist_wheel

```
hummingbot/hummingbot:dev
```
Docker image
```
hummingbot/gateway:dev
```
Docker image (also rebuilds dist/)
```
hummingbot/hummingbot-api:dev
```
Docker image

Each image is also tagged with the branch name (e.g.,

hummingbot/gateway:core-2.7

Options:

bash

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

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

bash

bash scripts/build_all.sh

构建顺序：

通过

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 <name>     # Docker镜像标签（默认：dev）

Command: verify-build

命令: verify-build

Verify that all builds are correct and in sync.

bash

bash scripts/verify_build.sh

Checks:

Each repo is on the expected branch (from
```
.dev-branches
```
)
Hummingbot wheel exists in
```
dist/
```
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

bash

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

验证所有构建结果是否正确且保持同步。

bash

bash scripts/verify_build.sh

检查项：

每个仓库均处于预期分支（来自
```
.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格式结果

Command: run-dev-stack

命令: run-dev-stack

Start the full dev stack from source.

bash

bash scripts/run_dev_stack.sh

Start order:

Docker infra (postgres + EMQX) via
```
docker compose up emqx postgres -d
```

Gateway from source in background (

node dist/index.js --passphrase=hummingbot --dev

)

Hummingbot API from source in foreground (
```
uvicorn main:app --reload
```
)

Options:

bash

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

Logs:

Gateway logs:

tail -f ~/.openclaw/workspace/.gateway.log

API logs: printed to terminal (foreground)

从源码启动完整开发技术栈。

bash

bash scripts/run_dev_stack.sh

启动顺序：

通过
```
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 <pass>    # Gateway密码（默认：hummingbot）
--stop                 # 停止所有服务
--status               # 显示服务运行状态

日志：

Gateway日志:

tail -f ~/.openclaw/workspace/.gateway.log

API日志: 输出到终端（前台运行）

Command: start

命令: start

Check the full dev environment and show a status summary.

检查完整开发环境并显示状态汇总。

Step 1: Run environment check

步骤1: 运行环境检查

bash

bash scripts/check_env.sh --json

bash

bash scripts/check_env.sh --json

Step 2: Check repo branches

步骤2: 检查仓库分支

bash

bash scripts/check_repos.sh --json

bash

bash scripts/check_repos.sh --json

Step 3: Check running services

步骤3: 检查运行中的服务

bash

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

bash

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

Step 4: Show status checklist

步骤4: 显示状态检查清单

Present a checklist like:

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

Adapt to actual state. If all good, show the test command.

展示如下格式的检查清单：

开发环境状态
======================
  [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与本地源码关联

清单会根据实际状态动态调整。若所有项均正常，会显示测试命令。

Command: setup-hummingbot

命令: setup-hummingbot

Install Hummingbot from source on the

development

branch.

从

development

分支源码安装Hummingbot。

Step 1: Check prereqs

步骤1: 检查前置依赖

bash

bash scripts/check_env.sh

bash

bash scripts/check_env.sh

Step 2: Checkout development branch

步骤2: 检出development分支

bash

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

bash

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

Step 3: Remove solders from environment.yml (pip-only package)

步骤3: 从environment.yml中移除solders（仅支持pip安装的包）

bash

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

bash

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

Step 4: Install conda environment

步骤4: 安装conda环境

bash

make install

This creates the

hummingbot

conda env. Takes 3-10 minutes on first run.

bash

make install

此命令会创建

hummingbot

conda环境。首次运行需3-10分钟。

Step 5: Install solders via pip (not on conda)

步骤5: 通过pip安装solders（conda不提供该包）

bash

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

bash

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

Interpreting output

输出结果解读

Output	Meaning	Next step
`conda develop .` succeeds	Dev install registered	Proceed
`PackagesNotFoundError: solders`	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`

输出	含义	下一步
`conda develop .` 执行成功	开发模式安装已注册	继续后续操作
`PackagesNotFoundError: solders`	跳过了步骤3	执行sed命令后重新安装
`Error: Conda is not found`	conda不在PATH中	执行 `source ~/.zshrc` 或安装Anaconda
`build_ext` 错误	缺失构建工具	安装Xcode CLT: `xcode-select --install`

After setup

安装完成后

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

  [x] conda环境 "hummingbot" 已创建
  [x] solders 已通过pip安装
  运行Hummingbot: /hummingbot-developer run-hummingbot
  构建镜像:    /hummingbot-developer build-hummingbot

Command: run-hummingbot

命令: run-hummingbot

Run the Hummingbot CLI from source.

bash

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

Or via make:

bash

cd <HUMMINGBOT_DIR>
make run

Note: This opens the interactive Hummingbot CLI. Use

exit

to quit.

To run with a specific config:

bash

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

从源码运行Hummingbot CLI。

bash

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

或通过make命令运行:

bash

cd <HUMMINGBOT_DIR>
make run

注意: 此命令会打开交互式Hummingbot CLI。使用

exit

命令退出。

若要使用指定配置运行:

bash

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

Command: build-hummingbot

命令: build-hummingbot

Build a Hummingbot wheel and/or Docker image from source.

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

Build wheel (for local pip installs)

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

bash

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

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:

bash

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

bash

cd <HUMMINGBOT_DIR>
conda activate hummingbot
pip install build wheel  # 若未安装则执行此命令
python -m build --wheel --no-isolation

Wheel包会输出到

dist/hummingbot-*.whl

。

重要提示: 必须使用Python 3.12构建wheel包，以匹配hummingbot-api的环境版本。

使用此wheel包安装到其他环境:

bash

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

Build Linux wheel for Docker

为Docker构建Linux wheel包

When building hummingbot-api Docker images, you need a Linux wheel (not macOS/Windows). Build inside Docker to ensure compatibility:

bash

cd <HUMMINGBOT_DIR>

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

bash

cd <HUMMINGBOT_DIR>

Build Linux wheel using Docker (Python 3.12 to match hummingbot-api)

使用Docker构建Linux wheel包（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 "

Verify the Linux wheel was created

验证Linux wheel包是否已创建

ls dist/linux.whl

Example: hummingbot-20260126-cp312-cp312-linux_aarch64.whl

示例: hummingbot-20260126-cp312-cp312-linux_aarch64.whl


**Platform wheel suffixes:**
- `linux_x86_64` — Linux AMD/Intel 64-bit
- `linux_aarch64` — Linux ARM64 (Apple Silicon Docker, AWS Graviton)
- `macosx_11_0_arm64` — macOS Apple Silicon (native only, NOT for Docker)
- `macosx_10_9_x86_64` — macOS Intel (native only, NOT for Docker)


**Platform wheel suffixes:**
- `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)

Build Docker image

构建Docker镜像

bash

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

Or with make (also cleans first):

bash

make build TAG=:dev

Tag for use with hummingbot-api:

bash

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

bash

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

或通过make命令构建（会先清理旧构建文件）:

bash

make build TAG=:dev

为hummingbot-api使用的镜像打标签:

bash

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

Interpreting output

输出结果解读

Output	Meaning
`Successfully built` + wheel path	Wheel ready in `dist/`
`Successfully tagged hummingbot/hummingbot:dev`	Docker image ready
`build_ext` error	Cython compile issue — check conda env is active
OOM during Docker build	Add `--memory 4g` flag

输出	含义
`Successfully built` + wheel包路径	Wheel包已在 `dist/` 目录就绪
`Successfully tagged hummingbot/hummingbot:dev`	Docker镜像已就绪
`build_ext` 错误	Cython编译问题 — 检查conda环境是否已激活
Docker构建时出现OOM错误	添加 `--memory 4g` 参数

Command: setup-gateway

命令: setup-gateway

Install and configure Gateway from source.

从源码安装并配置Gateway。

Step 1: Check prereqs

步骤1: 检查前置依赖

Requires Node.js 20+, pnpm, and git.

bash

bash scripts/check_env.sh

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

bash

bash scripts/check_env.sh

Step 2: Checkout development branch

步骤2: 检出development分支

bash

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

bash

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

Step 3: Install dependencies

步骤3: 安装依赖

bash

cd <GATEWAY_DIR>
pnpm install

If you see USB HID errors on macOS:

bash

pnpm install --force

bash

cd <GATEWAY_DIR>
pnpm install

若在macOS上看到USB HID错误:

bash

pnpm install --force

Step 4: Build TypeScript

步骤4: 构建TypeScript代码

bash

pnpm build

bash

pnpm build

Step 5: Run setup

步骤5: 运行设置脚本

bash

undefined

bash

undefined

Non-interactive with defaults (recommended for dev)

非交互式默认设置（推荐开发环境使用）

pnpm run setup:with-defaults

Interactive (choose which configs to update)

交互式设置（选择要更新的配置项）

pnpm run setup


Setup creates:
- `conf/` — chain, connector, token, and RPC configs
- `certs/` — TLS certificates (self-signed for dev)

pnpm run setup


设置脚本会创建:
- `conf/` — 链、连接器、代币和RPC配置
- `certs/` — TLS证书（开发环境使用自签名证书）

Interpreting output

输出结果解读

Output	Meaning	Next step
`Gateway setup complete`	Ready to start	`run-gateway`
`tsc` 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

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

Command: run-gateway

命令: run-gateway

Run Gateway from source in dev mode (HTTP, no TLS).

bash

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

Default passphrase matches hummingbot-api setup:

hummingbot

bash

pnpm start --passphrase=hummingbot --dev

What
--dev
does:

Runs in HTTP mode (no TLS) on port 15888
Enables verbose logging
Hummingbot API auto-connects at
```
http://localhost:15888
```

Verify it's running:

bash

curl http://localhost:15888/

Watch logs for startup sequence:

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

Configure custom RPC (recommended to avoid rate limits):

bash

undefined

以开发模式从源码运行Gateway（HTTP协议，无TLS加密）。

bash

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

默认密码与hummingbot-api设置一致:

hummingbot

bash

pnpm start --passphrase=hummingbot --dev

--dev
参数的作用:

以HTTP模式运行（无TLS），端口为15888
启用详细日志
Hummingbot API会自动连接到
```
http://localhost:15888
```

验证服务是否运行:

bash

curl http://localhost:15888/

查看启动日志序列:

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

配置自定义RPC（推荐，避免速率限制）:

bash

undefined

After gateway is running, update RPC via API

Gateway运行后，通过API更新RPC

curl -X POST http://localhost:15888/network/config
-H "Content-Type: application/json"
-d '{"chain": "solana", "network": "mainnet-beta", "nodeURL": "https://your-rpc.com"}'

---

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

Build a Gateway Docker image from source.

bash

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 .

Tag as development for use with hummingbot-api:

bash

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

Verify image:

bash

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

从源码构建Gateway Docker镜像。

bash

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使用的镜像打development标签:

bash

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

验证镜像:

bash

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

Command: setup-api-dev

命令: 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.

配置Hummingbot API使用本地HUMMINGBOT源码构建版本而非PyPI包版本。

这样您可以修改Hummingbot源码后，无需重新构建Docker镜像即可通过API立即测试更改。

Step 1: Install hummingbot-api conda environment

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

bash

cd <HUMMINGBOT_API_DIR>
make install

This creates the

hummingbot-api

conda env with the PyPI version of hummingbot.

bash

cd <HUMMINGBOT_API_DIR>
make install

此命令会创建

hummingbot-api

conda环境，并安装PyPI版本的hummingbot。

Step 2: Install local Hummingbot into hummingbot-api env

步骤2: 将本地HUMMINGBOT安装到hummingbot-api环境

Option A — Editable install (recommended for active development):

bash

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

Changes to hummingbot source are reflected immediately (no reinstall needed).

Option B — Wheel install (for testing a specific build):

bash

undefined

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

bash

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

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

选项B — Wheel包安装（用于测试特定构建版本）:

bash

undefined

First build the wheel

先构建wheel包

cd <HUMMINGBOT_DIR> && conda run -n hummingbot python setup.py bdist_wheel

Install into hummingbot-api env

安装到hummingbot-api环境

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

undefined

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

undefined

Step 3: Verify local version is active

步骤3: 验证本地版本是否激活

bash

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

Should print a path inside

<HUMMINGBOT_DIR>

, not

site-packages

bash

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

输出路径应位于

<HUMMINGBOT_DIR>

内部，而非

site-packages

。

Step 4: Install solders

步骤4: 安装solders

bash

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

bash

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

Interpreting output

输出结果解读

Output	Meaning
Path inside your hummingbot dir	✅ Local source active
Path inside `anaconda3/.../site-packages`	❌ Still using PyPI version
`ImportError: No module named hummingbot`	pip install failed — retry

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

Command: run-api-dev

命令: run-api-dev

Run Hummingbot API from source with hot-reload, using local Hummingbot.

从源码运行Hummingbot API并支持热重载，使用本地HUMMINGBOT版本。

Step 1: Start infrastructure (postgres + EMQX via Docker)

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

bash

cd <HUMMINGBOT_API_DIR>
docker compose up emqx postgres -d

Verify they're healthy:

bash

docker compose ps

bash

cd <HUMMINGBOT_API_DIR>
docker compose up emqx postgres -d

验证服务是否健康:

bash

docker compose ps

Step 2: Run the API with uvicorn hot-reload

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

bash

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

Or via make:

bash

make run

API is available at

http://localhost:8000

Swagger UI at

http://localhost:8000/docs

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.

bash

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

或通过make命令运行:

bash

make run

API可访问地址:

http://localhost:8000

Swagger UI地址:

http://localhost:8000/docs

热重载的含义: 对hummingbot-api目录下

*.py

文件的更改会立即生效。对hummingbot源码的更改（可编辑安装）也会在重载时被识别。

Step 3: Confirm local hummingbot is in use

步骤3: 确认使用的是本地HUMMINGBOT版本

bash

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

Check API logs for hummingbot version on startup.

bash

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

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

Useful dev commands

常用开发命令

bash

undefined

bash

undefined

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

---

docker compose ps curl http://localhost:8000/health

---

Command: test-integration

命令: test-integration

Smoke test the full dev stack — API, Gateway, and Hummingbot connectivity.

bash

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

对完整开发技术栈进行冒烟测试 — 验证API、Gateway和HUMMINGBOT的连通性。

bash

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

What gets tested

测试内容

Test	Checks
API health	`GET /health` 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

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

Interpreting results

结果解读

Output	Meaning	Fix
`✓ API running`	API up	—
`✓ Gateway running`	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`

输出	含义	修复方法
`✓ API running`	API已启动	—
`✓ Gateway running`	Gateway已启动	—
`✓ API→Gateway connected`	完整技术栈已连通	—
`✗ API not running`	执行 `run-api-dev` 启动API	—
`✗ Gateway not running`	执行 `run-gateway` 启动Gateway	—
`✗ API→Gateway: connection refused`	Gateway URL不匹配	检查 `.env` 文件中的 `GATEWAY_URL=http://localhost:15888`
`✗ Local hummingbot not active`	使用的是PyPI版本	执行 `setup-api-dev`

Docker-Based API Development

基于Docker的API开发

For testing with Docker containers (instead of source), build a custom hummingbot-api image with your hummingbot wheel.

若要使用Docker容器（而非源码）进行测试，可构建包含自定义hummingbot wheel包的hummingbot-api镜像。

Step 1: Build Linux wheel for Docker

步骤1: 为Docker构建Linux wheel包

bash

cd <HUMMINGBOT_DIR>

bash

cd <HUMMINGBOT_DIR>

Build Linux wheel using Docker (Python 3.12)

使用Docker构建Linux wheel包（Python 3.12）

ls dist/linux.whl

undefined

ls dist/linux.whl

undefined

Step 2: Build hummingbot-api Docker image

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

bash

cd <HUMMINGBOT_API_DIR>

bash

cd <HUMMINGBOT_API_DIR>

Copy wheel to API directory

将wheel包复制到API目录

cp <HUMMINGBOT_DIR>/dist/hummingbot--cp312--linux_*.whl .

Update environment.docker.yml with wheel filename

更新environment.docker.yml中的wheel包文件名

Then build using Dockerfile.dev

然后使用Dockerfile.dev构建镜像

docker build -f Dockerfile.dev -t hummingbot/hummingbot-api:dev .

undefined

docker build -f Dockerfile.dev -t hummingbot/hummingbot-api:dev .

undefined

Step 3: Deploy with docker-compose.dev.yml

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

bash

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

bash

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

Step 4: Verify development features

步骤4: 验证开发功能

bash

undefined

bash

undefined

Check lp_executor is available (only in development hummingbot)

检查lp_executor是否可用（仅development分支的hummingbot提供）

curl -s -u admin:admin http://localhost:8000/executors/types/available | grep lp_executor

---

curl -s -u admin:admin http://localhost:8000/executors/types/available | grep lp_executor

---

Deploying Bots with Custom Images

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

When deploying bots via the API, specify which hummingbot Docker image to use.

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

Deploy with development image

使用development镜像部署

bash

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

bash

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

Available hummingbot images

可用的hummingbot镜像

Image	Description
`hummingbot/hummingbot:latest`	Stable PyPI release (default)
`hummingbot/hummingbot:development`	Development branch from Docker Hub
`hummingbot/hummingbot:dev`	Locally built image

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

DEX connectors require Gateway

DEX连接器需要Gateway支持

For connectors like

meteora/clmm

, Gateway must be running:

bash

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

对于

meteora/clmm

等连接器，必须运行Gateway:

bash

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

Quick Reference

快速参考

Full Dev Setup (first time)

完整开发环境搭建（首次）

bash

undefined

bash

undefined

1. Setup repos

1. 配置仓库

cd ~/Documents/hummingbot && git checkout development && git pull cd ~/.openclaw/workspace/hummingbot-gateway && git checkout development && git pull

2. Install hummingbot

2. 安装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

3. 安装gateway

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

4. Wire hummingbot-api to local source

4. 将hummingbot-api与本地源码关联

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

5. 启动所有服务

cd ~/.openclaw/workspace/hummingbot-gateway pnpm start --passphrase=hummingbot --dev &

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

undefined

cd ~/.openclaw/workspace/hummingbot-gateway pnpm start --passphrase=hummingbot --dev &

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

undefined

Testing a Hummingbot Change

测试HUMMINGBOT代码更改

bash

undefined

bash

undefined

1. Make changes in hummingbot source

1. 在hummingbot源码中进行更改

2. If editable install: just save the file (hot-reload picks it up)

2. 若为可编辑安装：仅需保存文件（热重载会自动识别）

3. If wheel install: rebuild and reinstall

3. 若为wheel包安装：重新构建并安装

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

4. 重启API

5. Run tests

5. 运行测试

python scripts/test_integration.py

undefined

python scripts/test_integration.py

undefined

Repo Paths (defaults)

仓库路径（默认）

Component	Default path
Hummingbot	`~/Documents/hummingbot`
Gateway	`~/.openclaw/workspace/hummingbot-gateway`
Hummingbot API	`~/.openclaw/workspace/hummingbot-api`

Override by setting env vars:

bash

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

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

可通过设置环境变量覆盖:

bash

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

Scripts Reference

脚本参考

Script	Purpose
`check_env.sh`	Verify prereqs (conda, node, pnpm, docker, git)
`check_repos.sh`	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

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