mirror of
https://github.com/headroomlabs-ai/headroom.git
synced 2026-08-27 14:17:10 -04:00
2e6c442dc8
## Description
The `headroom-openclaw` plugin silently fails to load on OpenClaw
2026.x. OpenClaw's plugin loader calls `setupRegistration.register(api)`
on the plugin's default export. The current plugin exports a **bare
function** as its default — which has no `.register()` method — so the
loader skips it silently and the plugin never initializes. No error is
thrown, no warning logged. The plugin appears "enabled" in the registry
but does nothing.
Fix: wrap the function in a `{ register: headroomPlugin }` object. One
structural change, plugin body unchanged.
## Type of Change
- [x] Bug fix (non-breaking change that fixes an issue)
## Changes Made
- Wrapped `export default function headroomPlugin(api)` in a `{
register: headroomPlugin }` object so OpenClaw's loader can call
`.register(api)` on it
## Testing
- [ ] Unit tests pass (`pytest`)
- [ ] Linting passes (`ruff check .`)
- [ ] Type checking passes (`mypy headroom`)
- [ ] New tests added for new functionality
- [x] Manual testing performed
### Test Output
```text
$ node -e "
const mod = require('./plugins/openclaw/dist/index.js');
const plugin = mod.default;
console.log('type:', typeof plugin);
console.log('has register:', typeof plugin.register);
const mockApi = {
config: { plugins: { entries: { headroom: { config: { proxyUrl: 'http://127.0.0.1:8787' } } } } },
logger: { info: (m) => console.log('INFO:', m), warn: console.warn, error: console.error },
registerContextEngine: (id) => console.log('registerContextEngine:', id),
registerTool: () => console.log('registerTool called'),
on: (e) => console.log('on:', e),
};
plugin.register(mockApi);
"
type: object
has register: function
registerContextEngine: headroom
registerTool called
on: gateway_start
INFO: [headroom] Plugin registered
INFO: Headroom proxy ready at http://127.0.0.1:8787
```
## Real Behavior Proof
- Environment: macOS 15.x arm64, OpenClaw 2026.6.8, Node.js v25.8.0,
headroom-openclaw 0.1.0
- Exact command / steps: `openclaw plugins install headroom-ai/openclaw`
→ restart OpenClaw → check gateway logs for `[headroom]` entries → check
`curl http://localhost:8787/stats` for `api_requests > 0`
- Observed result: Before fix — no `[headroom]` log entries, proxy never
started, `api_requests: 0`. After fix — `[headroom] Plugin registered`
in gateway log, proxy starts, `api_requests: 135`, `$10.11` saved in one
session.
- Observed result (after fix): `[headroom] Plugin registered` in gateway
log. Proxy starts on port 8787. Real Anthropic API calls intercepted —
`/stats` showed `api_requests: 135`, `total_saved_usd: 10.11` after one
session.
- Not tested: Windows, Linux
## Review Readiness
- [x] I have performed a self-review
- [x] This PR is ready for human review
## Checklist
- [x] My code follows the project's style guidelines
- [x] I have performed a self-review of my code
- [x] I have commented my code, particularly in hard-to-understand areas
- [ ] I have made corresponding changes to the documentation
- [x] My changes generate no new warnings
- [ ] I have added tests that prove my fix is effective or that my
feature works
- [x] New and existing unit tests pass locally with my changes
- [ ] I have updated the CHANGELOG.md if applicable
## Additional Notes
Found while integrating headroom into
[Vespera](https://github.com/problemsolverai2026-svg/vespera), a
persistent local AI system. The workaround was manually setting
`models.providers.anthropic.baseUrl = "http://127.0.0.1:8787"` in
OpenClaw config — which works but bypasses the plugin entirely. The
proper plugin path should work out of the box.
|
||
|---|---|---|
| .. | ||
| headroom-agent-hooks | ||
| headroom-oauth2 | ||
| hermes | ||
| openclaw | ||