This document lists the third-party tools required for the local BCS + OpenClaw quick start. It is written for humans and agents to read before installing dependencies or starting services.
Supported platforms: macOS, Debian / Ubuntu, and Fedora. This page covers the
native singlebox.sh isolated local path. The Docker source-build path only
needs the optional Docker dependency below; see the
Docker Guide for the full flow.
Run the safety preflight from the repository root first:
./singlebox/singlebox.sh check
check only prints the paths it will use and checks the BCS / frontend
preflight items: Cargo / protoc, the Node.js major version, npm, source
directories, and ports. Except for initializing a few local runtime
directories, it does not install dependencies, build code, start services, kill
processes, or change global configuration. check does not preflight OpenClaw
or jq for the 5-bot startup script; those are checked when the local bot
stack actually starts. The repository’s rust-toolchain.toml
selects Rust 1.94.0. The workspace’s rust-version = "1.91" declares the minimum
supported Rust version (MSRV); it does not select the compiler. If check fails,
install the missing items manually and run the same check again.
If you want the script to help check and install missing tools, use:
./singlebox/singlebox.sh install-tools
install-tools first checks the basic compiler and build environment. If a
compiler or another basic build tool is missing, it prints a platform-specific
manual installation command. It asks for confirmation before installing
missing system commands and development libraries, OpenClaw, Rust/Cargo, and
protobuf/protoc. Node.js and uv are the current exceptions: when Node.js 22+ is
missing or too old, the script automatically installs it through nvm; when uv
is missing, it automatically tries pip and then the official installer. If a
system package installation is rejected by host permissions or otherwise
fails, the script prints a command that can be run manually. On macOS, a
missing Homebrew install is reported with a link to
brew.sh and instructions to rerun install-tools. Run it
only after confirming that all of these local writes, including the automatic
Node.js and uv paths, are acceptable.
Running singlebox.sh also installs the repo-local pre-push hook by setting
core.hooksPath=.githooks. Set OCB_SKIP_GIT_HOOKS=1 if you need to skip hook
installation for a one-off command.
install-tools Node.js and uv auto-install paths, stop
for confirmation before running sudo, global installs, brew link --force,
curl | sh, or any equivalent system-level write.| Tool | Used for | Check command | Notes |
|---|---|---|---|
| macOS or Linux | Local quick start | uname -a |
Linux needs build tools, pkg-config, and SQLite / OpenSSL development libraries. |
| Rust 1.94.0 via rustup | Building BCS | rustc --version from the repository root |
Pinned by rust-toolchain.toml; the BCS workspace MSRV remains 1.91. |
| Cargo | Building BCS | cargo --version |
Installed with the Rust toolchain. |
protoc |
BCS protobuf codegen | protoc --version |
Requires the Protocol Buffers compiler. |
| SQLite development libraries | BCS local storage | pkg-config --modversion sqlite3 |
Usually present on macOS; Linux needs a dev package. |
| OpenSSL development libraries | Building Rust TLS / native-tls dependencies | pkg-config --modversion openssl |
Linux needs libssl-dev / openssl-devel; on macOS, prefer Homebrew openssl@3. |
| Node.js 22+ | Building the BCN plugin and running the frontend | node --version |
singlebox.sh rejects lower major versions. |
| npm | Installing/building the BCN plugin and installing frontend dependencies | npm --version |
The native singlebox path uses npm for plugin and frontend setup. |
OpenClaw >= 2026.3.28 |
Starting the local 5-bot stack | openclaw --version |
install-tools asks whether to install the requested version when OpenClaw is missing or below the minimum. |
jq |
Generating and reusing 5-bot OpenClaw JSON configuration | jq --version |
The local 5-bot stack uses it to safely handle model and bot configuration. |
curl |
Health checks and manual downloads | curl --version |
Used by scripts and manual installation commands. |
lsof |
Port checks | lsof -v |
Used to check whether local ports are occupied before startup. |
| Tool | When you need it | Notes |
|---|---|---|
pnpm enabled through corepack |
Developing other plugin workspace packages | Not required by quick start. |
| Docker and Docker Compose | Using the Docker source-build path | Docker Desktop includes Compose; Linux can install Docker Engine and the Compose plugin. See the Docker Guide. |
| Model API endpoint and key | Letting test bots make real model calls, or using LLM judge nodes in custom collaboration | Do not commit keys and do not write them into shell rc files. |
USE_CN_MIRROR=1 |
Network acceleration in mainland China | Use only when you explicitly want npm, PyPI, nvm, rustup, corepack, and similar downloads to use public mirrors. |
The commands below are examples for manual execution. Agents must stop for confirmation before running any system-level or global write command.
brew install protobuf jq pkg-config openssl@3
protoc --version
jq --version
PKG_CONFIG_PATH="$(brew --prefix openssl@3)/lib/pkgconfig" pkg-config --modversion openssl
If OpenSSL is visible to pkg-config only with PKG_CONFIG_PATH, export the
same variable in the current shell before building BCS.
Install Rust 1.94.0 and its coverage component through rustup. With an existing
rustup installation, this adds the pinned toolchain without changing the global
default. Run these commands from the repository root:
if command -v rustup >/dev/null 2>&1; then
rustup toolchain install 1.94.0 --profile minimal --component llvm-tools
else
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs \
| sh -s -- -y --profile minimal --default-toolchain 1.94.0
source "${CARGO_HOME:-$HOME/.cargo}/env"
rustup component add --toolchain 1.94.0 llvm-tools
fi
rustc -Vv
The compiler must report release: 1.94.0. If another version is active, check
for a conflicting RUSTUP_TOOLCHAIN or a non-rustup compiler earlier in PATH.
Use your preferred Node version manager to install or switch to Node.js 22+, then verify it:
node --version
npm --version
After you confirm that a global install is acceptable, install the OpenClaw CLI:
npm install -g "openclaw@>=2026.3.28"
openclaw --version
sudo apt-get update
sudo apt-get install -y \
build-essential pkg-config perl \
protobuf-compiler libssl-dev libsqlite3-dev \
curl git jq lsof
protoc --version
pkg-config --modversion sqlite3
pkg-config --modversion openssl
jq --version
Then install Rust 1.94.0, Node.js 22+, npm, and OpenClaw as described above.
sudo dnf install -y \
gcc gcc-c++ make pkg-config perl \
protobuf-compiler openssl-devel sqlite-devel \
curl git jq lsof
protoc --version
pkg-config --modversion sqlite3
pkg-config --modversion openssl
jq --version
Then install Rust 1.94.0, Node.js 22+, npm, and OpenClaw as described above.
After installing or upgrading dependencies, return to the repository root and run:
./singlebox/singlebox.sh check
After the preflight passes, continue with the main flow:
./singlebox/singlebox.sh
--standalone remains accepted as an explicit alias for the same isolated
singlebox mode:
./singlebox/singlebox.sh --standalone