Tools
Gnome Shell Extension
By OpenClaw plugin from kasparmir/openclaw-gnome-shell-extension
Configuration Example
{
"gateway": {
"http": {
"endpoints": {
"chatCompletions": { "enabled": true }
}
}
}
}README
# OpenClaw Chat — GNOME Shell extension
> **Note:** this is a vibe-coded extension, built primarily for the author's
> own personal use. It works, but expect rough edges and don't assume
> production-grade polish or support.
Chat with your [OpenClaw](https://openclaw.ai) agent directly from the GNOME
top bar. Set the Gateway URL, API token, agent ID and session key, and you
have a one-click chat with the agent — no browser needed.
Uses the same OpenClaw Gateway Chat Completions API as
[openclaw-conversation for Home Assistant](https://github.com/nicoglg/openclaw-conversation) —
`POST /v1/chat/completions`, `Authorization: Bearer <token>`.
Compatible with Ubuntu **24.04 LTS and newer**, including Ubuntu 26.04 (GNOME Shell 45–50, X11 and Wayland).
The UI is in English by default and switches to Czech automatically when the
system locale is Czech (via the bundled `po/cs.po` translation).
## What it does
- A panel icon that opens a chat (message history + input line) on click.
- Enter sends the message, the agent's reply appears in the same window.
- Settings in Preferences (Gateway URL, API token, Agent ID, Session key,
Model, timeout, local history length) + a "Test" button to verify the connection.
- A "New conversation" button clears the local history and starts over.
- The session key is sent as `"user": "conv:<key>"`, so the Gateway keeps the
same agent session across messages (memory, tools) — not just stateless queries.
- The agent ID is sent as `"model": "openclaw/<agent-id>"`; if empty, the
"Model" field is used instead (default `openclaw`).
## Installation
### Quick path (development / local use)
```bash
./install.sh
```
Creates a symlink into `~/.local/share/gnome-shell/extensions/<uuid>/` and
compiles the gsettings schema and Czech translation. Then:
```bash
# X11: Alt+F2, type "r", Enter
# Wayland: log out and back in (the Shell can't be restarted at runtime otherwise)
gnome-extensions enable openclaw-chat@miroslavkaspar.cz
gnome-extensions prefs openclaw-chat@miroslavkaspar.cz
```
Or open the **Extensions** app (preinstalled on Ubuntu 24.04) and enable/configure
the extension there via the gear icon.
### Package (.zip) for installation/distribution
```bash
./pack.sh
gnome-extensions install --force build/openclaw-chat@miroslavkaspar.cz.shell-extension.zip
```
## Settings
**Preferences → OpenClaw**
| Field | Description |
|---|---|
| Gateway URL | E.g. `http://192.168.1.100:18789`. Don't use `127.0.0.1` if the Gateway runs on a different machine or in Docker — there it refers to the container itself. |
| API token | Token from `gateway.auth` in `openclaw.json` (`token` mode). |
| Agent ID | Optional — a specific agent, sent as `openclaw/<agent-id>`. |
| Session key | Optional — any stable string (e.g. `desktop`, `notebook-kaspar`). Same key = the agent remembers context between messages on the Gateway side. |
| Model | Used only when Agent ID is empty. |
| Timeout / history | Request timeout and how many recent messages are sent as context. |
### Enabling the Chat Completions endpoint on the Gateway
In `openclaw.json`:
```json
{
"gateway": {
"http": {
"endpoints": {
"chatCompletions": { "enabled": true }
}
}
}
}
```
Restart the Gateway after the change.
## Troubleshooting
| Problem | Fix |
|---|---|
| "Invalid API token (401)" | Check the token and that `gateway.auth.mode` is `"token"`. |
| "Endpoint is disabled (405)" | Enable `chatCompletions` in `openclaw.json`, restart the Gateway. |
| "Could not connect to the Gateway" | Check `curl http://<ip>:<port>/v1/chat/completions`, the firewall, and that you're not using `127.0.0.1` across machines/containers. |
| Extension doesn't show up in the Extensions app | Check `shell-version` in `metadata.json` against your version (`gnome-shell --version`) and the logs: `journalctl -f -o cat /usr/bin/gnome-shell`. |
| Code changes don't take effect | On Wayland you need to log out/in, on Xorg Alt+F2 → `r` is enough. |
## Security note
The API token is stored via `Gio.Settings` (dconf) under your user account —
readable by other applications running as the same user, but not by other
users of the system. It is not encrypted. If you need stronger protection
(e.g. a shared computer), consider modifying `lib/openclawClient.js`/`prefs.js`
to store the token via `libsecret` (GNOME Keyring) instead of gsettings.
## Project structure
```
extension.js # panel indicator + chat logic (GNOME Shell process)
prefs.js # preferences window (Adw.PreferencesWindow, GTK4 process)
lib/openclawClient.js # shared HTTP client for /v1/chat/completions
schemas/ # gsettings schema (gateway-url, api-token, agent-id, …)
po/cs.po # Czech translation of the UI strings
icons/openclaw-symbolic.svg
stylesheet.css
install.sh / pack.sh
```
## Possible extensions (out of scope for v1)
- SSE streaming of responses (the Gateway supports it via `"stream": true`).
- Storing the token in `libsecret` instead of dconf.
- Persisting conversation history across Shell restarts.
- Showing `tool_calls` (when the agent calls a tool) in the UI.
tools
Comments
Sign in to leave a comment