Build, Shape, and Extend an OpenClaw Agent on AMD#


What You’ll Learn Today#

You’re running on an AMD MI300X, one of the most powerful AI accelerators available. By the end of this workshop, you’ll have run a 122-billion-parameter model locally and built a fully autonomous agent on the MI300X GPU.

No API tokens. No rate limits. Everything runs on AMD hardware, accessible to you.

The Steps#

1. Setup
Host a state-of-the-art open-weight LLM locally using vLLM.

2. Meet your agent
Start OpenClaw and go through onboarding. Watch how the agent learns who you are and understand the file-based memory system that makes it persistent across sessions.

3. Give it a task
Ask the agent to clone a Python project and set it up.

4. Fix a bug
Watch the think β†’ act β†’ observe β†’ repeat loop in real time as the agent investigates, traces the bug, fixes it, and verifies.

5. Package as a skill
Turn what the agent just did into a reusable skill that works on any Python project.

6. Use the skill
Prove the skill works by running it on the same project without further guidance.

7. Autonomous workflows
Tell the agent to schedule itself and deliver a personalized brief every morning. Watch it transition from reporting to actively fixing code.

8. The challenge
Apply everything you’ve built to an open-ended problem. Pick a challenge and see how far you can push the agent.

What You’ll Walk Away With#

  • A running local LLM stack: vLLM + AMD, fully configured

  • A personalized agent: Knows your name, preferences, and working style

  • A reusable skill: To debug any Python repo

  • An autonomous workflow: Runs every morning without you asking

  • A challenge result: An agent to demo and build on


Section 1: Setup#

Follow the steps to start the model server and verify connectivity.

πŸ–₯️ Start the vLLM server#

Time to start your vLLM server and create an end-point for your LLM. The cells below start it in the background and wait until it is ready: the first defines helpers that start a server, wait until it answers (or stop with its log if it fails), and stop it again; the second starts vLLM to serve Qwen3.5-122B on AMD hardware.

Note: The API key abc-123 is used throughout this notebook. You can replace it with any string, just keep it consistent across all cells.

Hide code cell source

import os
import signal
import subprocess
import time
import urllib.request


def server_is_up(url, headers=None):
    try:
        with urllib.request.urlopen(urllib.request.Request(url, headers=headers or {}),
                                    timeout=5):
            return True
    except Exception:
        return False


def ensure_server(command, url, log_path, timeout=1200, headers=None):
    """Start `command` in the background (its output goes to log_path) unless
    url already answers, then wait until it does. Returns the server process,
    or None if a server was already running. Raises, with the end of the log,
    if the server exits or is not ready within timeout seconds."""
    if server_is_up(url, headers):
        print(f"Already running: {url}")
        return None
    log = open(log_path, "w")
    server = subprocess.Popen(command, shell=True, stdout=log, stderr=subprocess.STDOUT,
                              start_new_session=True)
    deadline = time.time() + timeout
    while time.time() < deadline and server.poll() is None:
        if server_is_up(url, headers):
            print(f"Ready after {timeout - int(deadline - time.time())}s: {url}")
            return server
        time.sleep(5)
    tail = "".join(open(log_path).readlines()[-40:])
    state = f"exited with code {server.returncode}" if server.poll() is not None else "timed out"
    raise RuntimeError(f"Server {state} before {url} answered. Last log lines:\n{tail}")


def stop_server(server):
    """Stop a server started by ensure_server, and everything it started."""
    if server is not None and server.poll() is None:
        os.killpg(server.pid, signal.SIGTERM)
        try:
            server.wait(timeout=60)
        except subprocess.TimeoutExpired:
            os.killpg(server.pid, signal.SIGKILL)

Now start the vLLM server in the background and wait until it is ready (the model takes a few minutes to load):

vllm_server = ensure_server(
    "vllm serve Qwen/Qwen3.5-122B-A10B-FP8"
    " --served_model_name qwen3-5-122b --host 0.0.0.0 --port 8000 --api-key abc-123"
    " --enable-auto-tool-choice --tool-call-parser qwen3_coder --trust-remote-code"
    " --gpu-memory-utilization 0.92 --max-num-seqs 512",
    "http://localhost:8000/v1/models", "vllm_server.log", timeout=3600,
    headers={"Authorization": "Bearer abc-123"},
)

