OpenClaw AI 工作流

Prerequisites

• Kubernetes 1.28+
• Helm 3

Runtime dependencies

Enable built-in init containers that install pnpm or Python/uv to the data PVC for MCP servers and skills:

spec:
  runtimeDeps:
    pnpm: true    # Installs pnpm via corepack
    python: true  # Installs Python 3.12 + uv

2. The agent creates this to install a skill at runtime

apiVersion: openclaw.rocks/v1alpha1 kind: OpenClawSelfConfig metadata: name: add-fetch-skill spec: instanceRef: my-agent addSkills: - "@anthropic/mcp-server-fetch" ```

Every request is validated against the instance's allowlist policy. Protected config keys cannot be overwritten, and denied requests are logged with a reason. See Self-configure for details.

Note: Without selfConfigure enabled, config or skill changes made by the agent inside the container won't trigger a pod restart. You'll need to restart the pod manually (e.g. kubectl delete pod <pod-name>) for changes to take effect.

1. Install the operator

helm install openclaw-operator \
  oci://ghcr.io/paperclipinc/charts/openclaw-operator \
  --namespace openclaw-operator-system \
  --create-namespace

<details> <summary>Alternative: install with Kustomize</summary>

```bash

Install CRDs

make install

Deploy the operator

make deploy IMG=ghcr.io/paperclipinc/openclaw-operator:latest

</details>

<details>
<summary>Restrict the operator to specific namespaces</summary>

To run the operator with namespaced RBAC instead of cluster-wide permissions,
list the namespaces it should watch. The chart switches from
`ClusterRole`/`ClusterRoleBinding` to per-namespace `Role`/`RoleBinding`, and
passes `--watch-namespaces` to the operator so its informer cache is scoped
to that list (plus the operator's own namespace, for backup credentials).

Each listed namespace must already exist; the chart does not create them.

To bring your own RBAC entirely (e.g. managed by a separate controller or
SecurityCenter policy), disable chart-managed RBAC:

The kubebuilder markers in internal/controller/ and the manager rules helper at charts/openclaw-operator/templates/_helpers.tpl document the minimum permission set the operator requires.

</details>

3. Deploy an OpenClaw instance

apiVersion: openclaw.rocks/v1alpha1
kind: OpenClawInstance
metadata:
  name: my-agent
spec:
  envFrom:
    - secretRef:
        name: openclaw-api-keys
  storage:
    persistence:
      enabled: true
      size: 10Gi

kubectl apply -f secret.yaml -f openclawinstance.yaml

Skill installation

Install skills declaratively. The operator runs an init container that fetches each skill before the agent starts. Entries use ClawHub by default, or prefix with npm: to install from npmjs.com. ClawHub installs are idempotent - if a skill is already installed (e.g., when using persistent storage), it is skipped rather than failing:

spec:
  skills:
    - "@anthropic/mcp-server-fetch"       # ClawHub (default)
    - "npm:@openclaw/matrix"              # npm package from npmjs.com

npm lifecycle scripts are disabled globally on the init container (NPM_CONFIG_IGNORE_SCRIPTS=true) to mitigate supply chain attacks.

Plugin installation

Install plugins declaratively. The operator runs a dedicated init container that installs each plugin into ~/.openclaw/extensions/<name>/ before the agent starts, where <name> is the unscoped npm package basename (so @openclaw/brave-plugin becomes ~/.openclaw/extensions/brave-plugin/):

spec:
  plugins:
    - "@martian-engineering/lossless-claw"
    - "some-other-plugin"

This is the layout the OpenClaw gateway's plugin discovery expects - it scans direct subdirectories of ~/.openclaw/extensions/ for plugin manifests and skips node_modules/ entirely. The init container shells out to openclaw plugins install clawhub:<pkg> (the OpenClaw CLI's ClawHub installer) so plugins published with workspace:* dependency markers — such as the first-party @openclaw/matrix — resolve correctly. Raw npm install rejects those with EUNSUPPORTEDPROTOCOL.

npm lifecycle scripts are disabled globally on the init container (NPM_CONFIG_IGNORE_SCRIPTS=true) to mitigate supply chain attacks. The PVC backs ~/.openclaw/, so installs persist across pod restarts.

If you previously worked around the install-path bug by adding plugins.load.paths entries to your gateway config (pointing at ~/.openclaw/node_modules/<pkg>), that workaround is no longer needed and can be removed - plugins now land in the documented location and are auto-discovered.

Quick Start

1. Enable self-configure on the instance

spec: selfConfigure: enabled: true allowedActions: [skills, config, envVars, workspaceFiles]

Configuration

Inline config (openclaw.json)

spec:
  config:
    raw:
      agents:
        defaults:
          model:
            primary: "anthropic/claude-sonnet-4-20250514"
          sandbox: true
      session:
        scope: "per-sender"

