OpenClaw EnterpriseDOCSGitHub

Set up the OCC CLI

Use occ to manage OpenClaw Control Plane (OCC) resources from a terminal. Commands that access the OCC API need your Installation's endpoint and a protected service-key response file. To inspect an initialization Job without the OCC API, see Resume an installation in progress. For all commands and flags, see the CLI command reference. To deploy through the browser, see Create and deploy Agents in the console.

Connect to your Installation

For a published OCE version, download the binary matching your machine from the GitHub Releases page. The assets are named occ-v<version>-<os>-<arch> for macOS (darwin) and Linux, on amd64 or arm64. Download SHA256SUMS from the same release and compare the selected binary's SHA-256 before making it executable. For example, with the GitHub CLI:

bash
(  set -eu  OCE_VERSION='v<release-version>'  OCC_ASSET="occ-${OCE_VERSION}-darwin-arm64" # Choose your OS and CPU.  umask 077  tmp_dir="$(mktemp -d "${TMPDIR:-/tmp}/occ-install.XXXXXXXX")"  trap 'rm -rf "$tmp_dir"' EXIT   gh release download "$OCE_VERSION" \    --repo openclaw/openclaw-enterprise --dir "$tmp_dir" \    --pattern "$OCC_ASSET" --pattern SHA256SUMS  cd "$tmp_dir"   # Compare the full checksum line (digest and filename) for this asset.  expected="$(awk -v name="$OCC_ASSET" '$2 == name' SHA256SUMS)"  if command -v shasum >/dev/null 2>&1; then    actual="$(shasum -a 256 "$OCC_ASSET")"  else    actual="$(sha256sum "$OCC_ASSET")"  fi  if [ "$actual" != "$expected" ]; then    printf 'OCC CLI checksum verification failed; binary not installed.\n' >&2    exit 1  fi  mkdir -p "$HOME/.local/bin"  install -m 755 "$OCC_ASSET" "$HOME/.local/bin/occ"  "$HOME/.local/bin/occ" --version)

Ensure $HOME/.local/bin is on PATH. The example uses shasum if available and otherwise uses sha256sum. The printed CLI version should match the selected release. Use the release your controller runs, and upgrade occ with it: an older occ can misread newer API responses, such as paged Agent revision lists.

To build from a trusted source checkout instead, run this from its root to install occ on your Go binary path:

bash
go install ./cmd/occ

Ensure that directory is on PATH. To use the binary inside the checkout instead, use the Go version in go.mod, run go build -trimpath -o bin/occ ./cmd/occ from the repository root, and substitute ./bin/occ for occ below. Building the CLI does not require Node.js, pnpm, or installed JavaScript dependencies. occ dev up and occ dev down still require a source checkout even when the binary came from a GitHub Release.

Set the endpoint and the service-key file supplied by your administrator or created during bootstrap:

bash
export OCC_URL='https://occ.example.com'export OCC_SERVICE_KEY_FILE='/private/path/occ-service-key.json'occ installation getocc namespace list

occ has no human sign-in: a service key authenticates a non-Agent ServicePrincipal, not a person. For OCC API access without a key, use the console.

Replace both example values with your own. These commands require an Installation-scoped key; reading the Installation also requires Installation read. If your key is Namespace-scoped, use occ namespace get '<namespace-id>' with the ID supplied by your administrator instead.

installation get prints the Installation ID and name. namespace list prints the authorized Namespaces and their STATUS; a Namespace must be ready to deploy an Agent. Add --output json or --output yaml to print the resource or list without the HTTP response envelope. Set a Namespace once for subsequent commands:

bash
export OCC_NAMESPACE='<namespace-id>'

Give a member or automation CLI access

People sign in to the console; the CLI authenticates to the OCC API with a service key. An Installation administrator gives someone CLI access to one Namespace by issuing a key for a Namespace service principal that holds only the grants you bind. With an administrator key file and OCC_NAMESPACE set:

bash
occ iam service-principal create -o json    # note its id: <service-principal-id>occ iam access-binding create --file binding.jsonocc service-key create --service-principal '<service-principal-id>' \  --name nora-laptop --expires-in-days 30 --out nora-key.json

binding.json names the service principal as subjectId and an existing Namespace Role; see Namespace IAM. Each binding grants one target, so bind the same targets a person would need, as in Let a person run an existing Agent. Issuing the key requires that you already hold every grant of the service principal. The key never reaches another Namespace, IAM policy, or key issuance. Hand over the 0600 key file privately; the member sets OCC_SERVICE_KEY_FILE to it and OCC_NAMESPACE to the Namespace. When the key is no longer needed, run occ service-key revoke <key-id> (the ID printed at creation) or delete its AccessBindings. Disabling the member's console account does not end the key, so revoke it when they leave. OCE does not record whom a key was issued for, so start each key's --name with the person's name, as nora-laptop does: Remove a person finds their keys by it.

Choose your next task

Task Guide
Create and deploy an Agent Production Agent deployment, including Configuration, model credentials, and verification
Update a Configuration and deploy again Agent revisions; its CLI examples also require jq
Stop or delete an Agent Agent lifecycle and deletion and cleanup
Create or replace integration Secrets Namespace Secrets and Configuration bindings
Use a Credential Gateway Credential sources, including the current OpenShell limits
Grant access to a Namespace resource Namespace IAM
Let an Agent use a Secret Grant the Agent's own identity Secret operate
Inspect or upgrade the running fleet Production image upgrades and the CLI reference
Run a local development installation Local Setup

Connection and credential boundaries

The key file is the full JSON response from bootstrap or key issuance, not a file containing only the raw key. Keep it owner-readable; never put the key in command arguments, logs, or source control. For HTTPS signed by a private certificate authority, set OCC_CA_BUNDLE to its PEM bundle. See global options for timeout, origin, and TLS behavior.

Troubleshoot

Search documentation