"Return only JSON" is one of the most common instructions in production LLM apps — and one of the least reliable. Models wrap JSON in markdown fences, add a friendly sentence, or (if they're reasoning models) narrate their entire thought process around it. Any of those breaks a strict JSON.parse, and your pipeline falls over.

In this guide we build a Promptfoo eval that makes WEC Inference API models classify support tickets into schema-validated JSON, then harden it against real-world messiness — and use it to pick a model you can actually trust. This is part 2 of the evals series (see part 1 for first-run setup). Everything here was run live against https://inference.wiline.com.

How the eval works​

Every test runs through the same pipeline. The detail that matters most: the transform runs on the model's output before the assertion sees it — that's what lets us recover messy JSON before validating it.

Prerequisites​

• A WEC Inference API key — see Inference → API Keys.

• The model names used here (GLM-5.2, gemma4, Qwen2.5-3B-Instruct, qwen3.5:9B) come from the Models Hub — swap in whatever you've enabled.

• Node.js 22+ and your key exported (Promptfoo runs via npx):

  nvm use 24
  export WEC_API_KEY='sk-your-key'
  

Step 1 — A strict schema, and a real failure​

We'll do something closer to a real workload than "capital of France": classify a support ticket into category, priority, and a short summary. The key upgrade over a basic check is the JSON Schema — it enforces enums, so a model that invents a category fails.

cat > promptfooconfig.yaml <<'EOF'
description: "WEC Inference API — structured output (JSON schema)"
providers:
  - id: openai:chat:zai-org/GLM-5.2
    config:
      apiBaseUrl: https://inference.wiline.com/v1
      apiKeyEnvar: WEC_API_KEY
      temperature: 0
prompts:
  - |
    Classify this support ticket. Return ONLY JSON with keys:
    "category" (one of: billing, technical, account, other),
    "priority" (one of: low, medium, high),
    "summary" (string, max 12 words).
    Ticket: {{ticket}}
defaultTest:
  assert:
    - type: is-json
      value:
        type: object
        required: [category, priority, summary]
        properties:
          category: { type: string, enum: [billing, technical, account, other] }
          priority: { type: string, enum: [low, medium, high] }
          summary: { type: string }
tests:
  - vars: { ticket: "I was charged twice for my instance this month." }
    assert: [{ type: icontains, value: billing }]
  - vars: { ticket: "My VM won't boot after the latest snapshot restore." }
    assert: [{ type: icontains, value: technical }]
EOF
npx -y promptfoo@latest eval -c promptfooconfig.yaml

The result — 50%, and the failure is instructive:

ticket                                    [zai-org/GLM-5.2]
I was charged twice for my instance…      [FAIL] ```json
                                          { "category": "billing", "priority": "high", … }
                                          ```
My VM won't boot after the latest…        [PASS] { "category": "technical", … }

✓ 1 passed (50%)   ✗ 1 failed (50%)

Figure 1. Same model, same prompt, temperature 0 — one response is clean, the other is wrapped in ```json fences, so is-json can't parse it.

The content is correct; the format isn't. is-json validates both "is it parseable JSON" and "does it match the schema" — and fenced output fails the first test.

Step 2 — Recover fenced output with a transform​

A transform runs on the model's output before assertions. Here we strip the fences. (This block uses four backticks because the config itself contains triple backticks.)

cat > promptfooconfig.yaml <<'EOF'
description: "WEC Inference API — fence-stripping transform"
providers:
  - id: openai:chat:zai-org/GLM-5.2
    config:
      apiBaseUrl: https://inference.wiline.com/v1
      apiKeyEnvar: WEC_API_KEY
      temperature: 0
prompts:
  - |
    Classify this support ticket. Return ONLY JSON with keys:
    "category" (one of: billing, technical, account, other),
    "priority" (one of: low, medium, high),
    "summary" (string, max 12 words).
    Ticket: {{ticket}}
defaultTest:
  options:
    transform: |
      return output.replace(/```json\n?|\n?```/g, '').trim();
  assert:
    - type: is-json
      value:
        type: object
        required: [category, priority, summary]
        properties:
          category: { type: string, enum: [billing, technical, account, other] }
          priority: { type: string, enum: [low, medium, high] }
          summary: { type: string }
tests:
  - vars: { ticket: "I was charged twice for my instance this month." }
    assert: [{ type: icontains, value: billing }]
  - vars: { ticket: "My VM won't boot after the latest snapshot restore." }
    assert: [{ type: icontains, value: technical }]
EOF
npx -y promptfoo@latest eval -c promptfooconfig.yaml --no-cache

Now both pass — 2/2. The fences are stripped before is-json sees the output.

Figure 2. The transform removes the code fences, so the previously-failing ticket parses.

Step 3 — The cleaner fix: JSON mode​

Rather than clean up after the model, ask the API to only emit valid JSON via response_format. No transform this time:

cat > promptfooconfig.yaml <<'EOF'
description: "WEC Inference API — JSON mode (response_format)"
providers:
  - id: openai:chat:zai-org/GLM-5.2
    config:
      apiBaseUrl: https://inference.wiline.com/v1
      apiKeyEnvar: WEC_API_KEY
      temperature: 0
      response_format: { type: json_object }
prompts:
  - |
    Classify this support ticket. Return ONLY JSON with keys:
    "category" (one of: billing, technical, account, other),
    "priority" (one of: low, medium, high),
    "summary" (string, max 12 words).
    Ticket: {{ticket}}
defaultTest:
  assert:
    - type: is-json
      value:
        type: object
        required: [category, priority, summary]
        properties:
          category: { type: string, enum: [billing, technical, account, other] }
          priority: { type: string, enum: [low, medium, high] }
          summary: { type: string }
tests:
  - vars: { ticket: "I was charged twice for my instance this month." }
    assert: [{ type: icontains, value: billing }]
  - vars: { ticket: "My VM won't boot after the latest snapshot restore." }
    assert: [{ type: icontains, value: technical }]
EOF
npx -y promptfoo@latest eval -c promptfooconfig.yaml --no-cache

2/2 PASS with no transform — looks like JSON mode works.

Figure 3. With response_format: json_object, GLM-5.2 returns clean JSON, no transform needed.

But before trusting response_format, we need to test it across models — because a single green result can be luck, not enforcement.

Step 4 — Reliability matrix across WEC models​

Run the JSON-mode config against all four chat models. This is the payoff — a WEC-specific reliability comparison you can't get from a generic leaderboard.

cat > promptfooconfig.yaml <<'EOF'
description: "WEC Inference API — JSON-mode reliability across models"
providers:
  - id: openai:chat:zai-org/GLM-5.2
    config: { apiBaseUrl: https://inference.wiline.com/v1, apiKeyEnvar: WEC_API_KEY, temperature: 0, response_format: { type: json_object } }
  - id: openai:chat:gemma4
    config: { apiBaseUrl: https://inference.wiline.com/v1, apiKeyEnvar: WEC_API_KEY, temperature: 0, response_format: { type: json_object } }
  - id: openai:chat:Qwen2.5-3B-Instruct
    config: { apiBaseUrl: https://inference.wiline.com/v1, apiKeyEnvar: WEC_API_KEY, temperature: 0, response_format: { type: json_object } }
  - id: openai:chat:qwen3.5:9B
    config: { apiBaseUrl: https://inference.wiline.com/v1, apiKeyEnvar: WEC_API_KEY, temperature: 0, response_format: { type: json_object } }
prompts:
  - |
    Classify this support ticket. Return ONLY JSON with keys:
    "category" (one of: billing, technical, account, other),
    "priority" (one of: low, medium, high),
    "summary" (string, max 12 words).
    Ticket: {{ticket}}
defaultTest:
  assert:
    - type: is-json
      value:
        type: object
        required: [category, priority, summary]
        properties:
          category: { type: string, enum: [billing, technical, account, other] }
          priority: { type: string, enum: [low, medium, high] }
          summary: { type: string }
tests:
  - vars: { ticket: "I was charged twice for my instance this month." }
    assert: [{ type: icontains, value: billing }]
  - vars: { ticket: "My VM won't boot after the latest snapshot restore." }
    assert: [{ type: icontains, value: technical }]
EOF
npx -y promptfoo@latest eval -c promptfooconfig.yaml --no-cache

4/8. GLM-5.2 and Qwen2.5-3B pass cleanly; gemma4 and qwen3.5:9B dump their reasoning ("Thinking Process…") instead of JSON — despite response_format being set.

Figure 4. response_format set on all four — but the two reasoning-oriented models ignore it.

Step 5 — Verify: is response_format doing anything?​

Don't assume the reasoning was caused by JSON mode. Re-run the same matrix without response_format (using the fence-strip transform instead) and compare:

cat > promptfooconfig.yaml <<'EOF'
description: "WEC Inference API — matrix without response_format"
providers:
  - id: openai:chat:zai-org/GLM-5.2
    config: { apiBaseUrl: https://inference.wiline.com/v1, apiKeyEnvar: WEC_API_KEY, temperature: 0 }
  - id: openai:chat:gemma4
    config: { apiBaseUrl: https://inference.wiline.com/v1, apiKeyEnvar: WEC_API_KEY, temperature: 0 }
  - id: openai:chat:Qwen2.5-3B-Instruct
    config: { apiBaseUrl: https://inference.wiline.com/v1, apiKeyEnvar: WEC_API_KEY, temperature: 0 }
  - id: openai:chat:qwen3.5:9B
    config: { apiBaseUrl: https://inference.wiline.com/v1, apiKeyEnvar: WEC_API_KEY, temperature: 0 }
prompts:
  - |
    Classify this support ticket. Return ONLY JSON with keys:
    "category" (one of: billing, technical, account, other),
    "priority" (one of: low, medium, high),
    "summary" (string, max 12 words).
    Ticket: {{ticket}}
defaultTest:
  options:
    transform: |
      return output.replace(/```json\n?|\n?```/g, '').trim();
  assert:
    - type: is-json
      value:
        type: object
        required: [category, priority, summary]
        properties:
          category: { type: string, enum: [billing, technical, account, other] }
          priority: { type: string, enum: [low, medium, high] }
          summary: { type: string }
tests:
  - vars: { ticket: "I was charged twice for my instance this month." }
    assert: [{ type: icontains, value: billing }]
  - vars: { ticket: "My VM won't boot after the latest snapshot restore." }
    assert: [{ type: icontains, value: technical }]
EOF
npx -y promptfoo@latest eval -c promptfooconfig.yaml --no-cache

Still 4/8 — the exact same models fail. So response_format changed nothing: on WEC today it's effectively a no-op (the backend isn't enforcing JSON mode). The reasoning behavior belongs to the models, not to the flag.

Figure 5. Identical result without JSON mode — the flag wasn't doing anything.

Step 6 — A more robust transform: extract the JSON​

The reasoning models do emit JSON — it's just buried in prose. Instead of stripping fences, extract the first { … } block from anywhere in the output:

cat > promptfooconfig.yaml <<'EOF'
description: "WEC Inference API — JSON extraction transform"
providers:
  - id: openai:chat:zai-org/GLM-5.2
    config: { apiBaseUrl: https://inference.wiline.com/v1, apiKeyEnvar: WEC_API_KEY, temperature: 0 }
  - id: openai:chat:gemma4
    config: { apiBaseUrl: https://inference.wiline.com/v1, apiKeyEnvar: WEC_API_KEY, temperature: 0 }
  - id: openai:chat:Qwen2.5-3B-Instruct
    config: { apiBaseUrl: https://inference.wiline.com/v1, apiKeyEnvar: WEC_API_KEY, temperature: 0 }
  - id: openai:chat:qwen3.5:9B
    config: { apiBaseUrl: https://inference.wiline.com/v1, apiKeyEnvar: WEC_API_KEY, temperature: 0 }
prompts:
  - |
    Classify this support ticket. Return ONLY JSON with keys:
    "category" (one of: billing, technical, account, other),
    "priority" (one of: low, medium, high),
    "summary" (string, max 12 words).
    Ticket: {{ticket}}
defaultTest:
  options:
    transform: |
      const m = output.match(/\{[\s\S]*\}/);
      return m ? m[0] : output;
  assert:
    - type: is-json
      value:
        type: object
        required: [category, priority, summary]
        properties:
          category: { type: string, enum: [billing, technical, account, other] }
          priority: { type: string, enum: [low, medium, high] }
          summary: { type: string }
tests:
  - vars: { ticket: "I was charged twice for my instance this month." }
    assert: [{ type: icontains, value: billing }]
  - vars: { ticket: "My VM won't boot after the latest snapshot restore." }
    assert: [{ type: icontains, value: technical }]
EOF
npx -y promptfoo@latest eval -c promptfooconfig.yaml --no-cache

7/8 — a big jump. gemma4 and Qwen2.5 fully recover; qwen3.5:9B recovers one of two. The one remaining failure is telling: that response emitted JSON and then kept reasoning (with more braces), so the greedy { … } match over-captured and produced invalid JSON.

Figure 6. Extracting the JSON block recovers the chatty models — but it's a heuristic, not a guarantee (note the one over-capture failure).

Step 7 — See it in the browser​

The terminal table is fine for a quick read, but the web report is where a matrix like this comes alive:

npx -y promptfoo@latest view

The dashboard at the top gives you the model-reliability picture at a glance — the Pass Rate (%) bars are the ones to watch here: three models tall, qwen3.5:9B sitting at 50%. Below, each provider is a column you can expand to the full response (that's how we pulled the over-capture failure in Figure 10 — the terminal truncates it).

Figure 7. The report's dashboard — the Pass Rate bars turn the model matrix into a one-glance ranking, and any cell expands to the full output.

Step 8 — Gate it in CI​

Promptfoo exits non-zero when tests fail, so a one-liner is a gate (put it in a script or Makefile, never your interactive shell):

npx -y promptfoo@latest eval -c promptfooconfig.yaml \
  && echo "✅ passed" \
  || { echo "❌ eval failed — blocking"; exit 1; }

Figure 8. A real failure blocks: 7/8 passed, but qwen3.5:9B's over-capture (from Step 6) trips the gate — the non-zero exit code is the signal CI uses to block a PR.

On GitLab:

eval:
  image: node:22
  script:
    - npx -y promptfoo@latest eval -c promptfooconfig.yaml
  # WEC_API_KEY set as a masked CI/CD variable — never committed.

What we learned​

• Model choice dominates. GLM-5.2 and Qwen2.5-3B reliably produce schema-valid JSON and are ~8× cheaper than the reasoning models. For structured output on WEC, start there.
• Reasoning models (qwen3.5:9B, and gemma4 on the day we tested) narrate their thinking and cost far more — poor fits for strict JSON.
• A transform is your safety net — fence-stripping recovers the common case; JSON extraction recovers most chatty output — but extraction is a heuristic that can over-capture.
• response_format is a no-op on WEC today — verified by isolating it. Don't rely on it; validate instead.
• The eval is the point. Every one of these surprises was caught automatically, before it reached production.

Troubleshooting​

"Transform function did not return a value"​

A multi-line transform is compiled as a function body, so it needs an explicit return. output.replace(...) on its own returns nothing.

options:
  transform: |
    return output.replace(/.../g, '').trim();   # note the `return`

Figure 9. Without return, Promptfoo errors instead of transforming.

A model returns reasoning around the JSON​

If is-json fails with "Expected output to be valid JSON" and the response contains a "Thinking Process…" / "Final Review…" narration, you're using a reasoning model. Sometimes it emits only reasoning; sometimes — as below — it emits valid JSON and then keeps talking, so even the Step 6 extraction over-captures and the parse fails. Options: switch to GLM-5.2 / Qwen2.5-3B, or accept that the extraction transform is best-effort, not a guarantee.

Figure 10. The failing case expanded in the report: qwen3.5:9B returned valid JSON and then kept reasoning ("7. Final Review…"), so the extraction over-captured and the assertion reports "Expected output to be valid JSON."

"Cannot convert argument to a ByteString"​

Your pasted API key contains an invisible Unicode character. Strip it:

export WEC_API_KEY=$(printf '%s' "$WEC_API_KEY" | LC_ALL=C tr -cd '[:print:]')

Figure 11. A stray character in the key trips the HTTP header before any request is sent.

What's next​

• DeepEval regression suites — turn these checks into a versioned, CI-gated regression run.
• Tracing — see why a response went wrong, not just that it failed.

Have a structured-output case that still slips through? That's the next test to add.

You wouldn't ship code without tests — but most teams ship LLM features on "looks good to me." Evaluations (evals) fix that: you define test cases and pass/fail criteria, then measure your model objectively — catching regressions, comparing models, and gating deploys.

In this guide you'll build a real eval harness with Promptfoo pointed at the WEC Inference API — the same OpenAI-compatible endpoint you call from your apps. Everything here was run live against https://inference.wiline.com; the outputs are real.

Prerequisites​

• A WEC (WiLine Edge Cloud) account and an Inference API key — see Inference → API Keys.

• Node.js 22+. Promptfoo treats Node 20 as end-of-life; with nvm:

  nvm install 24      # 24 LTS preferred
  nvm use 24
  node -v             # v24.x
  

We'll run Promptfoo with npx — nothing to install globally.

Figure 1. Create a key under Inference → API Keys, then copy it.

Put your key in the shell:

export WEC_API_KEY='sk-your-key-here'

Step 1 — See which models you have​

The API is OpenAI-compatible, so the model list is a plain GET /v1/models:

curl -s https://inference.wiline.com/v1/models \
  -H "Authorization: Bearer $WEC_API_KEY" | jq -r '.data[].id'

zai-org/GLM-5.2
gemma4
Qwen2.5-3B-Instruct
qwen3.5:9B
whisper-large-v3
whisper-medium
whisper-base

The whisper-* models are speech-to-text; the rest are chat models. We'll evaluate the chat models, starting with zai-org/GLM-5.2.

Step 2 — Your first eval​

Create a config. apiBaseUrl points Promptfoo at WEC; apiKeyEnvar tells it which env var holds your key:

cat > promptfooconfig.yaml <<'EOF'
description: "WEC Inference API eval"
providers:
  - id: openai:chat:zai-org/GLM-5.2
    config:
      apiBaseUrl: https://inference.wiline.com/v1
      apiKeyEnvar: WEC_API_KEY
      temperature: 0
prompts:
  - "Answer in a single word. What is the capital of {{country}}?"
tests:
  - vars: { country: France }
    assert: [{ type: icontains, value: Paris }]
  - vars: { country: Japan }
    assert: [{ type: icontains, value: Tokyo }]
EOF
npx -y promptfoo@latest eval -c promptfooconfig.yaml

Figure 4. Your first passing eval against the WEC Inference API.

icontains is a deterministic assertion — a case-insensitive substring check. Cheap, fast, and perfect for facts with a known answer.

Step 3 — The visual report​

npx -y promptfoo@latest view

This opens a local web UI with every prompt, output, and pass/fail — far easier to scan than the terminal once you have more than a handful of cases.

Figure 5. promptfoo view — the same results in the browser.

Step 4 — Add a second model​

Adding a provider is one extra block. Here we add Qwen2.5-3B-Instruct alongside GLM-5.2 and run the same two test cases against both:

cat > promptfooconfig.yaml <<'EOF'
description: "WEC Inference API eval — model comparison"
providers:
  - id: openai:chat:zai-org/GLM-5.2
    config:
      apiBaseUrl: https://inference.wiline.com/v1
      apiKeyEnvar: WEC_API_KEY
      temperature: 0
  - id: openai:chat:Qwen2.5-3B-Instruct
    config:
      apiBaseUrl: https://inference.wiline.com/v1
      apiKeyEnvar: WEC_API_KEY
      temperature: 0
prompts:
  - "Answer in a single word. What is the capital of {{country}}?"
tests:
  - vars: { country: France }
    assert: [{ type: icontains, value: Paris }]
  - vars: { country: Japan }
    assert: [{ type: icontains, value: Tokyo }]
EOF
npx -y promptfoo@latest eval -c promptfooconfig.yaml

Figure 6. Both models pass. GLM-5.2's results are served from cache (0 new requests); only Qwen2.5 makes live calls.

Step 5 — Grade quality, not substrings (LLM rubric)​

Substring checks can't judge an open-ended answer. A model-graded llm-rubric assertion uses a model to score the output against criteria — and the grader can run on WEC too, so you need no external provider:

cat > promptfooconfig.yaml <<'EOF'
description: "WEC Inference API eval — model-graded (LLM rubric)"
providers:
  - id: openai:chat:zai-org/GLM-5.2
    config:
      apiBaseUrl: https://inference.wiline.com/v1
      apiKeyEnvar: WEC_API_KEY
      temperature: 0
defaultTest:
  options:
    provider:                       # the grader model
      id: openai:chat:zai-org/GLM-5.2
      config:
        apiBaseUrl: https://inference.wiline.com/v1
        apiKeyEnvar: WEC_API_KEY
prompts:
  - "Explain what a {{topic}} is in two sentences, for a beginner."
tests:
  - vars: { topic: VPC }
    assert:
      - type: llm-rubric
        value: "Describes a VPC as a private, isolated virtual network in the cloud, and is understandable to a beginner."
EOF
npx -y promptfoo@latest eval -c promptfooconfig.yaml

Figure 7. The run shows two token lines — Eval (75) and Grading (350) — because the rubric check is itself a model call.

Model-graded checks are powerful, but they aren't free.

Step 6 — Guardrails: latency​

A correct answer that takes 30 seconds is still a production problem. Add a latency guardrail to defaultTest (it applies to every case). Always run with --no-cache — cached responses report ~0 ms and would pass the gate for free:

cat > promptfooconfig.yaml <<'EOF'
description: "WEC Inference API eval — latency guardrail"
providers:
  - id: openai:chat:zai-org/GLM-5.2
    config:
      apiBaseUrl: https://inference.wiline.com/v1
      apiKeyEnvar: WEC_API_KEY
      temperature: 0
defaultTest:
  assert:
    - type: latency
      threshold: 5000        # fail anything slower than 5 s
prompts:
  - "Answer in a single word. What is the capital of {{country}}?"
tests:
  - vars: { country: France }
    assert: [{ type: icontains, value: Paris }]
  - vars: { country: Japan }
    assert: [{ type: icontains, value: Tokyo }]
EOF
npx -y promptfoo@latest eval -c promptfooconfig.yaml --no-cache

This failed — the answers were correct (Paris, Tokyo) but both calls took ~33 s, tripping the 5 s gate:

Figure 8. The guardrail fires: correct answers, wrong latency. Duration: 33s.

Bump the threshold to something realistic and re-run:

sed -i 's/threshold: 5000/threshold: 60000/' promptfooconfig.yaml
npx -y promptfoo@latest eval -c promptfooconfig.yaml --no-cache

Figure 9. With a 60 s threshold the same calls pass easily — Duration: 2s.

Step 7 — Guardrails: latency + token cap​

The cost assertion doesn't work against WEC (see Troubleshooting #2). Use latency + max_tokens together as your production guardrail instead:

cat > promptfooconfig.yaml <<'EOF'
description: "WEC Inference API eval — guardrails (latency + token cap)"
providers:
  - id: openai:chat:zai-org/GLM-5.2
    config:
      apiBaseUrl: https://inference.wiline.com/v1
      apiKeyEnvar: WEC_API_KEY
      temperature: 0
      max_tokens: 16
defaultTest:
  assert:
    - type: latency
      threshold: 30000
prompts:
  - "Answer in a single word. What is the capital of {{country}}?"
tests:
  - vars: { country: France }
    assert: [{ type: icontains, value: Paris }]
  - vars: { country: Japan }
    assert: [{ type: icontains, value: Tokyo }]
EOF
npx -y promptfoo@latest eval -c promptfooconfig.yaml --no-cache

Figure 11. With a 30 s threshold and a 16-token cap, both cases pass.

Step 8 — Validate structured output (JSON schema)​

Real apps want JSON, not prose. is-json checks the output is valid JSON and matches a schema in one assertion:

cat > promptfooconfig.yaml <<'EOF'
description: "WEC Inference API eval — JSON schema validation"
providers:
  - id: openai:chat:zai-org/GLM-5.2
    config:
      apiBaseUrl: https://inference.wiline.com/v1
      apiKeyEnvar: WEC_API_KEY
      temperature: 0
prompts:
  - 'Return ONLY a JSON object (no markdown, no prose) with keys "capital" (string) and "population_millions" (number) for the country {{country}}.'
defaultTest:
  assert:
    - type: is-json
      value:
        type: object
        required: [capital, population_millions]
        properties:
          capital: { type: string }
          population_millions: { type: number }
tests:
  - vars: { country: France }
    assert: [{ type: icontains, value: Paris }]
  - vars: { country: Japan }
    assert: [{ type: icontains, value: Tokyo }]
EOF
npx -y promptfoo@latest eval -c promptfooconfig.yaml

Figure 12. GLM-5.2 returns compact, schema-valid JSON on the first try.

Step 9 — The payoff: compare every WEC model​

Here's what you can't get anywhere else — the same strict-JSON test across all the chat models on your account:

cat > promptfooconfig.yaml <<'EOF'
description: "WEC Inference API eval — model matrix"
providers:
  - id: openai:chat:zai-org/GLM-5.2
    config: { apiBaseUrl: https://inference.wiline.com/v1, apiKeyEnvar: WEC_API_KEY, temperature: 0 }
  - id: openai:chat:gemma4
    config: { apiBaseUrl: https://inference.wiline.com/v1, apiKeyEnvar: WEC_API_KEY, temperature: 0 }
  - id: openai:chat:Qwen2.5-3B-Instruct
    config: { apiBaseUrl: https://inference.wiline.com/v1, apiKeyEnvar: WEC_API_KEY, temperature: 0 }
  - id: openai:chat:qwen3.5:9B
    config: { apiBaseUrl: https://inference.wiline.com/v1, apiKeyEnvar: WEC_API_KEY, temperature: 0 }
prompts:
  - 'Return ONLY a JSON object (no markdown, no prose) with keys "capital" (string) and "population_millions" (number) for the country {{country}}.'
defaultTest:
  assert:
    - type: is-json
      value:
        type: object
        required: [capital, population_millions]
        properties:
          capital: { type: string }
          population_millions: { type: number }
tests:
  - vars: { country: France }
    assert: [{ type: icontains, value: Paris }]
  - vars: { country: Japan }
    assert: [{ type: icontains, value: Tokyo }]
  - vars: { country: Brazil }
    assert: [{ type: icontains, value: Bras }]
EOF
npx -y promptfoo@latest eval -c promptfooconfig.yaml

Figure 13a. 12 test cases across 4 models — 9 pass, 3 fail. qwen3.5:9B emits its chain-of-thought instead of JSON.

Figure 13b. The token breakdown tells the real story: the reasoning model cost 13× more for the same task.

Two lessons fall out immediately:

• qwen3.5:9B is a reasoning model. It "thinks out loud," so it breaks strict JSON unless you strip the reasoning or use a response-format constraint. Picking it for structured output would silently fail.
• Cost varies ~13×. The reasoning model burned 2,650 tokens for the same task the others did in ~200. For a JSON extraction job, the smaller models are both correct and far cheaper.

That's a model-selection decision you can now defend with data — for your workloads, not a generic leaderboard.

Step 10 — Make it a gate​

Promptfoo exits non-zero (100) when any test fails. Verify this first:

npx -y promptfoo@latest eval -c promptfooconfig.yaml > /dev/null 2>&1; echo "exit code: $?"

Figure 14. Exit code 100 confirms Promptfoo signals failure reliably — exactly what CI needs.

Wire it up as a gate:

npx -y promptfoo@latest eval -c promptfooconfig.yaml \
  && echo "✅ eval passed" \
  || { echo "❌ eval failed — blocking"; exit 1; }

Figure 15a. The gate re-runs the matrix eval from cache — same 9/3 result.

Figure 15b. Promptfoo exits non-zero, the || branch fires, and the gate blocks.

In CI, you don't even need the exit 1 — the non-zero exit fails the job. On GitLab:

eval:
  image: node:22
  script:
    - npx -y promptfoo@latest eval -c promptfooconfig.yaml
  # WEC_API_KEY is set as a masked CI/CD variable — never commit it.

Now a prompt change that quietly breaks JSON output, or a model swap that doubles latency, fails the pipeline before it reaches users.

Troubleshooting (real errors)​

1. ByteString error on first eval​

API call error: TypeError: Cannot convert argument to a ByteString because
the character at index 32 has a value of 8232 which is greater than 255.

Figure 2. Every API call errors before reaching the server — the key never even leaves the machine.

Cause: The pasted key contains an invisible Unicode character — U+2028 (line separator). Some terminals and clipboard managers insert it silently when copying from certain sources.

Fix: Strip non-printable characters from the key:

export WEC_API_KEY=$(printf '%s' "$WEC_API_KEY" | LC_ALL=C tr -cd '[:print:]')
printf 'len=%s\n' "$(printf %s "$WEC_API_KEY" | wc -c)"
# len=25

Figure 3. After stripping, the key length confirms no extra characters remain. Re-run the eval — it passes.

2. Cost assertion errors immediately​

Error: Cost assertion does not support providers that do not return cost

Figure 10. The WEC Inference API doesn't return a cost field in its responses.

Cause: Promptfoo calculates cost by looking up a price-per-token for the model in its built-in price list and multiplying by the tokens used. It has prices for the big hosted models but not for WEC's self-hosted model names, so it has no price to apply and the assertion fails. (Most APIs, including OpenAI, don't return a dollar cost in the response — tools compute it.)

Fix: Skip the cost assertion entirely. Track spend from the Total Tokens line Promptfoo prints at the end of every run, and use max_tokens in the provider config to cap per-call token usage.

3. exit 1 closes your SSH session​

❌ eval failed — blocking
logout
Connection to 10.80.4.212 closed.

Cause: Running || { echo "❌ eval failed — blocking"; exit 1; } directly in an interactive shell exits the shell process itself — which, over SSH, closes the connection.

Fix: Put the gate in a non-interactive context: a Makefile target, an npm script, a git pre-commit hook, or a CI job. In those environments exit 1 fails the job without touching your terminal. If you need to test the gate locally, use || echo "❌ eval failed" (without exit 1) to see the output safely.

What's next​

You've gone from "looks good to me" to a real, automatable eval harness on WEC — with deterministic checks, guardrails, schema validation, model-graded rubrics, a model matrix, and a CI gate.

Coming up in this series:

• Trustworthy JSON: schema-validate your model's structured output — now available (part 2): recover fenced and reasoning-wrapped output with transforms, compare models for JSON reliability, and gate it all in CI.
• Model-graded evals done right — calibrating llm-rubric, factuality scoring, and multi-judge checks so your grader is trustworthy.
• Catching hallucinations — pairing these techniques with WEC's RAG hallucination evaluation.
• Evaluating audio — scoring Whisper transcription accuracy on the WEC Inference API.

Hermes Agent is Nous Research's open-source (MIT) AI agent — "the agent that grows with you." Its standout feature is persistent memory: it learns your projects and doesn't forget across restarts. This guide deploys it on the same WEC Instance you already use for OpenClaw, points it at a model, and proves the memory survives a full reboot.

Why persistent memory matters​

An agent that forgets on every restart is a toy. Hermes keeps a durable store on disk under ~/.hermes/:

• ~/.hermes/memories/MEMORY.md — a human-readable file of facts the agent has chosen to remember.
• ~/.hermes/state.db — a SQLite database holding every session and message, with FTS5 full-text search indexes layered on top so the agent can search its own history.

A deploy, crash, or reboot doesn't wipe what it learned. That's the difference between a chat demo and an agent you can rely on day to day — and it's exactly what we test at the end.

The moving parts​

Everything runs on one WEC Instance. Hermes talks to a model over the WEC Inference API, keeps its memory on local disk, and runs as a systemd user service — so it restarts itself after a reboot and its memory is still there:

Prerequisites​

• An existing WEC Instance with shell access (the OpenClaw box works).
• A model: either a Nous Portal login, or your own provider API key (we use an OpenAI key here; WEC Models with glm-5.2 works too).
• Nothing to pre-install — the installer handles Python, Node.js, and the browser engine.

Step 1 — Install Hermes​

curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash

The installer resolves a Python virtual environment with uv, installs the Node.js browser tools, downloads a Playwright Chromium, syncs the bundled skills, and drops a hermes launcher into ~/.local/bin:

✓ Main package installed (hash-verified via uv.lock)
✓ All dependencies installed
✓ Browser engine setup complete
✓ Installed hermes launcher → ~/.local/bin/hermes
✓ Configuration directory ready: ~/.hermes/
→ Starting setup wizard...

It then launches the setup wizard automatically. Reload your shell afterward so the hermes command is on your PATH:

source ~/.bashrc

Step 2 — Run the setup wizard​

The wizard walks through setup type, terminal backend, and messaging. On a box that already ran OpenClaw, it offers to import the old config first — you can preview what would be migrated before anything changes.

The first choice is how to set up Hermes:

• Quick Setup (Nous Portal) — one OAuth login, no API keys. The Portal bundles a model and a tool gateway. Requires an active Nous Portal subscription.
• Full setup (bring your own keys) — you configure providers and paste your own keys.

For the rest of the wizard:

• Terminal backend: Local — commands run directly on this machine.
• Messaging: Skip for now (you can wire up Telegram/Discord later with hermes setup gateway).

The wizard applies sensible agent defaults (max iterations, a 50% context-compression threshold) and finishes with a tool-availability summary.

Step 3 — Connect a model​

Out of the box the default model routes through the Nous Portal / OpenRouter and needs a key. To use your own provider instead, run:

hermes setup model

Then select OpenAI ▸ OpenAI API, paste your API key when prompted (it's written to ~/.hermes/.env — never echoed), accept the default base URL https://api.openai.com/v1, and pick a model — we used gpt-5.5:

API key saved.
Base URL [https://api.openai.com/v1]:
Select default model:
 → (●) gpt-5.5

Confirm the model and key are healthy:

hermes doctor

◆ Configuration Files
  ✓ ~/.hermes/.env file exists
  ✓ API key or custom endpoint configured
...
◆ Memory Provider
  ✓ Built-in memory active (no external provider configured — this is fine)

The remaining ⚠ lines in doctor are optional tool integrations (web search, Discord, image gen) — not needed for this guide.

Step 4 — Chat and save a memory​

Start an interactive session:

hermes

Send it a fact and ask it to remember — watch for the 🧠 memory tool to fire:

● Please save to your long-term memory: my WEC project codename is
  Bluefin-7, running on the OpenClaw box.
  ┊ 🧠 memory    ?  0.0s

╭─ ⚕ Hermes ─────────────────────────────────────────────────────────╮
    Saved to long-term memory: your WEC project codename is Bluefin-7,
    running on the OpenClaw box.
╰─────────────────────────────────────────────────────────────────────╯

That write creates ~/.hermes/memories/MEMORY.md. Exit with /exit or Ctrl+D.

Step 5 — Prove memory survives a reboot​

This is the whole point. The Hermes gateway is installed as a systemd user service with linger enabled, so it comes back automatically after a reboot — no login required. Restart the service, then reboot the whole box to make the test airtight:

systemctl --user restart hermes-gateway   # restart just the gateway service
sudo reboot                               # then reboot the entire box

Reconnect once the box is up and confirm the service restarted on its own:

systemctl --user status hermes-gateway --no-pager

● hermes-gateway.service - Hermes Agent Gateway - Messaging Platform Integration
     Loaded: loaded (...; enabled; vendor preset: enabled)
     Active: active (running) since Thu 2026-06-25 21:21:54 UTC; 1min 36s ago

Now open a fresh session and ask — no prior context, brand-new session ID:

hermes

● What's my WEC project codename, and which box does it run on?

╭─ ⚕ Hermes ─────────────────────────────────────────────────────────╮
    Your WEC project codename is Bluefin-7, and it runs on the
    OpenClaw box.
╰─────────────────────────────────────────────────────────────────────╯

It recalled the fact from disk after a full reboot. Inspect where that durable state lives:

cat ~/.hermes/memories/MEMORY.md
file ~/.hermes/state.db && du -h ~/.hermes/state.db

User's WEC project codename is Bluefin-7, running on the OpenClaw box.

/home/ubuntu/.hermes/state.db: SQLite 3.x database, ...
176K	/home/ubuntu/.hermes/state.db

A plain-text MEMORY.md you can read and edit, backed by a SQLite state.db for sessions. That's the persistent memory — and it just outlived a reboot.

cat ~/.hermes/memories/MEMORY.md

sudo apt install -y sqlite3
sqlite3 ~/.hermes/state.db '.tables'

CREATE VIRTUAL TABLE messages_fts USING fts5(content);
CREATE VIRTUAL TABLE messages_fts_trigram USING fts5(content, tokenize='trigram');

sqlite3 -header -column ~/.hermes/state.db \
  "SELECT substr(id,1,15) AS id, model, message_count FROM sessions ORDER BY started_at;"

id               model    message_count
---------------  -------  -------------
20260625_211227  gpt-5.5  8
20260625_212333  gpt-5.5  2

Bonus — read the conversation the agent stored​

The messages table holds the actual text of every turn. Each row has a role — user (what you typed), assistant (Hermes's reply), or tool (a tool's result) — so you can replay the whole exchange:

sqlite3 -header -column ~/.hermes/state.db \
  "SELECT substr(session_id,10,6) AS sess, role, substr(content,1,55) AS content
   FROM messages ORDER BY timestamp;"

sess    role       content
------  ---------  -------------------------------------------------------
211227  user       hello, can you hear me?
211227  assistant  Yes — I can hear you. How can I help?
211227  user       Please save to your long-term memory: my WEC project...
211227  tool       {"success": true, "done": true, "target": "memory", ...
211227  assistant  Saved to long-term memory: your WEC project codename...
212333  user       What's my WEC project codename, and which box does...
212333  assistant  Your WEC project codename is Bluefin-7, and it runs...

The interesting part is how the memory got written. The assistant didn't edit a file directly — it emitted a memory tool call, and that tool is what wrote MEMORY.md. You can see the exact call recorded in the history:

sqlite3 ~/.hermes/state.db \
  "SELECT tool_calls FROM messages WHERE tool_calls LIKE '%memory%' LIMIT 1;"

{"function": {"name": "memory", "arguments":
  "{\"target\":\"memory\",\"operations\":[
     {\"action\":\"add\",
      \"content\":\"User's WEC project codename is Bluefin-7, running on the OpenClaw box.\"}]}"}}

So the full chain is: you type → the agent decides it's worth keeping → it calls the memory tool with action: add → that writes the fact into MEMORY.md, while the whole conversation stays in state.db, full-text searchable via FTS5. Two stores, one durable memory.

What can you do with it?​

A memory that survives reboots only matters because of what the agent does with it. With Hermes running, the same install ships these capabilities (you saw them in the hermes doctor tool list) — here's what they unlock day to day:

• Run real work on the box. The terminal and code_execution tools let it act, not just chat — e.g. "clone this repo, install deps, and run the tests," or "check why the disk is filling up." It does it on the WEC Instance and reports back.
• Drive it from your phone. A messaging gateway (Telegram, Discord, Slack, and more) means you can hand it a task from anywhere — no SSH. (Setup in Part 2.)
• Put it on a schedule. The cronjob tool runs recurring jobs: a morning briefing, a weekly disk-usage report, or watch a service and alert you when it fails — delivered to your messaging channel. (Part 3.)
• Browse and search the web. With the browser and web-search tools it can pull live information and act on real pages. (These need provider API keys — see hermes setup tools.)
• Grow reusable skills and delegate. It can build skills from what it learns and hand subtasks to subagents — the "agent that grows with you" part.
• Remember across all of it. Everything above is backed by the persistent memory you just set up, so context carries from one task — and one day — to the next.

The rest of this series turns each of these into a hands-on guide (see What's next).

Troubleshooting (real)​

• Quick Setup (Nous Portal) hangs at "Waiting for approval (polling)". The Portal login needs an active subscription/credit. If you don't have one, Ctrl+C and use Full setup with your own key instead (Step 3).

• doctor shows "No API key found in ~/.hermes/.env". The default model points at the Portal/OpenRouter. Run hermes setup model, pick your provider, and paste the key — doctor then reports "API key or custom endpoint configured."

• Deprecated .env warning on gateway start (e.g. MESSAGING_CWD). Harmless; follow the hint to move the setting into config.yaml when convenient.

• Repeating WARNING [Telegram] … in the gateway logs. If you followed the earlier OpenClaw parts and added a Telegram channel, Hermes's setup detected OpenClaw and imported those messaging settings into ~/.hermes/.env. Because we skipped finishing messaging here, the gateway has a token but no complete config, so it keeps retrying and logging this warning. (A fresh box with no OpenClaw Telegram setup won't see it.) Remove the stray entries and restart:

  sed -i '/^TELEGRAM_ALLOWED_USERS=/d; /^TELEGRAM_BOT_TOKEN=/d' ~/.hermes/.env
  systemctl --user restart hermes-gateway
  

  If that token was ever exposed, revoke it in Telegram's @BotFather and issue a new one.

What's next​

Now that Hermes is running with durable memory, the rest of the series turns each capability above into a hands-on guide:

• Part 2 — Drive Hermes from Telegram. Finish migrating the Telegram channel Hermes already imported from OpenClaw (hermes setup gateway, allowlists, verify the bot responds), so you can hand it tasks from your phone.
• Part 3 — Put it on a schedule. Use the cron tool for a morning briefing, a weekly report, and a service-health alert delivered to your channel.
• Part 4 — Custom skills & subagents. Teach it reusable skills and delegate work.

Links will appear here as each part ships.

In Article 2 we put Caddy in front of OpenClaw for HTTPS, and in Article 3 we added a Telegram channel. The gateway works — but Caddy is still listening on 0.0.0.0, reachable by anything that can route to the box. This is the chave de ouro for the series: we join the server and your laptop to a NetBird mesh, repoint openclaw.local at the mesh IP, and close the public ports. The same https://openclaw.local/chat URL keeps working — but only for your devices. Every command and error below is from the actual run.

How NetBird works (and what you'll build)​

NetBird has two parts, and the distinction is the whole point:

1. The control plane (NetBird's managed management + signal service) — this is the only thing with a public presence. Every device that wants to join authenticates to it (with your setup key or SSO login), and it brokers the exchange of each peer's WireGuard public key.
2. The data plane — once authenticated, peers talk directly to each other, end-to-end encrypted over WireGuard. Your actual traffic never flows through a public port you manage; the control plane just did the introductions.

So you're building a mesh where Peer A (your laptop) reaches Peer B (the OpenClaw box) by its private 100.x address — and openclaw.local points there, with Caddy bound to that interface only. The public/LAN side has nothing listening.

The key idea for later: the mesh isn't limited to two peers. Authenticate once, and every new service — Ollama, a VDI, WordPress — joins as another peer with its own 100.x address, reachable privately with no public ports to open. You set up the auth model once; you add services forever.

The public internet only ever reaches NetBird's control plane — and that just authenticates peers, it never carries your app traffic. Your services aren't "firewalled off" so much as invisible: OpenClaw has no public IP, so there's simply no route to it from the internet. The only way in is to be an authenticated peer on the mesh.

In this tutorial we wire up the first two peers — your laptop and the OpenClaw box. The other services make the point: once auth is set up, Ollama, a VDI, WordPress each just join the same mesh as another 100.x peer — no public ports, no per-service exposure.

Stand up a NetBird control plane​

Every NetBird mesh has two roles: peers — your machines, i.e. the OpenClaw box from Parts 1–3 and your laptop — and a control plane that authenticates those peers and issues their join keys. You already have the peer (your OpenClaw box); now you need a control plane for it to join. Two ways to get one:

• Option A — self-host it on WiLine (recommended). Deploy WEC's NetBird Marketplace template: a dedicated WEC Instance that runs your own NetBird control plane — dashboard, trusted certificate, zero shell. Now your entire private network lives on WiLine — the OpenClaw box and its control plane — with no third-party dependency.
• Option B — managed NetBird (no extra box). Don't want to run your own control plane? Use the free tier at app.netbird.io — sign in and you're done; the control plane is NetBird's cloud. Then skip to Enroll your machines.

The steps below set up Option A. WEC runs the install; you give it an email and a public IP, and a few minutes later you have your own NetBird dashboard on https://<your-ip>.apps.wiline.cloud with a valid certificate.

1. Get a public (Elastic) IP​

The dashboard needs a public address. Under Networks → Elastic IPs, allocate a new IP or pick a free one, and note its value (ours: 108.60.112.165). It must be in the VPC and zone you'll deploy into. Full steps: Configure Elastic IPs.

2. Deploy a VM with the template​

This new instance becomes your NetBird control plane — a separate box from your OpenClaw instance, which stays untouched. Open Deploy → Deploy a VM (full walkthrough: Deploy a Virtual Machine). The choices that matter here:

• Network — pick the network in the same VPC/zone as your Elastic IP (we used Local Subnet in Princeton-VPC), so the IP can attach afterward.
• Template → Marketplace → Ubuntu 24.04 LTS Netbird.
• Template Configuration — your Let's Encrypt email and the Elastic IP from step 1 as the external address.

Finish the wizard and deploy.

3. Attach the Elastic IP to the new instance​

The IP isn't bound at deploy time — you attach it once the VM is up. Go to Networks → Elastic IPs → your IP → ⋯ → Allocate, and select your new instance (netbird-tutorial). Only VMs in the same VPC appear in the list.

4. Wait for first boot, then verify it's up​

The instance shows Running in Compute → Instances within a minute — but the template keeps working for a few minutes after that, pulling and starting the NetBird containers and bringing up the dashboard. Don't expect the URL to answer immediately.

Check from your laptop over HTTPS (not ping — ICMP is firewalled off, so a failed ping doesn't mean it's down):

curl -skS -m 10 -o /dev/null -w "%{http_code}\n" https://<your-ip>.apps.wiline.cloud

• 000 / connection refused → still provisioning; wait a minute and retry.
• 301 then 200 → it's up (HTTP redirects to HTTPS).

To watch it directly, SSH in (ssh ubuntu@<your-ip>) and confirm the containers are running and the ports are bound:

cloud-init status
sudo docker ps
sudo ss -tlnp | grep -E ':(80|443)'

It's ready once netbird-dashboard, netbird-traefik, and netbird-server show Up and 80/443 are listening.

5. Open the dashboard and create your account​

Open https://<your-ip>.apps.wiline.cloud — click through the certificate warning if you get one (same self-signed-cert click-through as Article 2).

This is your own NetBird control plane, running on your WEC Instance. On the first visit it asks you to create the admin account — enter a name, email, and password, click Create, then sign in with those same credentials. (That setup screen appears only once; afterwards the dashboard shows a normal Sign in page.)

You land on the NetBird dashboard — your private control plane on your own domain:

Click Add Peer and NetBird hands you the enrollment command for your server — note the --management-url pointing at your own domain:

curl -fsSL https://pkgs.netbird.io/install.sh | sh
netbird up --management-url https://<your-ip>.apps.wiline.cloud

(That second command opens a browser SSO login. For a headless server, add --setup-key <KEY> from your dashboard's Setup Keys page instead — same as the managed flow, just with --management-url added.)

This is the dashboard where you create the setup keys that enroll machines — which is exactly what we do next.

Now enroll your machines​

You have a control plane (your own template dashboard, or managed NetBird). Now put the two machines on the mesh — the OpenClaw box from Parts 1–3 and your laptop — and then close the box's public ports. These steps are the same no matter which control plane you picked.

Prerequisites: OpenClaw running behind Caddy from Articles 1–3 (reachable at https://openclaw.local), a control plane from the step above, and shell access to the box plus admin on your laptop.

Step 1 — Install the NetBird agent on the OpenClaw box​

This is the box from Parts 1–3 (a WEC Instance) — we're enrolling it as a peer, which is separate from any control-plane server. NetBird ships a one-line installer:

curl -fsSL https://pkgs.netbird.io/install.sh | sh

Gotcha (real one): on Ubuntu the install triggers the needrestart dialog — a blue "Which services should be restarted?" box. Tab between buttons can get swallowed by some SSH/terminal setups; use arrow keys to move, Space to toggle, Enter to confirm (<Ok> is the default). The package is already in place by the time this box appears, so even if you Ctrl+C out of it, the agent is installed — re-running the installer just tells you so:

NetBird seems to be installed already, please remove it before proceeding

(If you re-run the installer after this tutorial, you'll instead see NetBird service is running, please stop it before proceeding — the agent's already up, so there's nothing to reinstall.)

Confirm the version:

netbird version
# 0.73.2

Step 2 — Create a setup key and join the OpenClaw box​

A setup key is the token that enrolls a device into your mesh — ideal for a headless server (no browser SSO needed).

1. Open https://app.netbird.io/setup-keys.
2. Create Setup Key → name openclaw-tutorial, toggle Reusable (so it works for the laptop too), defaults otherwise.
3. Copy the key.

Connect the VM (replace with your key):

sudo netbird up --setup-key <YOUR_SETUP_KEY>

Check the connection:

netbird status

That NetBird IP (100.87.239.229) is the address everything below points at. Peers count: 0/0 is expected — nothing else has joined yet.

Step 3 — Join your laptop​

Install the NetBird client on whatever you're using, then connect with the same reusable setup key. The connect command (netbird up --setup-key …) is identical on every OS — only the install differs.

brew install netbirdio/tap/netbird
sudo netbird service install
sudo netbird service start
netbird up --setup-key <YOUR_SETUP_KEY>

WARNING: ... dial unix /var/run/netbird.sock: connect: no such file or directory
Connected

netbird up --setup-key <YOUR_SETUP_KEY>

curl -fsSL https://pkgs.netbird.io/install.sh | sh
sudo netbird up --setup-key <YOUR_SETUP_KEY>

Verify the two nodes see each other, and that the tunnel carries traffic:

netbird status
ping -c 3 100.87.239.229   # Windows: ping -n 3 100.87.239.229

Peers count: 1/1 — that peer is the VM. In the dashboard, both machines now show up under Peers (because we enrolled them with a setup key rather than an SSO login, they appear under Servers rather than User Devices):

Step 4 — Repoint openclaw.local at the mesh IP​

From Article 2, your hosts file maps openclaw.local to the VM's LAN IP (10.80.4.212). Swap it for the mesh IP (100.87.239.229). The file path and edit command differ by OS:

grep openclaw /etc/hosts
# 10.80.4.212 openclaw.local
sudo sed -i '' 's/^10\.80\.4\.212 openclaw\.local/100.87.239.229 openclaw.local/' /etc/hosts
grep openclaw /etc/hosts
# 100.87.239.229 openclaw.local

grep openclaw /etc/hosts
sudo sed -i 's/^10\.80\.4\.212 openclaw\.local/100.87.239.229 openclaw.local/' /etc/hosts
grep openclaw /etc/hosts
# 100.87.239.229 openclaw.local

$h = "$env:WINDIR\System32\drivers\etc\hosts"
(Get-Content $h) -replace '^10\.80\.4\.212 openclaw\.local','100.87.239.229 openclaw.local' | Set-Content $h
Select-String openclaw $h

Test over the mesh — before touching any ports:

curl -kI https://openclaw.local/

HTTP/2 200
...
via: 1.1 Caddy

via: 1.1 Caddy over the mesh IP — the chat now flows through NetBird. Load https://openclaw.local/chat?session=main in the browser to confirm it behaves exactly as before. The TLS cert still matches because the hostname is unchanged; only the IP behind it moved.

Step 5 — Close the public ports​

Here's the state we're fixing. On the VM:

sudo ss -tlnp | grep -E ':(80|443)'

LISTEN 0 4096  0.0.0.0:443  ...  docker-proxy
LISTEN 0 4096  0.0.0.0:80   ...  docker-proxy

Caddy listens on 0.0.0.0 — every interface, including the LAN (and any NAT in front of it).

The reliable fix is to bind the published ports to the mesh IP instead of 0.0.0.0, so Caddy only ever listens on wt0. Edit the Caddy service in docker-compose.override.yml (the override from Article 2):

cd /home/ubuntu/openclaw
cp docker-compose.override.yml docker-compose.override.yml.bak

Change the ports block from:

    ports:
      - "80:80"
      - "443:443"

to bind to the mesh IP:

    ports:
      - "100.87.239.229:80:80"
      - "100.87.239.229:443:443"

Recreate just Caddy and re-check:

docker compose up -d caddy
sudo ss -tlnp | grep -E ':(80|443)'

The ports are gone from 0.0.0.0 — they live on the mesh interface only.

Step 6 — Prove the lockdown​

Both directions, from the actual run.

Still reachable over the mesh (laptop):

curl -kI https://openclaw.local/
# HTTP/2 200 ... via: 1.1 Caddy

No longer reachable on the LAN (VM, hitting its own LAN IP):

curl -kI --connect-timeout 5 --resolve openclaw.local:443:10.80.4.212 https://openclaw.local/

That's the result: same URL, reachable only through your mesh, refused everywhere else.

Cleanup​

Delete the reusable setup key now that both devices are enrolled — Setup Keys → delete in the dashboard. Your peers stay connected; you're just closing the door you used to add them. To remove a device later, delete it under Peers → User Devices and run netbird down on that machine.

Troubleshooting (real)​

• needrestart dialog won't take Tab. Use arrow keys / Space / Enter. The package is already installed by the time the box shows.
• gRPC netbird.sock warning on first up. The daemon's socket lags the client by a beat. If it ends in Connected, ignore it.
• ufw rules don't block the gateway. Docker-published ports bypass ufw — bind the port to a specific IP (as above) or use Docker's own DOCKER-USER chain.
• Caddy crash-loops after reboot. It started before wt0 had the mesh IP. restart: unless-stopped recovers it; or order Docker after netbird.service.
• High ping to a peer. You're relayed, not direct — functional, just slower. Check Interface type and NetBird's peer detail for the connection type.

What's next​

That closes the Self-hosting OpenClaw series:

1. Deploy OpenClaw on a WEC Instance via Docker Compose
2. Secure OpenClaw with a Caddy reverse proxy + HTTPS
3. Add a Telegram channel to OpenClaw
4. Make OpenClaw private with a NetBird mesh VPN ← you are here

You now have a self-hosted agent that's encrypted in transit, paired to your devices, reachable from your phone, and invisible to the public internet — all on one small WEC Instance.

Continue the journey​

Ready for an agent that remembers? Start the Self-hosting Hermes series — Self-host the Hermes Agent with persistent memory — deployed on this same WEC Instance, with context that survives restarts.

You've deployed OpenClaw and secured it behind HTTPS. Now make it usable — talk to your agent from your phone via Telegram. We create a bot, connect it, clear OpenClaw's pairing gate, and get a real reply. Every command and gotcha below is from an actual run.

What you'll build​

Your phone talks to a Telegram bot; the OpenClaw gateway polls Telegram for messages, runs them through your model, and replies — no inbound ports needed.

Prerequisites​

• Part 1 + Part 2 done — OpenClaw running in ~/openclaw
• A Telegram account and a logged-in Telegram client — the phone/desktop app, or web.telegram.org. (You can't create a bot from the public t.me web page; see Troubleshooting.)

Step 1 — Create a Telegram bot​

In the Telegram app, tap search and type BotFather, then open the official account — the one with the blue checkmark.

Tap Start — BotFather replies with the commands it understands (you'll see options like /newbot, /mybots, /token, and more). Send /newbot, then follow its two prompts:

1. Name — a display name, e.g. My OpenClaw Agent
2. Username — must be unique and end in bot, e.g. wiline_openclaw_bot

BotFather confirms with "Done! Congratulations on your new bot" and gives you the token — the line after Use this token to access the HTTP API:, like 1234567890:AA....

Step 2 — Connect the bot to OpenClaw​

On the VM, in ~/openclaw, register the channel with your token:

docker compose run --rm openclaw-cli channels add --channel telegram --token "<your-bot-token>"
# Added Telegram account "default".

Step 3 — Activate and verify​

Restart the gateway so it picks up the channel, then check status:

docker compose restart openclaw-gateway
docker compose run --rm openclaw-cli channels status
# - Telegram default: enabled, configured, running, mode:polling, token:config

mode:polling means the gateway is actively polling Telegram — no inbound port or webhook required.

Step 4 — Message the bot (pairing gate)​

Open your bot (t.me/<your-bot-username>), tap Start, and send a message.

OpenClaw treats unknown senders as untrusted — so instead of replying, the bot returns a pairing code and your Telegram user id. This is the same security pattern as device pairing in Part 2.

Step 5 — Approve the pairing​

On the VM, approve the code from the bot's message:

docker compose run --rm openclaw-cli pairing approve telegram <pairing-code>
# Approved telegram sender <id>.
# Command owner configured telegram:<id> (commands.ownerAllowFrom was empty).

Step 6 — Chat with your agent​

Back in Telegram, just talk to it — no extra setup needed; OpenClaw with your model answers conversationally out of the box. Try something like:

In one sentence, what's the point of putting a reverse proxy in front of my agent?

It replies with a real answer — the full chain is live: your phone → Telegram → gateway → OpenAI → reply. Your self-hosted agent is now in your pocket. (Giving it tools and skills comes in later guides; conversational chat works immediately.)

Troubleshooting (real errors)​

1. BotFather "Start" does nothing in a browser​

Opening t.me/BotFather in a plain web browser shows a Start button that does nothing — that page is just the public bot card and needs a logged-in Telegram client to hand off to. Use the desktop/phone app, or log in at web.telegram.org (link a desktop device by scanning the QR from your phone: Settings → Devices → Link Desktop Device), then message BotFather there.

2. Bot returns a pairing code instead of replying​

Not an error — it's the pairing gate. Unknown senders must be approved first (Step 5). After approval, the bot chats normally.

3. Proxy headers detected from untrusted address​

If you followed Part 2, the gateway logs this because Caddy sits in front of it. It's a warning, not a failure. To silence it and restore correct client detection, set gateway.trustedProxies to your proxy's network.

Security & sizing notes​

• Pairing is the gate — only approved Telegram users reach the agent; the first approved user becomes the command owner.
• Polling, not webhooks — no inbound port is opened, which keeps the Part 2 hardening intact.
• Sizing — on a 2-vCPU box the gateway logged event loop degraded under load. For a busy bot, give it more CPU/RAM.

What's next​

You've finished Part 3 of the Self-hosting OpenClaw series. Next:

• Part 4 — Make OpenClaw private with a NetBird mesh VPN (next) — put your agent on a private mesh and close the public ports.

Then start the Self-hosting Hermes series — Self-host the Hermes Agent with persistent memory — for an agent whose context survives restarts.

Companion files for the series live in the WiLine manifests repo (link coming with the repo).

Teardown​

Remove the Telegram channel (keeps the rest of OpenClaw running):

docker compose run --rm openclaw-cli channels remove --channel telegram
docker compose restart openclaw-gateway

And /revoke the bot token in BotFather if you're done with it.

In Article 1 we got OpenClaw running — but only over plain HTTP, with an allowInsecureAuth workaround. Here we put Caddy in front of it as a reverse proxy: real HTTPS, device-paired auth, and the gateway's raw ports closed so the proxy is the only way in. Every command and error below is from the actual deploy.

What you'll build​

Caddy terminates HTTPS and reverse-proxies to the OpenClaw gateway over Docker's internal network. The gateway stops publishing its own ports — the only entry point becomes Caddy on :443.

Prerequisites​

• Article 1 completed — OpenClaw running in ~/openclaw
• Shell access to the VM
• A hostname for the gateway. With a public domain, use it (and get real Let's Encrypt certs). On a private box, we use openclaw.local + a hosts entry.

Step 1 — Confirm the starting point​

cd ~/openclaw
docker compose ps

You should see openclaw-gateway Up (healthy), publishing 18789/18790/3978. That's our starting state: working, but HTTP-only.

Step 2 — Write the Caddyfile​

Caddy's config: serve HTTPS and proxy everything to the gateway. tls internal uses Caddy's own local CA — no public domain needed.

cat > Caddyfile <<'EOF'
# Caddy selects its certificate by SNI (the hostname in the TLS handshake).
# A bare IP sends no SNI, so we use a hostname. With a public domain, put your
# domain here and drop `tls internal` for automatic Let's Encrypt.
openclaw.local {
    tls internal
    reverse_proxy openclaw-gateway:18789
}
EOF

The proxy target is openclaw-gateway:18789 — Caddy reaches the gateway by its Compose service name over the shared Docker network.

Step 3 — Add Caddy to Compose​

docker compose auto-merges a docker-compose.override.yml, so we add a caddy service without touching OpenClaw's official compose file:

cat > docker-compose.override.yml <<'EOF'
services:
  caddy:
    image: caddy:2
    restart: unless-stopped
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./Caddyfile:/etc/caddy/Caddyfile:ro
      - caddy_data:/data
      - caddy_config:/config

volumes:
  caddy_data:
  caddy_config:
EOF

caddy_data persists the local CA + certs across restarts.

Step 4 — Start Caddy​

docker compose up -d
docker compose ps

Caddy comes up alongside the gateway with 443 published, and generates its internal CA + a certificate on first run.

Step 5 — Verify HTTPS​

Hit the gateway's health endpoint through Caddy. --resolve makes curl send the hostname (SNI) while pointing at the box:

curl -k --resolve openclaw.local:443:127.0.0.1 https://openclaw.local/healthz
# {"ok":true,"status":"live"}

Step 6 — Re-secure the gateway​

Now traffic arrives over https://openclaw.local. Two config changes:

1. Add the HTTPS origin to allowedOrigins (the Control UI rejects unknown origins).
2. Turn allowInsecureAuth back off — HTTPS is a secure context, so the Article 1 workaround is no longer needed.

docker compose run --rm --no-deps --entrypoint node openclaw-gateway \
  dist/index.js config set --batch-json '[{"path":"gateway.controlUi.allowedOrigins","value":["https://openclaw.local"]},{"path":"gateway.controlUi.allowInsecureAuth","value":false}]'

docker compose restart openclaw-gateway

Step 7 — Pair your browser​

Open https://openclaw.local/ in your browser (on a private box, first map 10.80.4.212 openclaw.local in your machine's hosts file — /etc/hosts on macOS/Linux, or C:\Windows\System32\drivers\etc\hosts edited as Administrator on Windows).

You'll hit a certificate warning first — "Your connection is not private" (NET::ERR_CERT_AUTHORITY_INVALID). This is expected with tls internal: the certificate is signed by Caddy's local CA, which your operating system doesn't trust. Click Advanced → Proceed to openclaw.local (unsafe) to continue. (With a real domain + Let's Encrypt, the certificate is publicly trusted and this warning never appears — see Going to production.)

Now the page loads — but with allowInsecureAuth off, the gateway requires device pairing before this browser can use the Control UI. That's the secure flow doing its job. The screen shows a request id; approve it on the host:

docker compose run --rm openclaw-cli devices approve <request-id-from-the-screen>

Back in the browser, click Connect again — it pairs and loads the dashboard.

Step 8 — Lock down direct access (the real hardening)​

The gateway still publishes 18789 to the host, so http://<vm-ip>:18789 is still reachable in plain HTTP, bypassing Caddy. Close it: stop publishing the gateway's ports so Caddy on :443 is the only door. Caddy still reaches it over the internal network.

cat > docker-compose.override.yml <<'EOF'
services:
  openclaw-gateway:
    # Unpublish the gateway's host ports — Caddy reaches it internally, so the
    # only entry point is HTTPS on :443.
    ports: !reset []

  caddy:
    image: caddy:2
    restart: unless-stopped
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./Caddyfile:/etc/caddy/Caddyfile:ro
      - caddy_data:/data
      - caddy_config:/config

volumes:
  caddy_data:
  caddy_config:
EOF
docker compose up -d

ports: !reset [] clears the ports the base compose published.

Step 9 — Prove it's locked​

curl -s -m 5 http://<vm-ip>:18789/healthz ; echo " <- direct HTTP (should FAIL)"
curl -sk --resolve openclaw.local:443:127.0.0.1 https://openclaw.local/healthz ; echo " <- via Caddy (should work)"

The first returns nothing (connection refused) — the insecure door is gone. The second still returns {"ok":true,"status":"live"}.

Your OpenClaw is now reachable only over HTTPS, device-paired.

Troubleshooting (real errors)​

1. tlsv1 alert internal error​

Hit when the Caddyfile site address was a bare IP (https://10.80.4.212):

curl: (35) error:0A000438:SSL routines::tlsv1 alert internal error

Caddy's logs showed the cert was obtained fine. Cause: TLS picks a certificate by SNI (the hostname in the handshake), but connections to a bare IP send no SNI — so Caddy can't match a cert and aborts. Fix: use a hostname site address (Step 2). A reader with a real domain never hits this — the domain is the SNI.

2. Device pairing required​

On the first HTTPS connect after turning off allowInsecureAuth:

Device pairing required — This browser needs one-time approval from the Gateway
host before it can use the Control UI.

Cause: this is the correct secure flow — with insecure auth off, each new browser must be approved. Fix: docker compose run --rm openclaw-cli devices approve <request-id>. (The CLI may log scope upgrade pending approval … using local fallback but still completes the approval.)

3. NET::ERR_CERT_AUTHORITY_INVALID​

Expected with tls internal — the cert is signed by Caddy's local CA, which your OS doesn't trust. Click through on a private box. With a public domain + Let's Encrypt (below), the cert is trusted and there's no warning.

Going to production​

With a real domain, swap two lines in the Caddyfile — point it at your domain and drop tls internal:

- openclaw.local {
-     tls internal
+ openclaw.example.com {
      reverse_proxy openclaw-gateway:18789
  }

Then point the domain's DNS A record at the VM's public IP and open 80 + 443 to the internet. Caddy automatically provisions and renews a Let's Encrypt certificate — trusted, no warning, no --resolve or /etc/hosts needed. Update allowedOrigins to https://openclaw.example.com.

Security notes​

• Single entry point — only Caddy's :443 is exposed; the gateway has no host ports (Step 8).
• Device pairing — every browser needs one-time approval (openclaw devices).
• Origin allowlist — the Control UI only accepts https://openclaw.local.
• Rotate secrets — regenerate OPENCLAW_GATEWAY_TOKEN if it has ever been shown (screenshots, screen-shares).

What's next​

You've finished Part 2 of the Self-hosting OpenClaw series. Next:

• Part 3 — Add a Telegram channel (next) — talk to your now-secured agent from your phone.
• Part 4 — Make OpenClaw private with a NetBird mesh VPN — put it on a private mesh and close the public ports.

Companion files (Caddyfile, docker-compose.override.yml) live in the WiLine manifests repo (link coming with the repo).

Teardown​

To remove just Caddy and reopen the direct ports, delete docker-compose.override.yml and Caddyfile, then docker compose up -d. To stop everything:

docker compose down

Deploy a self-hosted OpenClaw AI agent on a WEC Instance with Docker Compose — from spinning up the VM to an agent that actually answers, using your own model API key. Every command, version, and error below was captured from a real deployment on a WEC Instance.

What you'll build​

A single OpenClaw gateway container, configured with your model provider, reachable through its web Control UI and CLI.

Prerequisites​

• A WiLine Edge Cloud account
• A model API key — this guide uses OpenAI; Anthropic and local models work too
• An SSH key pair on your machine (~/.ssh/id_ed25519 or similar)
• About 20 minutes

Step 1 — Provision the VM on WiLine​

Spin up a WiLine VM that meets these requirements:

The portal walkthrough is already documented — follow these and come back:

• Deploy a Virtual Machine →
• Configure an SSH Key →

Once it's running, SSH in:

ssh ubuntu@<your-vm-ip>

Step 2 — Verify the box​

Before installing anything, confirm what you're working with — the OS version and the resources available. Note these numbers; they're useful when you later compare performance or open a support ticket.

lsb_release -a
nproc
free -h
df -h /

On our WEC Instance: Ubuntu 22.04.5 LTS, 8 vCPU, ~15 GiB RAM, 25 GB free disk.

Step 3 — Install Docker + Compose​

Check whether Docker is already present:

docker --version
docker compose version

If it's not installed, follow Docker's official guide for your distro — Install Docker Engine on Ubuntu. The quickest path is Docker's convenience script, followed by adding your user to the docker group so you can run it without sudo:

curl -fsSL https://get.docker.com | sh
sudo usermod -aG docker $USER
newgrp docker

You need Docker Compose v2 (the docker compose subcommand, not the legacy docker-compose binary).

Step 4 — Get the Compose file​

Create a project directory and pull OpenClaw's official docker-compose.yml:

mkdir openclaw && cd openclaw
curl -fsSL https://raw.githubusercontent.com/openclaw/openclaw/main/docker-compose.yml -o docker-compose.yml

The file defines two services — openclaw-gateway (the long-running agent gateway) and openclaw-cli (a one-shot CLI that shares the gateway's network). By default it builds from source; we'll point it at the prebuilt image instead.

Step 5 — Configure .env​

Create a .env next to the compose file. Pin the prebuilt image and set a dashboard token:

OPENCLAW_IMAGE=ghcr.io/openclaw/openclaw:latest
OPENCLAW_GATEWAY_TOKEN=<paste output of: openssl rand -hex 32>

Pull the image:

docker compose pull

Step 6 — Pre-create the config directory​

OpenClaw bind-mounts ~/.openclaw into the container. Create it as your own user first — otherwise Docker creates it as root and the container (which runs as user node, uid 1000) can't write to it:

mkdir -p ~/.openclaw ~/.openclaw-auth-profile-secrets

If you skip this, you'll hit a permission error on first run — see Troubleshooting.

Step 7 — Onboard​

This is where you bring your own model — onboarding prompts for your provider and API key. This guide uses OpenAI, but Anthropic and local models work the same way.

Run OpenClaw's onboarding through the gateway container. It's interactive — it asks for your provider and API key and writes the config:

docker compose run --rm --no-deps --entrypoint node openclaw-gateway \
  dist/index.js onboard --mode local --no-install-daemon

Walk through the prompts:

• Continue past the personal-use security notice → Yes
• Setup mode → QuickStart
• Provider → OpenAI (or your provider), then paste your API key
• Default model → keep the suggested one (openai/gpt-5.5)
• Channel → search skip → Skip for now (messaging channels are a later guide)
• Skills / Hooks → No / Skip for now (configure later with openclaw configure)
• Hatch your agent → Hatch later (we start the gateway as a service next)

It ends with Onboarding complete.

Step 8 — Apply gateway config and start​

Onboarding wrote your provider and model. Now set the gateway's runtime options — run mode, network bind, and the Control UI origins it will accept — then start it as a background service.

docker compose run --rm --no-deps --entrypoint node openclaw-gateway \
  dist/index.js config set --batch-json '[{"path":"gateway.mode","value":"local"},{"path":"gateway.bind","value":"lan"},{"path":"gateway.controlUi.allowedOrigins","value":["http://localhost:18789","http://127.0.0.1:18789"]}]'

docker compose up -d openclaw-gateway

Step 9 — Sanity check​

Container health:

docker compose ps

You want Up ... (healthy). Then hit the health endpoint:

curl http://127.0.0.1:18789/healthz
# {"ok":true,"status":"live"}

Confirm your provider key is usable:

docker compose run --rm openclaw-cli models status
# openai ... api_key=1 ... status=usable

Now the real end-to-end test. The agent command needs a target, so list agents first, then message the default one (main):

docker compose run --rm openclaw-cli agents list
# - main (default)

docker compose run --rm openclaw-cli agent --agent main \
  --message "Reply with exactly one word: working"
# working

If it replies working, the full chain — gateway → OpenAI → response — is live.

The Control UI is at http://<your-instance-ip>:18789/; paste your OPENCLAW_GATEWAY_TOKEN into Settings to log in.

Troubleshooting (real errors)​

These are errors we actually hit during this deploy — not hypotheticals.

1. EACCES: permission denied, mkdir '/home/node/.openclaw/state'​

Hit on the first onboarding run when ~/.openclaw didn't pre-exist:

[openclaw] The CLI command failed.
[openclaw] Reason: Failed to open the plugin state database.
| EACCES: permission denied, mkdir '/home/node/.openclaw/state' | EACCES

Cause: Docker auto-created the bind-mount source ~/.openclaw owned by root (0:0). The container runs as user node (uid 1000), so it can't write inside that root-owned directory.

Fix: give the directory to uid 1000 (which is also your ubuntu user):

sudo chown -R 1000:1000 ~/.openclaw

Pre-creating the directory yourself (Step 6) avoids this entirely.

2. No target session selected​

The first time we ran agent without specifying who to talk to:

Error: No target session selected. Use --agent <id>, --session-key <key>,
--session-id <id>, or --to <E.164>. Run openclaw agents list to see agents.

Cause: openclaw agent runs one turn against a specific agent/session; with no channel configured there's no implicit target.

Fix: list agents and pass the id explicitly:

docker compose run --rm openclaw-cli agents list          # shows: main (default)
docker compose run --rm openclaw-cli agent --agent main --message "..."

3. Control UI: "Secure browser context required"​

Opening the Control UI from another machine (e.g. macOS) at the VM's IP over plain HTTP, the page refuses to connect:

Secure browser context required
This page is running over plain HTTP, so the browser cannot create the
device identity the Gateway expects.

Cause: browsers only expose the crypto APIs OpenClaw needs in a secure context — HTTPS, or localhost/127.0.0.1. A remote http://<ip>:18789 is neither, so it's blocked in the browser, regardless of the server-side gateway.controlUi.allowInsecureAuth flag.

Fix: tunnel the port over SSH so the browser talks to 127.0.0.1 (a secure context). On your local machine:

ssh -L 18789:127.0.0.1:18789 ubuntu@<your-vm-ip>

Then open http://127.0.0.1:18789/#token=<your-token> locally. The proper long-term fix is HTTPS via a reverse proxy — the next guide.

Security notes​

On startup the gateway logged warnings worth acting on before any public exposure:

• Binding to a non-loopback address — the gateway listens on the LAN. Don't expose port 18789 to the public internet without auth in front of it.
• gateway.controlUi.allowInsecureAuth=true — flagged dangerous. Run docker compose run --rm openclaw-cli security audit.
• plugins.allow is empty — non-bundled plugins (e.g. codex) may auto-load. Set an explicit allowlist of trusted plugin ids.

Hardening this behind a reverse proxy with HTTPS is the subject of the next guide.

What you've accomplished​

You went from a bare WEC Instance to a working, self-hosted AI agent:

• Provisioned and verified an Ubuntu VM on WEC
• Stood up the OpenClaw gateway with Docker Compose and the official prebuilt image
• Wired in your own model provider (OpenAI) and confirmed it end-to-end — the agent replied over the CLI and the Control UI
• Hit (and fixed) the real permission, session, and secure-context issues along the way

The agent is yours: your key, your box, your data. From here it's about making it secure, reachable, and useful.

What can you do with it?​

OpenClaw isn't a chatbot — it's an autonomous agent that can act on your box. Now that it's running, here's what it unlocks (some features need extra configuration, and we cover the big ones later in this series):

• Run real work on the machine. It can execute shell commands and read/write files — "check what's using the disk," "tail the logs and summarize the errors" — with configurable sandboxing for how much you let it touch.
• Talk to it from your phone. OpenClaw connects to WhatsApp, Telegram, Discord, Slack, Signal, and iMessage, so you delegate tasks conversationally without SSH. (We wire up Telegram in the next guide.)
• Browse and act on the web. Built-in browser automation lets it navigate sites, fill forms, and extract data autonomously.
• Write and run code. It integrates with Claude Code for autonomous coding — writing and modifying code, running tests, and even opening PRs.
• Work in the background, proactively. It runs 24/7, can execute background tasks, and does "heartbeat" check-ins instead of only reacting when you message it.
• Grow with you. A community skill library (ClawHub), self-written tools, and multi-agent orchestration mean it gets more capable over time — backed by persistent memory that carries context across conversations.

Typical real uses people run: inbox and calendar management, document processing, infrastructure tasks on the box, content pipelines, and autonomous code testing.

What's next​

This is Part 1 of the Self-hosting OpenClaw series on running production-grade AI infrastructure on a WEC Instance. Coming up:

• Part 2 — Secure OpenClaw with a Caddy reverse proxy + HTTPS (next) — put HTTPS in front of the gateway so you can drop the allowInsecureAuth workaround and reach the Control UI from anywhere, safely.
• Part 3 — Add a Telegram channel — talk to your agent from your phone.
• Part 4 — Make OpenClaw private with a NetBird mesh VPN — put it on a private mesh and close the public ports.

Companion files for this guide — docker-compose.yml and .env.example — live in the WiLine manifests repo (link coming with the repo).

Teardown​

docker compose down              # stop + remove containers
docker compose down --rmi all -v # also remove the image and volumes

To remove config/state on the host: rm -rf ~/.openclaw ~/.openclaw-auth-profile-secrets. To stop billing entirely, delete the VM from the WiLine portal.