Configuration

Agent profiles

An OpenClaw profile is a set of workspace files stored in an ORAS-compatible registry and copied into the workspace at startup. The repository includes example profiles under profile/.

openclaw:
  secrets:
    - name: GITLAB_TOKEN
      value: glpat-
  git:
    user:
      email: "eugene@example.com"
      name: "Eugene Harold Krabs"
  profile:
    registry: registry.gitlab.com
    repository: xrow-public/helm-openclaw/eugene-harold-krabs

GitLab timelogs

The bundled GitLab Agent plugin (gitlab-agent) adds Work Queue and a GitLab timelogs menu item for the signed time entries of the current GitLab user. Group the report by project, work item, or merge request. Filter it by project and sort each displayed data column. The report defaults to the last seven calendar days and accepts any inclusive date range up to 366 days. Totals, entry counts, negative adjustments, and percentage of displayed time are shown in a responsive table.

Timelog reports require only GITLAB_TOKEN in the OpenClaw environment. Add it through openclaw.secrets as shown above. The token stays in the gateway process: the browser requests an aggregated report and never receives the credential or the raw GitLab GraphQL response.

Install the GitLab Agent plugin separately

The same plugin is available as @xrow-public/openclaw-gitlab-agent in the public package registry. It includes both pages and its read-only report helpers; a private workspace profile is not required. See the plugin installation guide for prerequisites, version selection and commands. The Helm chart already bundles and enables it. Replace old gitlab-timelogs and gitlab-work-queue plugin entries with gitlab-agent when migrating an existing custom setup.

Custom OpenClaw configuration

Set openclaw.configuration to a YAML object. By default, session.scope is per-sender, session.dmScope is per-account-channel-peer, and session.groupScope is per-group. Direct messages therefore use separate sessions for each account, channel, and sender. Session tools default to tools.sessions.visibility: self, which limits them to the current session. Override these fields in openclaw.configuration only when the deployment's trust boundary requires a different scope.

The chart serializes the object as literal JSON, without interpreting Go template expressions inside values.

Helm merges custom and chart-managed settings into one rendered openclaw.json. At startup, that file merges with persisted settings. The effective precedence, from lowest to highest, is:

1. The persisted openclaw.json on disk.
2. The custom Helm configuration object.
3. The chart-managed openclaw.json.go.tpl output.

Arrays, scalar values and explicit JSON nulls replace earlier values; arrays are not appended. Unmentioned persisted fields survive. Removing a custom setting from Helm does not delete a value already saved on disk. The new file is written atomically with mode 0600; invalid JSON or a failed merge leaves the previous file intact and stops startup.

At each startup, the pre-start hook also runs openclaw config validate on the effective persisted configuration. A schema-valid file starts without a warning. If schema validation fails, the hook prints a warning and continues to the Gateway; it does not repair the file or print its contents. The Gateway may still reject an invalid configuration. Run openclaw config validate in the container to inspect the error, then correct the Helm value or persisted setting and restart. JSON merge and file I/O errors remain fatal.

The values schema reserves chart-managed paths, including the workspace, authentication mode, proxy user header, browser connection, plugin baseline and Control UI locale. Use dedicated Helm values such as openclaw.trustedProxies for those settings where available. Other OpenClaw fields can be added; the installed OpenClaw runtime performs their final validation. In particular, gateway.auth.trustedProxy accepts requiredHeaders, allowUsers, allowLoopback and deviceAutoApprove; userHeader remains chart-managed. For a deployment already fronted by OAuth2 Proxy:

openclaw:
  configuration:
    gateway:
      auth:
        trustedProxy:
          requiredHeaders:
            - x-forwarded-email
          allowUsers:
            - operator@example.invalid

The additional proxy settings merge with the chart's x-forwarded-user header. Custom settings are stored in a ConfigMap: use OpenClaw secret references or Kubernetes Secret-backed environment variables instead of literal credentials. The final chart layer is authoritative even for persisted settings; for example, a locale saved through the UI is reset to the chart's English locale on restart.

Built-in memory search

The chart enables OpenClaw's built-in memory-core plugin and selects memory.search.provider: "none". Memory search uses local SQLite keyword search, not external embeddings. No embedding API key or credits are required; search matches words rather than semantic similarity. Dreaming remains enabled and uses the configured agent models.

Run openclaw memory status --agent main in the container to check the active provider. Expect Provider: none.

