Skip to main content

Operations

Startup behavior​

The chart checks /healthz for startup, readiness, and liveness. Kubernetes waits for the Gateway to start before routing traffic or running liveness checks.

Image pulls, dependency setup, and profile syncs can delay startup. If initialization needs more time, increase openclaw.startupProbe.failureThreshold or openclaw.startupProbe.periodSeconds.

GitLab avatar refresh​

Startup runs a single Python importer using the existing GITLAB_TOKEN environment variable. The token's GitLab account supplies the main agent avatar. Run oc-import-gitlab-avatars for a manual refresh. Missing tokens skip the import, failed downloads preserve the cached image, and unchanged images are not rewritten.

There are no dedicated Helm avatar settings. See the chart configuration for download and validation limits. Reload the Control UI after a manual refresh.

Agent CLI helpers​

The agent image includes rg, jq, gh, glab, fd, yq, bat, tree, and ast-grep for repository inspection.

The commands fd and bat are also available under those names when the distribution packages them as fdfind and batcat. If no tree RPM is installed, the image uses the npm tree-cli package.

See the Containerfile for base-image, Node.js, and build details.

Smoke tests​

After installing or upgrading the openclaw release in the openclaw namespace, run:

helm test openclaw -n openclaw

The test checks that cluster DNS can resolve the Service. It also uses kubectl exec to run openclaw health --json inside the live Gateway container. When openclaw.httpRoute.enabled=true, the test checks the Teams and generic hook endpoints through the Service ports. Helm reports whether the test passed.

Increase openclaw.tests.cli.timeoutSeconds when the Gateway needs more than 300 seconds to become healthy, or set openclaw.tests.cli.enabled=false to disable the CLI check.

For each enabled OpenClaw CronJob, helm test also creates a manual Job and waits for it to finish. Increase openclaw.tests.cronJobs.timeoutSeconds for slower clusters, or set openclaw.tests.cronJobs.enabled=false to disable this check.

Monitoring​

GitLab Work Queue​

Open Work Queue in the Control UI to read assigned work in discovery order. The page shows creation dates, item kinds, priority, type and size labels, and total time spent. Combine the label filters to narrow the list without changing the original ranks. The To-dos tab shows all pending GitLab to-dos.

The gitlab-agent plugin and server-side glab authentication are required. Set skills.entries.gitlab-agent.config.owner in the active OpenClaw configuration to the GitLab username of the person who granted project access. The workspace profile and standalone package require the same setting; GITLAB_AGENT_OWNER and USER.md are not owner fallbacks. Select Refresh for a new snapshot; large queues can take several minutes. The status shows the snapshot date, and read failures display an error instead of an empty queue.

Expand Discovery scripts and ordering to inspect the installed scripts. The page shares the agent's priority and open-blocker ordering, but does not adopt issues, change labels or complete to-dos. New owner instructions can preempt the displayed order. Waiting and review items remain visible.

Run the same read-only report from the gateway workspace:

python3 skills/gitlab-agent/scripts/work-queue-report.py

The JSON contains ordered items, pending todos and script sources. Outside that profile, the plugin automatically uses the report helpers included in its public package. Both Work Queue and GitLab timelogs belong to the same gitlab-agent plugin.

GitLab label activity​

Access checks update workflow labels only when access changes. They preserve unrelated labels and stop if label data is missing or unreadable.

Routine audits keep the current workflow state unless the work changes. Unchanged checks do not add label activity; existing activity history remains intact.

Gateway metrics​

Gateway metrics are available at /api/diagnostics/prometheus and require authentication. In token-auth mode, the ServiceMonitor and Helm test use the release token. In trusted-proxy review deployments, the Helm test uses a synthetic forwarded identity.

The metrics Helm test is enabled by default:

openclaw:
  monitoring:
    tests:
      metrics:
        enabled: true

ServiceMonitor and Grafana dashboard integration are also enabled by default. The chart creates these resources only when their CRDs are installed.

Backups​

Set openclaw.crons.backup.enabled=true to back up the workspace to an OCI repository. Replace the example repository with your snapshot repository:

openclaw:
  crons:
    backup:
      enabled: true
      schedule: "0 */6 * * *"
      repository: registry.gitlab.com/group/project/openclaw-snapshot

The oc-oras-snapshot CronJob mounts the workspace PVC read-only. It pushes timestamped snapshots and updates the configured latest tag. This example runs every six hours.

Workspace cleanup advice​

The cleanup-advice CronJob is enabled by default. It checks disk usage in /mnt/openclaw/workspace and starts an agent turn with cleanup advice when usage reaches the threshold:

openclaw:
  crons:
    workdirCleanup:
      enabled: true
      schedule: "0 */6 * * *"
      thresholdPercent: 80

The job uses kubectl exec in the running Deployment rather than mounting the workspace PVC directly.

Deleting a release​

When the chart manages the workspace PVC, its Helm and Argo CD PreDelete hook clears the PVC's finalizers before deletion. The hook uses the release ServiceAccount and a namespaced Role limited to reading and patching that PVC.

Disable this cleanup job when your platform manages PVC lifecycle separately:

openclaw:
  preDeleteHook:
    enabled: false

Review pipeline checks​

When OPENROUTER_API_KEY is configured, merge-request pipelines test an isolated review release:

  1. review-helm deploys chart/tests/test.yaml. OAuth2 Proxy exposes the release over HTTPS using the pinned OAuth2 mock chart, which selects its own matching image.
  2. The review job runs the Helm hooks, including public OIDC discovery, and publishes JUnit results before Cypress starts.
  3. Cypress verifies the email session, waits for visible application controls, and captures a Control UI screenshot and run video. Use these job artifacts to diagnose browser failures.
  4. Cleanup waits for browser and provider validation.

The review release loads the GitLab agent profile published from the same commit as its image. The Work Queue browser test therefore exercises that commit's installed discovery scripts rather than the generic default profile.

The mock identity provider is for review environments only. Configure a real identity provider for production.