Tools
Vsclaw
By VS Code extension for OpenClaw — chat gateway client (community project)
Install
npm install
scripts/install-local.shREADME
# VSClaw
**VSClaw** is a VS Code extension for [OpenClaw](https://docs.openclaw.ai). It lets you chat with the agents on your OpenClaw Gateway from the editor, with your code as context. It also sets up, runs and hardens OpenClaw from the activity bar.
It has no telemetry. On the Gateway transport the extension talks only to the Gateway you configure. If the Gateway cannot be reached, it can fall back to the local [`acpx`](https://www.npmjs.com/package/acpx) CLI.
- [Features](#features)
- [Requirements](#requirements)
- [Install](#install)
- [Connect to your Gateway](#connect-to-your-gateway)
- [Where your code lives](#where-your-code-lives)
- [Commands](#commands) · [Settings](#settings)
- [Security and privacy](#security-and-privacy)
- [Troubleshooting](#troubleshooting)
- [Status and roadmap](#status-and-roadmap)
- [Contributing](#contributing)
## Features
### Chat with Gateway agents
- **Direct Gateway connection.** The extension connects to the OpenClaw Gateway over WebSocket using Gateway protocol v4. If the connection drops, it reconnects with backoff. After a reconnect or a window restart, it fetches the messages you missed.
- **Agent and session picker.** Pick an agent's session and every message goes to it. An indicator shows when a run is already active.
- **History and resume.** Reopen an earlier session and continue where you left off.
- **Streaming replies.** Replies stream as they are written. Tool calls are grouped into collapsible steps, and a setting can hide the finished ones.
- **Approvals and questions in the chat.** When the Gateway needs approval for a command or a plugin action, or asks you a question, you answer it in the chat.
- **Stop** a running reply at any time.
- **Several threads at once.** Show threads in a grid from `1x1` up to `4x4`. Each thread has its own composer and status. You can also pop the chat out into an editor tab.
- **Usage gauge.** Shows the tokens used against the model's context window.
- **Export** a conversation to Markdown or JSON.
### Your code as context
- **`@`-mentions** attach workspace files. You can attach a range of lines, such as `@src/app.ts#L5-10`.
- **Insert selection** adds the selected code as a mention. The shortcut is `Alt+K` (`Cmd+Alt+K` on macOS).
- **Attach the open file** to every normal message with `openclaw.chat.attachOpenFile`. Slash commands do not use this setting; they add their own context (see the table below).
- **Attachments**, including images, through the `+` button or drag and drop.
- **Slash commands** add the context that fits the task:
| Command | Purpose | Context added |
| --- | --- | --- |
| `/explain` | Explain code or a concept | Selection or file |
| `/fix` | Find and fix problems | Diagnostics and code |
| `/review` | Review changes | Git diff |
| `/test` | Write tests | Selection or file |
| `/refactor` | Suggest improvements | Selection or file |
| `/doc` | Write documentation | Selection or file |
| `/commit` | Draft a commit message | Staged changes |
| `/harden` | Security review | File contents |
| `/plan` | Plan the work before changing anything | None (only your task) |
| `/compact` | Summarise the conversation so far | The transcript |
| `/search` | Search the codebase | Your query |
### OpenClaw tools
- **Overview view** in the activity bar, with these sections:
- getting started;
- operations: status, doctor, update, dashboard and config;
- hardening;
- installed tools, which you can enable, disable or uninstall;
- help.
- **Security hardening.** Runs `openclaw security audit`, optionally with its fix and deep scans. It also writes a plain-language **access summary** of the MCP servers, tools, key sources, endpoints and local files OpenClaw can reach.
- **Guided setup** and a **model setup wizard**, for when the OpenClaw CLI is missing or not configured yet.
- **Status bar indicator** that shows the connection and connects in one click.
## Requirements
| Area | Supported |
| --- | --- |
| VS Code | 1.140 or newer |
| OpenClaw Gateway | Protocol v4 (OpenClaw 2026.9.x) |
| Operating systems | Linux, macOS and Windows (CI tests all three) |
| Remote development | SSH, WSL and Tunnel |
| VS Code forks (VSCodium, Cursor, …) | Planned through Open VSX; not tested yet |
You also need a chat backend. You can use either one, or both:
- **An OpenClaw Gateway you can reach, and its token.** This is the main path. The Gateway can run on this machine, on a server or NAS, or in Docker. To install one, see the [OpenClaw docs](https://docs.openclaw.ai) or run `openclaw onboard --install-daemon`.
- **[`acpx`](https://www.npmjs.com/package/acpx) on your `PATH`**, for the local CLI transport. With `openclaw.gateway.transport` set to `acpx`, no Gateway is needed. With `auto` (the default), acpx is used only when the Gateway cannot be reached.
## Install
Until the first public release, build and install from source. Afterwards, install from the [VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=OlehPendrakovskyi.vsclaw) or [Open VSX](https://open-vsx.org/extension/OlehPendrakovskyi/vsclaw). To build from source you need:
- **git**;
- **Node.js 24 (24.15 or later)**, the version CI builds with;
- **pnpm** (run `corepack enable` to get it);
- the `code` or `cursor` command on your `PATH`.
On Linux, on macOS, or on Windows with Git Bash or WSL:
```sh
git clone https://github.com/OlehPendrakovskyi/vsclaw.git
cd vsclaw
pnpm install
scripts/install-local.sh
```
The script compiles the extension, packages it as a `.vsix` and installs it into `cursor` or `code`, whichever is on your `PATH`. Reload the window afterwards.
In PowerShell, or any shell without Bash, run the same steps by hand:
```sh
git clone https://github.com/OlehPendrakovskyi/vsclaw.git
cd vsclaw
pnpm install
pnpm run compile
pnpm dlx @vscode/vsce@4.0.0 package --no-dependencies -o vsclaw.vsix
code --install-extension vsclaw.vsix --force # or: cursor --install-extension vsclaw.vsix --force
```
> **The extension ID changed.** A local build installed before the rename registers as `openknot.claw-code`, and one built between the rename and the publisher change registers as `openknot.vsclaw`; the released VSClaw registers as `OlehPendrakovskyi.vsclaw`. VS Code treats these as different extensions, which has two effects:
>
> - Uninstall the old build first: `code --uninstall-extension openknot.claw-code` (and `code --uninstall-extension openknot.vsclaw` if you installed a build between the rename and the publisher change).
> - VS Code keeps stored secrets and extension state per extension ID. After the switch, you enter the Gateway token again, pair the device again, and approve each workspace's `.acpxrc.json` again.
## Connect to your Gateway
1. Set the Gateway address in **Settings → OpenClaw → Gateway: Url** (`openclaw.gateway.url`). The default is `ws://127.0.0.1:18789`.
2. Run **OpenClaw: Connect to Gateway** from the Command Palette and paste the Gateway token. The token is stored in VS Code's SecretStorage, never in `settings.json`.
3. Open the **OpenClaw** view in the activity bar. Pick an agent with **OpenClaw: Pick Agent Session**, and start chatting.
The first time you connect, the Gateway may ask you to approve this device. This step is called pairing. Approve the device on the Gateway, for example in the OpenClaw Control UI. To start again with a new device identity, run **OpenClaw: Reset Gateway Device Identity**.
> **Use `wss://` for a Gateway on another machine.** The token is sent as soon as the connection opens. Over plain `ws://`, a Gateway on a NAS or a server receives it unencrypted across the network. VSClaw asks before it sends the token that way: **Connect This Time** allows it until the window closes, **Always Allow This Gateway** adds the URL to `openclaw.gateway.allowUnencryptedUrls`, and closing the dialog sends nothing and stops it asking for that URL until you change a gateway setting. Use `wss://` or a secure tunnel instead, such as SSH port forwarding, Tailscale or WireGuard.
### Local CLI fallback
`openclaw.gateway.transport` decides which backend the chat uses:
- `gateway`: always the Gateway.
- `acpx`: always the local CLI.
- `auto` (the default): the Gateway when it can be reached, otherwise acpx.
With acpx, `openclaw.chat.agent` chooses the agent and `openclaw.chat.permissions` decides what it may do. A workspace can redefine the commands acpx runs for agents and MCP servers in an `.acpxrc.json` file. VSClaw uses that file only after you approve it, and asks again whenever the file changes.
## Where your code lives
Often the Gateway and the agent's workspace run on one host, such as a server, a NAS or a Docker container, while VS Code runs on another. What the extension can do with your files depends on where the repository is:
| Setup | What to do |
| --- | --- |
| **The repository is on the Gateway host** (server, NAS or Docker) | Open the repository with VS Code **Remote** (SSH, WSL or Tunnel), so the editor and the agent see the same files. This setup gets the best support. |
| **The repository is on the Gateway host, but your VS Code window is local** | Chat works, and the agent edits files on the Gateway host. The editor shows those changes only as text in the chat. |
| **The agent cannot reach your code** | Attach files and selections to the prompt. The agent replies with a patch, which you apply yourself. |
## Commands
| Command | Description |
| --- | --- |
| OpenClaw: Open Chat | Focus the chat view |
| OpenClaw: Pop Out Chat | Move the chat into an editor tab |
| OpenClaw: New Chat Session | Open a new, empty thread in the panel. On the Gateway it uses the default session, so it keeps that session's context. For a separate context, pick another session with **Pick Agent Session** |
| OpenClaw: Pick Agent Session | Choose the Gateway agent session to talk to |
| OpenClaw: Connect to Gateway | Save the Gateway token and connect |
| OpenClaw: Reset Gateway
... (truncated)
tools
Comments
Sign in to leave a comment