OpenClaw Orchestrator

Manage OpenClaw organizations with inventory-driven configuration, isolated runtime boundaries, and repeatable deployment workflows.

Features

• Multi-instance orchestration from a single inventory.
• Strict isolation across config/state/workspaces per instance.
• Org-level deployment provider selection (docker or kubernetes) with env overrides.
• Policy guardrails for models, skills, and integrations.
• Agent lifecycle commands (add/remove/list) with channel bindings.
• Template workflows for SOUL.md and TOOLS.md.
• Render/runtime/deploy workflows with revision support.

Integrations

• Channels: Telegram, Discord.
• Tool/API workflows: GitHub, Notion, Better Stack, web search (Brave).

See docs/INTEGRATIONS_AND_USE_CASES.md for details.

Quick Start

Install

Global install (recommended):

npm install -g @maestro-org/oco
oco --help

Run without installing globally:

npx @maestro-org/oco --help

If oco is not found:

echo 'export PATH="$(npm config get prefix)/bin:$PATH"' >> ~/.zshrc

Initialize Inventory

oco inventory init
# or: npx @maestro-org/oco inventory init

When installed from npm, oco inventory init uses the bundled inventory template if no local template file exists yet.

Edit inventory/instances.local.yaml (recommended) for:

• organization metadata
• organization deployment target (organization.deployment.provider)
• instance ports and paths
• channel accounts + agent bindings
• policy allow/deny defaults

For isolated multi-org setups, use one inventory per org:

• inventory/<org>.instances.local.yaml (local, gitignored), or
• inventory/<org>.instances.yaml (tracked template/reference).

A generic multi-org example is available at inventory/org.instances.example.yaml.

Path resolution order:

1. --inventory <path>
2. OCO_INVENTORY_PATH
3. inventory/instances.local.yaml
4. inventory/instances.yaml

Configure Secrets

cp .env.example .env

Typical values:

OPENCLAW_GATEWAY_TOKEN=<strong-random-token>
OPENAI_API_KEY=<provider-key>

TELEGRAM_BOT_TOKEN_OWNER=<telegram-bot-token>
DISCORD_BOT_TOKEN_BRAIN_QA=<discord-bot-token>

GITHUB_TOKEN=<github-token>
NOTION_API_KEY=<notion-token>
BETTERSTACK_API_TOKEN=<betterstack-token>
BETTERSTACK_API_BASE_URL=<betterstack-api-base-url>

Load env:

set -a
source .env
set +a

For multi-org isolation, keep secrets in separate files (for example .env.acme, .env.beta-org) and load via:

ORG_ENV_FILE=.env.acme ./scripts/org.sh acme validate

Choose Deployment Target

Set the org default in inventory:

organization:
  deployment:
    provider: docker # or kubernetes
    kubernetes:
      namespace: default
      # context omitted => current kubectl context

When Kubernetes names are omitted, oco defaults deployment/service/container names to oco-<instance-id>.

Optional env overrides:

• OCO_DEPLOYMENT_PROVIDER=docker|kubernetes
• OCO_KUBE_CONTEXT=<context>
• OCO_KUBE_NAMESPACE=<namespace>
• OCO_KUBECONFIG=<path>

Inspect the resolved target:

oco deployment target --instance core-human

Validate and Deploy

oco validate
oco policy validate
oco preflight --instance core-human

./scripts/deploy-instance.sh core-human
oco health --instance core-human

oco compose ... and oco runtime ... are provider-aware and automatically use Docker Compose or Kubernetes based on org config/env.

Manage Agents and Templates

oco agent list --instance core-human

oco agent add \
  --instance core-human \
  --agent-id support \
  --role usecase \
  --account telegram:support \
  --integration telegram \
  --model openai/gpt-5.1 \
  --soul-template operations \
  --tools-template operations

Apply templates to an existing agent:

oco soul apply --instance core-human --agent-id support --template operations --force
oco tools apply --instance core-human --agent-id support --template operations --force

Run org-scoped commands with the helper script:

./scripts/org.sh <org> validate
./scripts/org.sh <org> runtime up --instance <instance-id>
./scripts/org.sh <org> health --instance <instance-id>

Recommended Functional Isolation

Group by credential risk and write scope. For example:

• discord-knowledge: read-heavy QA/research agents.
• discord-systems: write-capable system-of-record agents (GitHub/Notion).
• discord-infra: monitoring + incident triage agents.

Detailed rollout: docs/E2E_OCO_DISCORD_FUNCTIONAL_AGENTS.md

Documentation

Comprehensive documentation is available in docs/, including deployment steps, usage examples, and reusable templates.

Security Best Practices

• Keep secrets in local .env only.
• Do not commit runtime state or rendered configs.
• Run before pushing:

git status --short --ignored
rg -n "sk-[A-Za-z0-9]{20,}|ghp_[A-Za-z0-9]{20,}|BEGIN (RSA|EC|OPENSSH|PGP|DSA)? ?PRIVATE KEY" .