Skip to content

dependencies.md

Latest commit

 

History

History
183 lines (143 loc) · 7.35 KB

dependencies.md

File metadata and controls

183 lines (143 loc) · 7.35 KB
Raw

Dependencies

简体中文

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:

./scripts/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. Cargo verifies the minimum Rust version during the build from the workspace rust-version. 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:

./scripts/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.

Safety rules

  • Outside the disclosed 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.
  • Print the target path before creating directories, symlinks, generated files, or logs.
  • Check ports before starting long-running processes.
  • Stop on any failure. Do not automatically fix, switch mirrors, or kill unrelated processes.

Required tools

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.91+ Building BCS rustc --version The BCS workspace declares rust-version = "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.

Optional tools

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.

Installation guide

The commands below are examples for manual execution. Agents must stop for confirmation before running any system-level or global write command.

macOS

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.

If Rust 1.91+ is not installed locally, install it through rustup:

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs \
  | sh -s -- -y --profile minimal --default-toolchain 1.91.0
source ~/.cargo/env
rustc --version

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

Debian / Ubuntu

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.91+, Node.js 22+, npm, and OpenClaw as described above.

Fedora

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.91+, Node.js 22+, npm, and OpenClaw as described above.

Verification

After installing or upgrading dependencies, return to the repository root and run:

./scripts/singlebox.sh check

After the preflight passes, continue with the main flow:

./scripts/singlebox.sh

--standalone remains accepted as an explicit alias for the same isolated singlebox mode:

./scripts/singlebox.sh --standalone