OpenClaw's Documentation Was Full of Broken Links — and the Tool That Should Have Caught Them Was Broken Too

The Links That Led Nowhere

If you tried to follow an internal link in OpenClaw's English documentation over the past few weeks, there was a decent chance you landed on a broken anchor. The Feishu channel guide had seven image references pointing to relative paths that no longer resolved. The Qwen provider page linked to /providers/modelstudio — a URL that doesn't exist. The correct path is /providers/qwen_modelstudio.

Across the install guides, security reference, FAQ, plugin SDK docs, and dashboard guide, anchor targets were simply missing. Sections that other pages linked to had no corresponding <a id="..."> tag. The links rendered fine — blue, underlined, clickable — but clicking them scrolled to the top of the page instead of the intended section.

The affected pages span the full breadth of the docs: the Groups channel guide, the gateway security index, the installer and Podman setup pages, both plugin SDK references, and the web dashboard guide. Not a single corner of the documentation was untouched.

Why Nobody Caught It Sooner

OpenClaw has a link audit script — docs-link-audit.mjs — that is supposed to crawl the documentation tree and flag broken internal references. It should have caught every one of these failures. It didn't, because it had its own problems.

The script was running against the full docs directory, which includes machine-generated localized translations. These translated pages introduced anchors, paths, and cross-references that don't exist in the English source. The validator couldn't distinguish between a broken English link and a valid localized one. False positives drowned out real failures. Eventually, the noise made the tool useless.

Making it worse: a circular import in the Tlon channel's configuration schema was crashing the test suite. The config schema imported from plugin-sdk/core, which triggered a bundled metadata scan, which loaded the Tlon config schema again. An infinite loop. The Vitest worker would hang indefinitely, and since the link audit tests lived in the same suite, they never ran.

The documentation could accumulate broken links for weeks and the CI pipeline would never notice.

What Changed

The audit script now creates a temporary docs directory, strips out all localized subdirectories, and sanitizes the configuration file to English-only content before running validation. Localized pages can no longer mask or distort English-source checks.

The circular import was resolved by narrowing the Tlon config schema's import path. Instead of pulling from the broad plugin-sdk/core barrel export, it now imports buildChannelConfigSchema directly from plugin-sdk/channel-config-schema. The dependency chain stops there. The test suite runs again.

With the tooling restored, the actual docs fixes are straightforward: missing anchor IDs added to 10 pages, image paths corrected in the Feishu guide from relative to absolute references, and the Qwen Model Studio cross-reference updated to the correct URL. New unit tests cover the sanitization logic, temporary directory handling, and cleanup.

Pages That Were Fixed

The Bigger Problem

Broken docs links are mundane. Every project has them. What makes this interesting is the failure mode: OpenClaw had a tool specifically designed to prevent this, and that tool was silently failing. The localization layer — a feature — was actively undermining the quality check. And a circular import in an unrelated channel extension was taking down the entire test suite that hosted the link audit tests.

This is the kind of compound failure that open-source projects accumulate quietly. No single change broke the docs. No single change broke the audit tool. The localization feature was added months ago. The Tlon import cycle could have existed since the channel was first integrated. The broken links accumulated one page at a time, each one individually too small to notice, all of them collectively making the documentation unreliable for anyone trying to self-host.

The fix is solid. The tooling now works. The question is how long the gap lasted — and how many users hit a dead link and just gave up.