Section 2: Meet Your Agent#

The Overview#

Before we start OpenClaw, here’s an overview of what we will touch:

Concept

What it is

Where it lives

Gateway

Connects OpenClaw to the model running on AMD hardware

Process on port 18789

Workspace

The agent’s β€œbrain”: files it reads on every message

~/.openclaw/workspace/

Tools

How the agent acts: read files, run shell commands, write edits

Built into OpenClaw + workspace/skills/

Skills

Saved, reusable workflows the agent can follow on demand

workspace/skills/

πŸ–₯️ Install and onboard OpenClaw#

The next cell installs OpenClaw 2026.10.4, the release this tutorial was tested with, using its official installer, unless that version is already installed:

%%bash
set -e
# This tutorial was tested with OpenClaw 2026.10.4; other releases may behave differently.
OPENCLAW_VERSION=2026.10.4
if ! openclaw --version 2>/dev/null | grep -qF "$OPENCLAW_VERSION"; then
    curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh \
        | bash -s -- --no-onboard --no-prompt --version "$OPENCLAW_VERSION"
fi
openclaw --version

Onboarding connects OpenClaw to the vLLM server and creates the agent’s workspace. In a terminal, you would run openclaw onboard, and it would walk you through setup. Choose these settings:

  1. Security Continue? β†’ Yes

  2. Setup mode β†’ QuickStart

  3. Model/auth provider β†’ vLLM

  4. vLLM base URL β†’ Leave as http://127.0.0.1:8000/v1

  5. vLLM API key β†’ abc-123

  6. vLLM model β†’ qwen3-5-122b

  7. Default model β†’ Keep current (vllm/qwen3-5-122b)

  8. Select channel β†’ Skip for now

  9. Search provider β†’ Skip for now

  10. Configure skills now? β†’ No

  11. Enable hooks? β†’ Skip for now

  12. How do you want to hatch your bot? β†’ Hatch in Terminal (recommended)

If you onboard in a terminal, the OpenClaw interface appears when you finish, and once it says gateway connected, it’s ready.

The next cell makes the same choices without prompts (skipping channels, search, skills, and hooks), unless OpenClaw is already onboarded:

%%bash
set -e
if [ ! -f ~/.openclaw/openclaw.json ]; then
    openclaw onboard --non-interactive --accept-risk --flow quickstart \
        --auth-choice vllm --custom-base-url http://127.0.0.1:8000/v1 \
        --custom-api-key abc-123 --custom-model-id qwen3-5-122b \
        --skip-channels --skip-search --skip-skills --skip-hooks --skip-health --skip-ui
fi
ls ~/.openclaw/workspace

🦞 Ask your OpenClaw agent#

Whenever you see the 🦞 emoji, send your agent a message. Either chat with it in a terminal with openclaw tui --local (OpenClaw’s terminal UI), or run the cell that follows the step, which sends the same message from this notebook with openclaw agent and prints the reply. Do one or the other for each step: every message makes the agent act again. The cells all continue one conversation; this one defines the helper they use:

import json
import pathlib
import subprocess
import sys


def ask_agent(message, timeout=900):
    """Send one message to the OpenClaw agent and print its reply. Every call
    continues the same conversation (session "workshop")."""
    result = subprocess.run(
        ["openclaw", "agent", "--local", "--agent", "main", "--session-id", "workshop",
         "--timeout", str(timeout), "--json", "--message", message],
        capture_output=True, text=True, timeout=timeout + 120,
    )
    if result.returncode != 0:
        raise RuntimeError(f"openclaw agent failed:\n{result.stderr[-3000:]}")
    reply = "\n".join(p.get("text", "") for p in json.loads(result.stdout)["payloads"])
    print(reply)
    return reply

Send your first message to your OpenClaw agent and get set up! Answer any setup questions your agent asks you, then come back here to learn what happened behind the scenes. For example:

ask_agent("Hi! I'm a developer at the AMD OpenClaw workshop. Call me Dev. I like short, direct answers. Please pick a name and a personality for yourself and save it.")