At startup, the chart-managed provider replaces any persisted or custom Helm global memory provider. Unrelated memory settings and existing memory files are preserved. Per-agent memory overrides remain unchanged.

Heartbeat defaults

The chart configures Heartbeat (main) through agents.defaults.heartbeat. OpenClaw maintains the corresponding system automation from this configuration; do not edit the generated heartbeat automation directly.

Helm value	Default	Purpose
openclaw.heartbeat.every	"30m"	Regular checks without frequent wake-ups.
openclaw.heartbeat.target	"none"	Internal-only checks; no external alerts or owner-DM route required.
openclaw.heartbeat.lightContext	true	Skip workspace bootstrap files for lightweight monitor checks.
openclaw.heartbeat.isolatedSession	true	Start each heartbeat without the main conversation history.
openclaw.heartbeat.timeoutSeconds	120	Bound a routine heartbeat turn to two minutes.

These defaults suit WebChat-only installations, where an owner-DM route may not exist. Internal-only delivery does not send alerts. Isolation and lightweight context reduce inherited workload; they do not guarantee that every timeout is resolved. The configured agent model and OpenClaw heartbeat prompt are unchanged. Put a short checklist in the heartbeat monitor scratch when needed. Keep long GitLab tasks in a separate isolated / agentTurn automation with its own timeout; this chart change does not migrate existing automation jobs.

For external alerts, first configure a supported messaging channel, then set its recipient (example identifiers below):

openclaw:
  heartbeat:
    target: telegram
    to: "123456789"
    # accountId: alerts

All heartbeat options can be set under openclaw.heartbeat; unspecified options retain the defaults above. Use every: "0m" to disable recurring checks (targeted event wakes remain possible). Set lightContext: false if a custom heartbeat requires workspace bootstrap files. Additional OpenClaw heartbeat options are validated by the installed runtime.

Upgrades: chart-managed defaults replace matching persisted default settings, including alert routing. Carry existing alert settings into openclaw.heartbeat, or set openclaw.heartbeat: null to leave persisted/runtime settings unmanaged. Per-agent OpenClaw heartbeat overrides and unrelated agent settings are preserved. See the OpenClaw heartbeat reference for routing, monitor scratch and per-agent overrides.

Network access

Use local port forwarding or expose OpenClaw only on a private network. When your cluster enforces NetworkPolicy, enable the chart policy and allow ingress from the namespace that owns your ingress controller:

openclaw:
  networkPolicy:
    enabled: true
    ingress:
      from:
        - namespaceSelector:
            matchLabels:
              kubernetes.io/metadata.name: ingress-nginx

When OAuth2 Proxy fronts the gateway from a separate pod, set openclaw.trustedProxies to the proxy pod network and restrict gateway ingress to OAuth2 Proxy pods. Kubernetes Services do not preserve the Service cluster IP as the proxy's source address.

openclaw:
  trustedProxies:
    - 10.42.0.0/16
  networkPolicy:
    enabled: true
    ingress:
      from:
        - podSelector:
            matchLabels:
              app.kubernetes.io/name: oauth2-proxy
              app.kubernetes.io/instance: openclaw
        - podSelector:
            matchLabels:
              app.kubernetes.io/name: openclaw
              app.kubernetes.io/instance: openclaw

Persistence

By default, the chart creates a PersistentVolumeClaim for /mnt/openclaw.

Use an existing claim when restoring data or migrating a workspace:

openclaw:
  persistence:
    existingClaim: openclaw-workspace

Set openclaw.persistence.enabled=false for ephemeral test deployments. The chart then mounts an emptyDir.

Kubernetes credentials

Provide one or more kubeconfig files through openclaw.kubeconfigs. The chart stores them in a Kubernetes Secret and mounts each credential read-only at /opt/app-root/src/config/kubeconfigs/<name>/.kube/config:

openclaw:
  kubeconfigs:
    production: |-
      apiVersion: v1
      kind: Config
      clusters: []
      contexts: []
      users: []

Select a credential for kubectl by setting KUBECONFIG to its mounted config file. Names must contain lowercase letters, numbers, or hyphens and must start and end with a letter or number.

Browserless

The bundled Browserless service is enabled by default for the OpenClaw browser tool. The generated openclaw.json points at the release-scoped Browserless Service name, for example openclaw-browserless.

Set Browserless chart overrides at the subchart root:

browserless:
  image:
    tag: latest
  resources:
    requests:
      cpu: 250m
      memory: 512Mi

If browserless.browserless.token is set, the generated URL includes a ?token= query parameter.