External ConfigMap reference

spec:
  config:
    configMapRef:
      name: my-openclaw-config
      key: openclaw.json

Config changes are detected via SHA-256 hashing and automatically trigger a rolling update. No manual restart needed.

Config merge mode

By default, the operator overwrites the config file on every pod restart. Set mergeMode: merge to deep-merge operator config with existing PVC config, preserving runtime changes made by the agent:

spec:
  config:
    mergeMode: merge
    raw:
      agents:
        defaults:
          model:
            primary: "anthropic/claude-sonnet-4-20250514"

Caveat: In merge mode, removing a key from the CR does not remove it from the PVC config - the old value persists because deep-merge only adds or updates keys. If you need to remove stale config keys (e.g., after removing gateway.mode: local), temporarily switch to mergeMode: overwrite, apply, wait for the pod to restart, then switch back to merge.

Self-configure

Allow agents to modify their own configuration by creating OpenClawSelfConfig resources via the K8s API. The operator validates each request against the instance's allowedActions policy before applying changes:

spec:
  selfConfigure:
    enabled: true
    allowedActions:
      - skills        # add/remove skills
      - config        # patch openclaw.json
      - workspaceFiles # add/remove workspace files
      - envVars       # add/remove environment variables

When enabled, the operator: - Grants the instance's ServiceAccount RBAC permissions to read its own CRD and create OpenClawSelfConfig resources - Enables SA token automounting so the agent can authenticate with the K8s API - Injects a SELFCONFIG.md skill file and selfconfig.sh helper script into the workspace - Opens port 6443 egress in the NetworkPolicy for K8s API access

The agent creates a request like:

apiVersion: openclaw.rocks/v1alpha1
kind: OpenClawSelfConfig
metadata:
  name: add-fetch-skill
spec:
  instanceRef: my-agent
  addSkills:
    - "@anthropic/mcp-server-fetch"

The operator validates the request, applies it to the parent OpenClawInstance, and sets the request's status to Applied, Denied, or Failed. Terminal requests are auto-deleted after 1 hour.

GitOps Coexistence

SelfConfig uses Kubernetes Server-Side Apply (SSA) with the field manager name openclaw-selfconfig. This enables safe coexistence with GitOps controllers (FluxCD, ArgoCD, etc.) that manage the same OpenClawInstance resource:

• Per-item ownership -- Skills (set items), env vars (map items by name), and workspace files (map fields) are tracked individually. A SelfConfig can add or remove only the items it owns without conflicting with items managed by other controllers.
• Atomic ownership -- The config.raw field is owned atomically. If a GitOps controller also manages config.raw, ForceOwnership transfers ownership to the SelfConfig field manager on apply.
• Removal safety -- When a SelfConfig attempts to remove an item owned by another field manager, the operator emits a Warning / SelfConfigSkippedRemoval event identifying the owning manager and includes the warning in the status message.
• Non-SSA users are unaffected -- If you do not use selfConfigure, no SSA field managers are created and existing workflows remain unchanged.

See the API reference for the full OpenClawSelfConfig CRD spec and spec.selfConfigure fields.

2. Create a secret with your API keys

apiVersion: v1
kind: Secret
metadata:
  name: openclaw-api-keys
type: Opaque
stringData:
  ANTHROPIC_API_KEY: "sk-ant-..."

Tailscale integration

Expose your instance via Tailscale Serve (tailnet-only) or Funnel (public internet) - no Ingress or LoadBalancer needed:

spec:
  tailscale:
    enabled: true
    mode: serve          # "serve" (tailnet only) or "funnel" (public internet)
    authKeySecretRef:
      name: tailscale-auth
    authSSO: true        # allow passwordless login for tailnet members
    hostname: my-agent   # defaults to instance name
    image:
      repository: ghcr.io/tailscale/tailscale  # default
      tag: latest
    resources:
      requests:
        cpu: 50m
        memory: 64Mi
      limits:
        cpu: 200m
        memory: 256Mi

When enabled, the operator runs a Tailscale sidecar (tailscaled) that handles serve/funnel declaratively via TS_SERVE_CONFIG. An init container copies the tailscale CLI binary to a shared volume so the main container can call tailscale whois for SSO authentication. The sidecar runs in userspace mode (TS_USERSPACE=true) - no NET_ADMIN capability needed.

State persistence: Tailscale node identity and TLS certificates are automatically persisted to a Kubernetes Secret (<instance>-ts-state) via TS_KUBE_SECRET. This prevents hostname incrementing (device-1, device-2, ...) and Let's Encrypt certificate re-issuance across pod restarts. The operator pre-creates the state Secret, grants the pod's ServiceAccount get/update/patch access to it, and mounts the SA token automatically.

Use ephemeral+reusable auth keys from the Tailscale admin console. When authSSO is enabled, tailnet members can authenticate without a gateway token.