πŸ‘€ Behind the scenes: what just happened?#

Those answers didn’t just disappear. The agent’s memory, personality, and skills are written in markdown files. You can read them, edit them, and version-control them. The agent wrote them to files in its workspace, a folder it reads on every message to remember who you are and how to behave.

The workspace has 7 files that get injected into every session:

~/.openclaw/workspace/
β”œβ”€β”€ SOUL.md       ← WHO the agent is: values, personality, tone
β”œβ”€β”€ AGENTS.md     ← HOW it operates: startup rules, memory, red lines
β”œβ”€β”€ IDENTITY.md   ← WHO the agent is: name, creature, emoji, vibe
β”œβ”€β”€ USER.md       ← WHO you are: context the agent reads about you
β”œβ”€β”€ TOOLS.md      ← local environment notes (SSH hosts, device names, etc.)
β”œβ”€β”€ HEARTBEAT.md  ← periodic background checks (empty by default)
β”œβ”€β”€ BOOTSTRAP.md  ← first-run ritual (deleted after onboarding)
└── memory/       ← daily session logs (today + yesterday auto-loaded)

SOUL.md is personality. AGENTS.md is policy. Every message the agent receives, it re-reads both. Run the next cell to see all three key files at once.

workspace = pathlib.Path.home() / ".openclaw" / "workspace"

for filename in ["IDENTITY.md", "SOUL.md"]:
    print("=" * 60)
    print(filename)
    print("=" * 60)
    print((workspace / filename).read_text())
    print()

print("=" * 60)
print("AGENTS.md  (truncated)")
print("=" * 60)
agents_text = (workspace / "AGENTS.md").read_text()
print(agents_text[:1200] + "\n\n... (truncated)")

Try it: manually layer a rule into AGENTS.md#

SOUL.md is personality, don’t touch that. AGENTS.md is policy. You can manually add rules to the agent here as well. For example, about how to behave when debugging.

The next cell appends a debugging policy to AGENTS.md. After this, every debug explanation from the agent will follow these rules. Run it to see the before and after.

debug_rule = """
---

## Debugging Policy (added during workshop)

When investigating and explaining bugs:
- State the bug in two sentences max: file, line, what it does wrong
- No filler phrases, just the root cause and the fix
- Use bullet points, never paragraphs
- After fixing, report exactly: file changed, line changed, before, after

"""

agents_path = workspace / "AGENTS.md"
original = agents_path.read_text()

print("── AGENTS.md BEFORE (last 200 chars) ──────────────────────")
print("..." + original[-200:])

agents_path.write_text(original + debug_rule)

print("\n── APPENDED ────────────────────────────────────────────────")
print(debug_rule)

This is the pattern for real use: you don’t replace the soul for every task, you layer specialized instructions on top of a stable base.

Note: You will see this debugging policy in action in Section 3.


Section 3: Pull the App#

Now let’s give the agent something to work with. Ask the agent to clone the typing app and set it up.

🦞 Ask your OpenClaw agent#

Ask your OpenClaw agent to clone the Mahdi-CV/open_type_faster repo and explain it to you. Here is an example:

"Clone https://github.com/Mahdi-CV/open_type_faster, install its dependencies, and tell me how to run it"

Watch as your agent uses shell tools to clone, inspect requirements, and install libraries. This is the act phase: the agent doesn’t just answer, it does.

ask_agent("Clone https://github.com/Mahdi-CV/open_type_faster, install its dependencies, and tell me how to run it")

app_dir = workspace / "open_type_faster"
assert (app_dir / "stats.py").is_file(), f"the agent did not clone the app into {app_dir}"

Section 4: Fix a bug#

Step 1 - Spot the bug yourself#

πŸ–₯️ Open a new terminal and run the app#

Open a terminal in JupyterLab (File β†’ New β†’ Terminal, or the Terminal tile in the Launcher). In it, follow the instructions OpenClaw provides on how to run open_type_faster.

Type for 30 seconds. When the results screen appears, look at the accuracy.

Something is off. Do you see it?

Step 2 - Ask OpenClaw to test#

🦞 Ask your OpenClaw agent#

Ask your OpenClaw agent to fix the bug. Here is an example:

