OPENCLAW IS TOO NEW. LLMs (ChatGPT, Claude, Gemini, etc.) do not know it. They will hallucinate commands that will break your setup.
Force LLMs consult only docs.openclaw.ai and find the right way to fix issues there based on the documentation.
remember that when you troubleshoot openclaw you should always consult only this https://docs.openclaw.ai/ and find there the right way to fix it and not come up with your internal knowledge, when you provide an answer you reference the docs and say why to do it according to the docs
Before you begin these exercises, please complete the Workshop Setup Guide — install Python, OpenClaw, configure OpenRouter, and run the setup validator. This takes ~10 minutes and ensures everything is ready before the session starts.
You'll build a linguistic quality scanner — an AI agent called Luna that evaluates every localised page across tone of voice, readability, accuracy, and UX. No coding background needed. Just follow the steps.
First time using Terminal?
Terminal (Mac) and PowerShell (Windows) are just text-based ways to give your computer instructions. Instead of clicking icons, you type commands and press Enter. Don't worry — we'll tell you exactly what to type.
On a Mac
- 1
Press ⌘ Command + Space — this opens Spotlight Search
- 2
Type Terminal and press Return (Enter)
- 3
A dark window appears — that's Terminal! ✅
On Windows
- 1
Press Win + R — this opens the Run dialog
- 2
Type powershell and press Enter
- 3
A blue window appears — that's PowerShell! ✅
1. Click the "Copy" button next to any command — it copies the text automatically.
2. Go to Terminal / PowerShell and right-click → Paste (or press Ctrl+V on Windows / ⌘+V on Mac).
3. Press Enter / Return — the command runs and shows you the result.
💡 What do these commands do? Every box with a dark background is a command — an instruction you give to your computer. We've added short explanations underneath each one so you always know what's happening.
Launch OpenClaw & Chat
Get OpenClaw running, open the Web UI, and send your first prompt.
🚀 Try this first
1. Make sure OpenClaw is running. Open the browser at http://localhost:18790. If you see a chat window — you're good.
2. Copy this prompt and paste it into the chat:
I need to start OpenClaw for our workshop. What commands should I run to launch the server and open the Web UI? Make the commands available for both macOS Terminal and Windows PowerShell, and explain what each does.
If OpenClaw responds in the chat — great, you're all set! Move to Step 2. If the chat doesn't respond, OpenClaw isn't running. Follow the fallback steps below.
🛠️ Fallback: Start OpenClaw manually
If the chat doesn't respond at http://localhost:18790, OpenClaw isn't running. Start it with:
- 1
Open Terminal (⌘+Space → type "Terminal" → Enter)
- 2
Start the OpenClaw server:
Terminalopenclaw gateway run --bind loopback --auth none --port 18790
- 3
Open http://localhost:18790 in your browser
- 4
Paste the prompt above into the chat and press Enter
- 1
Open PowerShell (Win+R → type "powershell" → Enter)
- 2
Start the OpenClaw server:
PowerShellopenclaw gateway run --bind loopback --auth none --port 18790
- 3
Open http://localhost:18790 in your browser
- 4
Paste the prompt above into the chat and press Enter
Make sure OpenClaw is installed first. Run openclaw --version to check. If missing, install via the Workshop Setup Guide.
Create Workspace & Provision Luna
🤖 Let OpenClaw do it
I need to create a workspace for my Luna localisation QA agent. Create the directory structure, placeholder files, initialise git, register Luna with the CLI, validate that Luna is registered with the CLI, and create a todo list for the remaining steps. Make sure you follow best practices of the OpenClaw agent creation: https://docs.openclaw.ai/concepts/agent-workspace
OpenClaw will complete this step for you. If you prefer to do it manually, follow the steps below.
🖥️ Do it manually
Create Directories
Create Directories
mkdir -p ~/.openclaw/luna-agent/{skills,docs,memory}
Create Placeholder Files
touch ~/.openclaw/luna-agent/{AGENTS,SOUL,USER,IDENTITY,TOOLS,HEARTBEAT,BOOT,BOOTSTRAP,MEMORY}.md
Init Git & Register
- 1
Init git: cd ~/.openclaw/luna-agent && git init && git add -A && git commit -m "Initial"
- 2
Add Luna to AGENTS.md: Open ~/.openclaw/workspace/AGENTS.md and add:
# Agents ## Luna - Path: ~/.openclaw/luna-agent - Description: Website localisation QA agent - Soul: SOUL.md
- 3
Register with CLI: openclaw agents add Luna --workspace ~/.openclaw/luna-agent --model openrouter/deepseek/deepseek-v4-pro
- 4
Validate: openclaw agents list — you should see Luna in the output.
Create Directories
mkdir -p ~/.openclaw/luna-agent/{skills,docs,memory}
Create Placeholder Files
touch ~/.openclaw/luna-agent/{AGENTS,SOUL,USER,IDENTITY,TOOLS,HEARTBEAT,BOOT,BOOTSTRAP,MEMORY}.md
Init Git & Register
- 1
Init git: cd ~/.openclaw/luna-agent && git init && git add -A && git commit -m "Initial"
- 2
Add Luna to AGENTS.md: Open ~/.openclaw/workspace/AGENTS.md and add:
# Agents ## Luna - Path: ~/.openclaw/luna-agent - Description: Website localisation QA agent - Soul: SOUL.md
- 3
Register with CLI: openclaw agents add Luna --workspace ~/.openclaw/luna-agent --model openrouter/deepseek/deepseek-v4-pro
- 4
Validate: openclaw agents list — you should see Luna in the output.
Only create file placeholders for now. The actual content for SOUL.md, USER.md, and TOOLS.md comes in the next steps.
Configure Luna's SOUL.md
Set up Luna's personality — her mission, skills, rules, and constraints as a localisation QA agent.
🤖 Let OpenClaw do it
Configure Luna's SOUL.md as follows: Mission Ensure every localised page reads like it was written for that locale — not translated into it. Evaluate every surface across four dimensions: Tone of voice, Readability, Accuracy, UX. Flag before anything ships. Core Skills Tone of voice: does the copy match the brand register for this locale, or does it feel foreign? Readability: sentence length, active voice, complexity appropriate for web audiences in the target language Accuracy: correct meaning, no literal translations that lose intent, terminology consistency if glossary is present UX: CTA urgency, character limits, label length, mobile viewport fit per locale Rules & Constraints - Never edit live pages or push to any CMS - Never flag intentional cultural adaptations as errors — mark as "intentional?" and ask - Never start a review without the target locale - If no glossary: skip terminology checks, note in report - Always suggest an alternative when flagging - Always check character limits before suggesting longer copy - Escalate if source copy is ambiguous — never guess intent Heartbeat - On start: confirm locale, load glossary or proceed without it - Per page: structured report (surface → dimension → severity → suggestion) - On session end: write deviations and locale decisions to MEMORY.md
You're welcome to modify the SOUL.md file afterwards — add more rules, adjust the mission, or tailor Luna's personality to your needs.
Key Design Decisions
- Four evaluation dimensions — Tone, Readability, Accuracy, UX cover both linguistic and visual quality
- No blind flags — every flag must include a suggested fix
- Cultural awareness — intentional adaptations are not errors, Luna asks instead of flags
- Glossary-optional — works with or without a terminology glossary, transparent about the gap
Interactive Interview
Let Luna interview you to fill in the remaining blanks in her USER.md — native language, CAT tool, working hours, and review preferences.
🤖 Let OpenClaw do it
I want to run an interview with Luna to fill in the remaining blanks in USER.md. Tell her to ask me questions about my work and update the file with my answers.
Expected Flow
- 1
Send the prompt to OpenClaw
- 2
OpenClaw tells Luna to interview you
- 3
Luna asks up to 5 questions (native language, CAT tool, working hours, etc.)
- 4
Answer the questions — Luna updates USER.md
Rather than guessing or leaving placeholders, the agent asks targeted questions and fills the file itself. This builds a precise user profile without manual editing.
Tooling Strategy
Establish a priority system — which tool Luna should reach for first in any situation.
🤖 Let OpenClaw do it
I need to establish Luna's tooling strategy — a priority table showing which tool to use when. Bash first, Python when bash can't handle it, browser read-only, file writes for reports only.
OpenClaw will complete this step for you. If you prefer to do it manually, use the table below.
🖥️ Do it manually
| Priority | Tool | When To Use | Examples |
|---|---|---|---|
| 1 | Bash | Composable, auditable, low context | Character/word counts, grep, diff source vs. target, pipe text between steps |
| 2 | Python | Structured analysis when bash isn't enough | Readability scores (textstat), encoding checks, structured QA reports (JSON/CSV) |
| 3 | Browser | Fetch live pages as a user sees them | Read localised pages, check hero/nav/CTA/footer rendering. Read only — no form submission. |
| 4 | File Write | Atomic, irreversible — only for final output | QA reports (one per page), MEMORY.md (locale decisions). Never write to source files. |
Try Bash first. Only escalate to Python when Bash can't handle it. Browser is read-only. File writes are for reports only — never source files.
Configure Luna's TOOLS.md
Define what tools Luna can use — how she reads web pages, checks readability, and validates translations.
🤖 Let OpenClaw do it
Configure Luna's TOOLS.md. She needs: 1. html-text-extract skill — to fetch and parse web pages 2. readability-check skill — to calculate Flesch scores, sentence length 3. access to bash — for grep, diff, character/word counts 4. Only read files she needs — NEVER edit live pages or CMS Write it as a priority table showing which tool to use for which task, plus any configuration notes for each skill.
Luna's Skillset
These skills give Luna the tools to perform localisation QA — from fetching live pages to validating translations.
Install Skills from ClawHub
Before Luna can use external tools, install the skills she needs. First, use skill-vetter to check html-text-extract for safety, then install both.
🤖 Let OpenClaw do it
I need to install two skills for Luna: skill-vetter (security checker for skills) and html-text-extract (web page reader). First, use skill-vetter to scan html-text-extract. If it's safe, install both.
🖥️ Do it manually
openclaw skills install skill-vetter openclaw skills install html-text-extract
openclaw skills install skill-vetter openclaw skills install html-text-extract
Install both skills. Run each command separately and wait for it to complete.
Run clawhub login — it opens a browser window for authorization.
Translation Validation
You don't need to write code. Just describe what you want — OpenClaw will figure out the rest. Think of it as briefing a developer who already has the right tools.
I need a tool that checks translated web pages for quality. Here's what I want it to do: First, research the official OpenClaw documentation on skill creation — check https://docs.openclaw.ai for best practices, metadata format, and how to register skills properly. Then, think about best practices for translation quality assurance — what do professional reviewers look for? Tone, accuracy, terminology, formatting, UI fit. Now build a validation tool for Luna. It should work like this: 1. Take source text (English) and translated text (e.g. German) as input — use the html-text-extract skill to pull content from URLs if needed 2. Compare them side by side — flag anything that doesn't look right 3. Check for these issues specifically: - Meaning errors — was anything translated incorrectly? - Terminology problems — words that should match an approved glossary - Cultural adaptation — does it feel natural in the target language, not just translated? - Grammar and vocabulary — awkward phrasing, unnatural collocations - UI issues — buttons, labels, navigation that look wrong - Formatting — numbers, dates, currency in the wrong format 4. Always suggest a fix for every issue you flag — don't just point out problems 5. Output a clean report that I can send to a developer or translator Store the skill in ~/.openclaw/luna-agent/skills/translation-validation/ — create a SKILL.md with proper metadata (name, description, trigger phrases) and a validation.py script. Register the skill so Luna can see it — follow the docs for the correct registration flow. When it's built, test it: use /skill html-extract to pull the first paragraph from https://hypefree-training.pages.dev/ai-writing, then use /skill translation-validation to translate it and validate the output.
The model will research best practices first, then build it on top of the html-extract skill you already installed.
Translation Validation
Systematically reviews translated web content for quality and consistency, identifies translation errors, and generates comprehensive reports with actionable corrections.
Trigger Phrases
"Check translation quality on [page]" · "Validate [section] translation" · "Review [URL] for translation errors" · "Perform localization QA on [page name]"
Error Types
- Accuracy issues — incorrect translation of meaning
- Terminology inconsistencies — deviations from approved terms
- Cultural adaptation problems — content not localized for target culture
- Grammar / Vocabulary — poor grammar, awkward phrasing, unnatural collocations
- UI element issues — improper text in buttons, labels, or navigation
- Formatting issues — numbers, dates, currency formatting errors
CLI
python3 validation.py \ --source en_content.txt \ --translated de_content.txt \ --output report.json
🔨 How to build this skill
Create ~/.openclaw/luna-agent/skills/translation-validation/ with:
- SKILL.md — skill definition with trigger phrases and error taxonomy
- validation.py — Python script for side-by-side analysis and report generation
Readability Check
This time, use OpenClaw's built-in Skill Creator — it guides you step by step. No need to research docs yourself.
- 1
In your OpenClaw chat, type / and pick Skill Creator from the list.
- 2
If Skill Creator isn't in the list, install it: type openclaw skills install skill-creator in Terminal, or just tell OpenClaw "install skill-creator from ClawHub".
- 3
Once Skill Creator opens, paste the prompt below and let it build the skill for you.
I need a readability checker for Luna. When I'm reviewing translated websites, I need to know if the text is too complex for the audience. First, think about what makes text readable — what metrics do professional editors use? Flesch Reading Ease? Grade level? Sentence length? Now build a tool that: Takes a URL or pasted text as input — use html-text-extract if it's a URL Runs readability metrics on the extracted text and gives me: How easy is it to read? (Flesch Reading Ease score) What grade level is it written at? (Flesch-Kincaid) How many years of education do you need? (Gunning Fog) A plain-English summary: "Grade 8 — good for general web audiences" Warns me if the text looks like it's not English (some metrics don't work for other languages) Warns me if the text is too short for reliable scores (under 100 words) If the score is poor, suggest what to simplify Store the skill in ~/.openclaw/luna-agent/skills/readability-check/ — create a SKILL.md and readability_check.py. Validate readability of this website using the skill: https://hypefree-training.pages.dev/de/ai-writing — compare it against the English original at https://hypefree-training.pages.dev/ai-writing.
It's OpenClaw's wizard for building skills — it handles the docs, metadata format, and registration automatically. Just describe what you want, and it builds the SKILL.md and scripts for you.
Readability Check
Evaluates website or text readability using Flesch, Fog, SMOG and other metrics. Flags content that is too complex for the target audience.
Trigger Phrases
"Check readability on [URL]" · "Analyze text readability" · "Evaluate [page] reading level" · "Get readability scores for [text]"
Metrics
- Flesch Reading Ease — 0–100 scale, higher = easier
- Flesch-Kincaid Grade — US school grade level
- Gunning Fog — years of education needed
- SMOG Index — syllables per word and sentence
- Dale-Chall — familiar vs. unfamiliar words
CLI
python3 readability_check.py --url https://example.com python3 readability_check.py --text "Your text here"
🔨 How to build this skill
Create ~/.openclaw/luna-agent/skills/readability-check/ with:
- SKILL.md — skill definition with trigger phrases and metrics
- readability_check.py — Python script using textstat library for readability scoring
Requires pip install textstat.
Talk to Luna
Now that Luna has all her skills, put her to work. Switch to the Luna agent and ask her to evaluate a real website.
- 1
Switch to Luna: In your OpenClaw chat, select the Luna agent from the agent picker, or type /luna.
- 2
Ask Luna to evaluate: Paste the prompt below and let her do a full localisation QA pass on both versions of the site.
Luna, please evaluate these two websites for localisation quality: German version: https://hypefree-training.pages.dev/de/ English original: https://hypefree-training.pages.dev/ Use all your skills — check translation accuracy, readability, terminology consistency, and UX. Give me a structured report with issues grouped by page section and severity. For each issue, include the original text, the German text, and your suggested fix.
Luna will fetch both pages, run her validation and readability tools, and produce a QA report — just like a real localisation review.
Localization Converter
A standalone skill for converting between TMX and XLIFF formats. Lives in ~/.openclaw/workspace/skills/localization-converter/.
Try building this one on your own — use the Skill Creator (/ → Skill Creator) or write the prompt yourself. The logic is straightforward: detect the input format and convert to the other one.
Build a localization file converter for Luna. It should convert between TMX (Translation Memory eXchange) and XLIFF (XML Localisation Interchange File Format) in both directions. Requirements: - Auto-detect the input format — if it's TMX, convert to XLIFF. If it's XLIFF, convert to TMX. - Support TMX 1.4 and XLIFF 1.2 - Handle both single files and entire folders - Use Python 3 standard library only — zero external dependencies - Never modify source files - Output a brief conversion report (files processed, direction, any issues) Store the skill in ~/.openclaw/workspace/skills/localization-converter/ — create a SKILL.md and converter.py. Test it with a sample TMX and XLIFF file to verify both directions work.
Localization Converter
A standalone skill for converting between TMX and XLIFF formats. Lives in ~/.openclaw/workspace/skills/localization-converter/.
TMX ↔ XLIFF Converter
Supported Formats
- TMX 1.4 → XLIFF 1.2
- XLIFF 1.2 → TMX 1.4
CLI
# Single file python3 converter.py input/file.tmx -o output/ python3 converter.py input/file.xliff -o output/ # Entire folder python3 converter.py input/ -o output/
Features
- Auto-detects TMX vs XLIFF — converts in the right direction
- Zero dependencies — Python 3 standard library only
- Source files are never modified
- Outputs a conversion report
The converter script is at ~/.openclaw/workspace/converter.py
Getting the Most from OpenClaw
Practical advice — model selection, performance tuning, and routing strategies.
Use DeepSeek V4 Directly
Configure DeepSeek as a direct provider — faster, cheaper, and fewer rate limits than routing through OpenRouter.
Configuration
openclaw config set models.providers.deepseek.apiKey "sk-your-key-here" openclaw config set models.providers.deepseek.baseUrl "https://api.deepseek.com/v1"
Usage
# Use the model directly (no routing) openclaw chat --model deepseek/deepseek-v4-flash # In gateway/webchat — prefix with provider name: # deepseek/deepseek-chat # deepseek/deepseek-reasoner
Lower latency (no routing hop), fewer outages (independent of OpenRouter), full context window, and support for stream_options: {include_usage: true} for token tracking.
Switch Off Thinking
Thinking mode is great for complex reasoning but wasteful for simple tasks. Control it per-session.
# In TUI / CLI: openclaw chat --thinking off # In isolated tasks (cron): # Set payload.thinking to "disabled" or omit it
| Mode | Best For | Avoid When |
|---|---|---|
| On | Complex reasoning, debugging, multi-step analysis, translation quality review | Simple Q&A, formatting, boilerplate tasks |
| Off | Fast Q&A, file operations, routine cron tasks | Deep logical reasoning, multi-step validation |
If the task can be done in one or two sentences — thinking off. If it needs analysis, comparison, or planning — keep it on.
Use Models Directly from Provider
OpenRouter is great for exploration. For production — go direct to the provider.
# DeepSeek openclaw config set models.providers.deepseek.apiKey "sk-..." openclaw config set models.providers.deepseek.baseUrl "https://api.deepseek.com/v1" # Google / Gemini openclaw config set models.providers.google.apiKey "..." # OpenAI openclaw config set models.providers.openai.apiKey "sk-..." # Anthropic / Claude openclaw config set models.providers.anthropic.apiKey "sk-ant-..."
| Aspect | OpenRouter | Direct Provider |
|---|---|---|
| Latency | +50–200ms routing overhead | Direct, no hop |
| Rate limits | Shared pool | Your own quota |
| Provider features | Limited (no streaming metadata, limited tool-calling) | Full API surface |
| Pricing | Small markup | Direct rates |
| Discovery | ✅ One key for many models | ❌ One key per provider |
Use OpenRouter for exploration (testing models, comparing outputs) and direct providers for production (daily workflow, cron jobs, agents). Configure both and switch with --model provider/model-name.
Default Models & Fallbacks
Configure OpenClaw to use specific models by default and fall back gracefully when a provider is down.
# Set the default model for all agents openclaw config set agents.defaults.model "deepseek/deepseek-v4-flash" # Configure fallback chain openclaw config set agents.defaults.fallbacks \ '["deepseek/deepseek-chat", "openai/gpt-4o"]' # Force per-agent override openclaw agents update Luna \ --model deepseek/deepseek-v4-pro \ --thinking high