bamboo-claw

bamboo-claw is a CLI-first Python client agent that connects a Bamboo Claw central server to a local OpenClaw gateway.

It is not a general-purpose SDK at this point. The main entry point is the bambooclaw command installed by the package.

What It Does

• Connects to the Bamboo Claw central server over WebSocket.
• Connects to the local OpenClaw gateway over WebSocket.
• Registers the client with the server and waits for admin approval on first setup.
• Keeps bambooclaw run alive as a self-healing supervisor that re-enters registration if the server token is missing or rejected.
• Exchanges structured capability jobs with the server using register, client_status, job, job_event, job_result, job_query, and job_query_result.
• Hosts openclaw.chat on the persistent gateway connection and can expose structured subprocess-backed codex.exec and claude_code.exec adapters.
• Persists durable job state, ordered events, and logs in a local SQLite runtime journal.
• Supports Linux systemd installation and Windows .bat generation for service wrappers.

Requirements

• Python 3.11+
• A reachable Bamboo Claw server
• A reachable OpenClaw gateway

Default gateway URL:

ws://127.0.0.1:18789

Installation

From PyPI:

pip install bamboo-claw

For local development from this repository:

pip install -e ./client

Quick Start

1. Configure the client

bambooclaw setup --server https://central.example.com

You can also pass the gateway settings during setup:

bambooclaw setup \
  --server https://central.example.com \
  --gateway-url ws://127.0.0.1:18789 \
  --gateway-token YOUR_GATEWAY_TOKEN \
  --hostname worker-01

Notes:

• --server can be http://, https://, ws://, or wss://.
• If the path does not already end with /ws/client, the client appends it automatically.
• If no token exists yet, setup starts the registration flow immediately.

2. Approve the registration

On first setup, the client prints an approval code and waits for approval from the Bamboo Claw server.

The server-side approval flow uses this endpoint:

POST /api/admin/registrations/{approval_code}/approve

After approval, the client stores the issued token locally.

3. Run the agent

bambooclaw run

This starts the long-running supervisor process.

Supervisor behavior:

• If no Bamboo Claw server token exists, run enters the registration flow automatically.
• If the token is later rejected, run clears it and re-enters registration without requiring a manual restart.
• Server reconnect and registration retry use the fixed schedule 5s, 10s, 20s, then 30s forever.
• The OpenClaw gateway reconnects independently in the background.
• Locally running jobs continue writing to the runtime journal even if the server session drops.

4. Check local configuration state

bambooclaw status

This prints the configured server URL, whether a token exists, the client ID, the gateway URL, and the configured hostname.

Configuration File

Default config path:

~/.bamboo_claw/bamboo_claw.toml

Legacy fallback path:

~/.bamboo_claw/config.toml

Example config:

[server]
url = "https://central.example.com"

[auth]
token = "bcl_..."
client_id = "2f3c8d5a-7f3c-4c4a-b2d8-1f46d8f1e0d0"

[client]
hostname = "worker-01"

[gateway]
url = "ws://127.0.0.1:18789"
token = ""

[runtime]
journal_path = "/home/example/.bamboo_claw/client-runtime.sqlite3"
max_concurrent_jobs = 1

The client also stores additional runtime data in ~/.bamboo_claw/, including:

• device-identity.json for the persistent Ed25519 device identity used with the gateway
• device-tokens.json for gateway-issued device tokens
• client-runtime.sqlite3 for durable job state, ordered events, queryable logs, and reconnect replay

Command Reference

bambooclaw setup

Creates or updates local configuration and starts registration if no server token is present.

Useful options:

• --config PATH
• --server URL
• --gateway-url URL
• --gateway-token TOKEN
• --hostname NAME

bambooclaw run

Starts the agent. If the gateway is unavailable on startup, the client keeps retrying in the background while continuing to reconnect to the server as needed.

Useful option:

• --config PATH

Authenticated runtime messages:

• register advertises the client version, capability list, connectivity summary, and runtime health.
• client_status acts as the periodic liveness signal and sends updated connectivity/runtime health snapshots every 30 seconds, plus immediate updates on material changes.
• job, job_event, and job_result carry structured local work execution.
• job_query and job_query_result handle replay, summary, log-range, and cancellation queries against the local journal.

bambooclaw status

Shows local config state.

Useful option:

• --config PATH

bambooclaw daemon install

Installs and starts a Linux systemd service named bamboo-claw.service.

sudo bambooclaw daemon install

With an explicit config path:

sudo bambooclaw daemon install --config /etc/bamboo-claw/client.toml

Important behavior:

• Linux systemd only
• Requires root privileges
• Uses the current Python interpreter for ExecStart
• Uses the current working directory as WorkingDirectory

That means you should run the install command from the environment and directory you want the service to use.

Related commands:

bambooclaw daemon status
sudo bambooclaw daemon uninstall

bambooclaw windows-bat

Generates a Windows startup batch file for use with a wrapper such as NSSM.

bambooclaw windows-bat --output C:\bamboo\start-client.bat

Example with explicit working directory, virtualenv activation script, and config path:

bambooclaw windows-bat \
  --output C:\bamboo\start-client.bat \
  --working-dir C:\bamboo \
  --venv-activate C:\bamboo\.venv\Scripts\activate.bat \
  --config C:\bamboo\bamboo_claw.toml

Operational Notes

• If the server token is invalid or expired, the client clears the token and attempts the registration flow again.
• The gateway connection uses a persistent device identity and can store a gateway-issued device token after a successful handshake.
• OpenClaw chat now runs through the same job runtime used for future client capabilities; the server still keeps the legacy command path available during staged rollout, but the v2 client advertises and prefers the job protocol.
• Duplicate delivery of the same job_id is treated as the same logical job. Active jobs return their current state, and finished jobs return the stored terminal result.
• The package currently exposes a few importable modules, but the stable interface is the CLI, not a documented Python library API.