"There seems to be an accuracy bug in this open_type_faster app, can you help identify and fix?"

Watch the loop:

  1. Run pytest: see which tests fail and what they expect

  2. Read the failing test: understand the correct behavior

  3. Read stats.py: trace the calculation back to the bug

  4. Fix the minimal change needed

  5. Re-run to verify

This think β†’ act β†’ observe β†’ repeat loop is what separates an agent from a chatbot.

Or run the cell below instead of chatting: it sends the same request, then runs the app’s tests to confirm the fix:

ask_agent("There seems to be an accuracy bug in this open_type_faster app, can you help identify and fix?")

# Run the app's tests with this kernel's Python (pytest and the app's requirements)
deps = ["pytest"] + (["-r", "requirements.txt"] if (app_dir / "requirements.txt").exists() else [])
subprocess.run([sys.executable, "-m", "pip", "install", "-q", *deps], cwd=app_dir, check=True)
tests = subprocess.run([sys.executable, "-m", "pytest", "-q"], cwd=app_dir,
                       capture_output=True, text=True)
print(tests.stdout[-1500:])
assert tests.returncode == 0, "the app's tests still fail after the fix"

Section 5: Package as a Skill#

What the agent just did was a one-off. A skill packages that behavior so it can be invoked on any Python project. Skills live in ~/.openclaw/workspace/skills/ as a folder containing a SKILL.md file with YAML frontmatter and step-by-step instructions. OpenClaw injects them into the system prompt automatically.

🦞 Ask your OpenClaw agent#

Ask your OpenClaw agent to create a python debugger skill. Try sending this to your OpenClaw agent:

"Create a skill called pytest-debugger in the skills directory. Start its SKILL.md with YAML frontmatter that has a name and a description. The SKILL.md must define these steps: 1) Read the tests/ folder to understand what is being tested. 2) Run pytest with verbose output and short tracebacks. 3) For each failing test, read the source file it references. 4) Identify the minimal fix (do not rewrite functions). 5) Apply the fix and re-run pytest to confirm. 6) Report: file changed, line changed, what was wrong, what the fix was."

The prompt asks for the YAML frontmatter explicitly: OpenClaw only loads a skill whose SKILL.md starts with a name and a description, and the agent doesn’t always add them on its own.

The agent should show you where the skills file is saved. You can always ask it again to show you.

Or run the cell below instead of chatting: it sends the same request, then asks OpenClaw where the new skill is and shows it:

ask_agent("Create a skill called pytest-debugger in the skills directory. Start its SKILL.md with YAML frontmatter that has a name and a description. The SKILL.md must define these steps: 1) Read the tests/ folder to understand what is being tested. 2) Run pytest with verbose output and short tracebacks. 3) For each failing test, read the source file it references. 4) Identify the minimal fix (do not rewrite functions). 5) Apply the fix and re-run pytest to confirm. 6) Report: file changed, line changed, what was wrong, what the fix was.")

# Ask OpenClaw where the skill is: skills the agent writes in conversation can land in
# workspace/skills/ or in the agent's own skill folder.
info = subprocess.run(["openclaw", "skills", "info", "pytest-debugger", "--json"],
                      capture_output=True, text=True)
assert info.returncode == 0, "OpenClaw has no skill called pytest-debugger"
skill = json.loads(info.stdout)
assert skill["eligible"], "the pytest-debugger skill is not ready to use"
print(f"Skill file: {skill['filePath']}\n")
print(pathlib.Path(skill["filePath"]).read_text())

That file is all it takes. The skill lives in the workspace, alongside IDENTITY.md and SOUL.md, and OpenClaw injects it into every session automatically. Any time you ask the agent to debug a Python project, it has these steps to follow.

Skills are just markdown files. You can read them, edit them, and version-control them.


Section 6: Using the Skill#

The skill is now in the workspace and OpenClaw injects it into the agent’s system prompt automatically, no special command needed.

The real value of a skill is applying it to a completely different codebase, one the agent has never seen, without writing a single new instruction. There’s a broken Python project at https://github.com/Mahdi-CV/buggy-py-mg.git (or git@github.com:Mahdi-CV/buggy-py-mg.git if you have a GitHub SSH key set up), hand it to the agent and watch the skill do the work.

🦞 Ask your OpenClaw agent#

"/skill pytest-debugger https://github.com/Mahdi-CV/buggy-py-mg.git"

The agent will apply the exact same steps it used on `open_type_faster’, no re-explaining, no extra guidance.

Or run the cell below instead of chatting: it sends the same request over HTTPS, which needs no SSH key, then runs that project’s tests:

ask_agent("/skill pytest-debugger https://github.com/Mahdi-CV/buggy-py-mg.git")

# Find the agent's clone (usually in its workspace)
# (a few levels deep only: the home directory also holds the model cache)
buggy = next((d for base in (workspace, pathlib.Path.cwd(), pathlib.Path.home(), pathlib.Path("/tmp"))
              for pattern in ("buggy-py-mg", "*/buggy-py-mg", "*/*/buggy-py-mg")
              for d in base.glob(pattern) if (d / ".git").exists()), None)
assert buggy, "the agent did not clone buggy-py-mg"
deps = ["pytest"] + (["-r", "requirements.txt"] if (buggy / "requirements.txt").exists() else [])
subprocess.run([sys.executable, "-m", "pip", "install", "-q", *deps], cwd=buggy, check=True)
tests = subprocess.run([sys.executable, "-m", "pytest", "-q"], cwd=buggy,
                       capture_output=True, text=True)
print(tests.stdout[-1500:])
assert tests.returncode == 0, "buggy-py-mg's tests still fail after the skill ran"

Section 7: Adding Another Agent for Autonomous Workflows#

You’ve built an agent that fixes bugs on demand. Now make it work for you: automatically, every morning, without lifting a finger.

As an AI/ML developer, you need to track fast-moving repos (like SGLang, vLLM, Transformers, ROCm, OpenClaw) and keep up with daily AI hardware news. Instead of writing scripts or configuring schedulers or spending hours manually, tell the agent what your ideal morning looks like and let it figure out the rest.

What it can do autonomously:

  • Schedule itself to run every morning at 8 AM

  • Save your filtering preferences to long-term memory (MEMORY.md)

  • Check GitHub repos for relevant PRs and changes

  • Search the web for AI hardware news

  • Write the brief to your workspace

πŸ–₯️ Open a new terminal and run the app#

openclaw agents add morning-brief

OpenClaw will walk you through setup. Choose these settings:

  1. Workspace directory β†’ /root/.openclaw/workspace/morning-brief

  2. Copy auth profiles from β€œmain”? β†’ Yes

  3. Configure model/auth for this agent now? β†’ No

  4. Configure chat channels now? β†’ No

Step 1 - Switch to your new agent#

🦞 Ask your OpenClaw agent#

"/agent morning-brief"

Step 2 - Delegate#

The prompt below is purely conversational, no mention of cron, no memory commands. The agent can infer what infrastructure it needs from the prompt:

🦞 Ask your OpenClaw agent#

"I need to wake up to a personalized tech brief every morning at 8 AM. Check sgl-project/sglang, vllm-project/vllm, huggingface/transformers, ROCm/ROCm, and openclaw/openclaw. I only care about performance updates, GPU features, and breaking changes, skip CI/infrastructure noise and docs-only PRs. Also search the web and add a summary of the latest AI hardware news."

Section 8: The Challenge#

🦞 Escape the Green Data Center#

An AMD lobster is trapped inside an overheating β€œgreen” data center. Electrified barbed wires block the exit; cut the wrong one and you fry the system.

The security camera shows four wires blocking the exit: W1, Q7, M3, and Z9. To escape, the lobster must cut the wire immediately to the right of the thermally coolest wire.

The lobster has scavenged a few artifacts from the data center’s mainframe. Everything it found is in /workspace/.challenge/escape-claw-image/.

The model you’re running (qwen3-5-122b) is multimodal, so your agent can work with images as well as text.

Wake up your OpenClaw agent, dig through what the lobster recovered, and figure out which wire is safe to cut.

Security Camera Feed

Your Mission#

Tell the lobster which wire to cut, and be ready to explain how you got there.

When you’re done, stop the vLLM server:

stop_server(vllm_server)