How to Run OpenClaw in VS Code: Three Extension Approaches Compared

The official OpenClaw extension crossed 4,994 installs on the VS Code Marketplace as of June 2026, yet developers still ask which extension they should actually install. The confusion exists because OpenClaw's architecture separates concerns that other AI coding tools bundle together.

OpenClaw runs as a Gateway process that manages models, sessions, and skills. VS Code can connect to that Gateway in fundamentally different ways, and each connection type enables different workflows. The official extension manages the Gateway lifecycle. The Node extension makes VS Code addressable by the Gateway. The ACP Client routes prompts through a protocol layer that supports multiple agents, not just OpenClaw.

Most guides cover only the official extension, which handles model setup and Gateway launching but doesn't expose IDE commands like file editing, diagnostics, or git operations to the AI. If you want OpenClaw to read your codebase, find references, or commit changes through VS Code's API, you need the Node extension. If you want to switch between OpenClaw and Claude Code or Copilot from a single chat panel, ACP is the path.

The good news: these approaches aren't mutually exclusive. You can run the official extension for Gateway management alongside the Node extension for IDE command access, or pair either with the ACP Client for multi-agent workflows.

The official extension, published by gguf on the VS Code Marketplace, is the fast way to get OpenClaw running in VS Code. It adds a status bar magnet that launches and manages the OpenClaw Gateway without leaving the editor.

What it does

Click the status bar icon to access a menu with five commands: Dashboard (opens the browser UI), Checker (verifies your setup), Setup (configures model providers and API keys), Gateway (starts or stops the local Gateway), and Terminal (opens a preconfigured shell). The extension handles OS-specific terminal detection, choosing WSL on Windows and the native terminal elsewhere.

Install steps

1. Open VS Code and go to the Extensions panel
2. Search for "openclaw" and install the extension by gguf (version 0.3.7 or later)
3. Install the OpenClaw CLI globally using npm (see the official OpenClaw docs for current install instructions)
4. Click the magnet icon in the status bar and select Setup to configure your model provider
5. Select Gateway to start the local Gateway process
6. Open Dashboard to verify the connection in your browser

Optional dependency: Install gguf-connector via pip if you plan to use the Terminal feature for direct model interaction.

Auto-connect: By default, the extension doesn't automatically start the Gateway when VS Code opens. Enable this in Settings under Claw: Auto Connect if you want OpenClaw ready every time you open a project.

What it doesn't do

The official extension is a control panel for the Gateway, not a bridge between the Gateway and your editor. It can't read your open files, run diagnostics, execute git commands, or let the AI interact with VS Code's APIs. For those capabilities, you need the Node extension.

The OpenClaw Node extension (publisher: xiaoyaner, extension ID: xiaoyaner.openclaw-node-vscode) takes the opposite approach from the official extension. Instead of managing the Gateway from VS Code, it registers VS Code as a Node on the Gateway, making 40+ IDE commands available to any AI assistant connected to your OpenClaw setup.

Architecture

The extension connects to a running OpenClaw Gateway over WebSocket using the Node protocol. Once registered, your VS Code instance becomes addressable from OpenClaw conversations. When an AI assistant needs to read a file, find symbol references, or check git status, it calls commands like vscode.file.read, vscode.lang.references, or vscode.git.status through the Gateway, and the extension executes them inside VS Code's API sandbox.

Command categories

• File operations: read, write, edit, delete, list files in the workspace
• Editor controls: open files, get selections, retrieve cursor context
• Language intelligence: go-to-definition, find references, hover info, workspace symbols, rename, code actions, formatting
• Diagnostics: retrieve errors and warnings from VS Code's problem panel
• Git: status, diff, log, blame, stage, commit, stash
• Testing: discover and run tests through VS Code's test API
• Debugging: launch debug sessions, set breakpoints, evaluate expressions, inspect stack traces
• Workspace info: folder structure, installed extensions

Setup walkthrough

1. Download the latest .vsix from the GitHub releases page or install from the Marketplace
2. Open the command palette (Cmd+Shift+P on macOS, Ctrl+Shift+P on Windows/Linux)
3. Run "OpenClaw: Setup Wizard" and complete the four steps: Gateway connection (host, port, token), security preferences, terminal access settings, and agent configuration
4. Approve the device on your Gateway. The extension generates a unique Ed25519 keypair stored at ~/.openclaw-vscode/device.json, and the Gateway must approve this device before it can execute commands
5. Test with workspace.info from an OpenClaw conversation to confirm the bridge is active

Security model

All operations run through the VS Code Extension API sandbox, not raw filesystem access. Path traversal is blocked, restricting operations to workspace directories. Terminal access is disabled by default and requires explicit whitelisting of allowed commands. You can enable read-only mode or write confirmation prompts for additional control. Each extension instance authenticates via its Ed25519 keypair, and the Gateway can restrict which commands a specific device is allowed to execute.

Friction points

The Node extension requires a running Gateway before it can connect. If your Gateway restarts or your network drops, the WebSocket connection breaks and you need to reconnect manually or restart the extension. The Marketplace listing currently has 3,394 installs, and documentation beyond the GitHub README is sparse. Debugging connection failures means checking the Gateway logs, the extension output panel, and the device approval status independently.

Give your OpenClaw agent persistent file storage

A workspace with built-in AI indexing. Write agent output to Fast.io through the MCP server, share it with your team, and search files by meaning. Starts with a 14-day free trial.

Start 14-Day Trial

The Agent Client Protocol (ACP) is a newer approach that treats OpenClaw as one of many possible agents rather than the sole AI backend. The ACP Client extension (publisher: formulahendry, extension ID: formulahendry.acp-client) has 16,115 installs and supports 11 preconfigured agents, OpenClaw among them.

How ACP differs

Instead of a direct WebSocket connection to a single Gateway, ACP defines a standard protocol for IDE-to-agent communication. The openclaw acp command starts a bridge that speaks ACP over stdio and forwards prompts to the Gateway over WebSocket. Your IDE treats OpenClaw as an interchangeable agent, the same way it treats Claude Code, Copilot, or Gemini CLI.

OpenClaw 2026.2.26 elevated ACP Agents to first-class runtimes. OpenClaw can act as an ACP server (external clients connect to it) and as an ACP client (it connects to other ACP-compatible agents). This dual role means you can chain agents: start in an OpenClaw conversation, delegate a task to Claude Code via ACP, and pull the results back.

Setup steps

1. Make sure the OpenClaw CLI is installed globally (follow the official install guide for current steps) and complete the onboarding process if this is a fresh setup
2. Install the ACP Client extension from the VS Code Marketplace
3. Open the ACP Client panel from the Activity Bar
4. OpenClaw should appear in the preconfigured agent list. If it doesn't, add a custom agent configuration pointing to the openclaw acp command
5. Click Connect next to OpenClaw and start a conversation

The ACP Client provides a built-in chat panel with Markdown rendering, per-agent session lists for restoring conversation history, file system and terminal integration, slash command autocomplete, and protocol traffic logging for debugging connection issues.

Version compatibility note

Some developers report that specific OpenClaw versions work more reliably with ACP than others. If you encounter connection instability, try pinning to a known-good release. Check the OpenClaw changelog or community forums for version-specific ACP compatibility notes.

Limitations

The ACP bridge is not a full native editor runtime. The official docs note that client filesystem and terminal methods are unavailable through ACP, session plans and thought streaming aren't yet implemented, and loadSession only fully replays history for bridge-created sessions. Per-session MCP server configuration is also unsupported. If you need deep IDE integration with file operations and diagnostics, the Node extension is still the more capable path.

Each approach optimizes for a different workflow. Here's how to decide.

Use the official extension if you want the simplest path to running OpenClaw. You manage models, start the Gateway, and use the browser dashboard as your primary interface. VS Code is just where you edit code, and you switch to the OpenClaw dashboard for AI conversations. This is the right starting point if you're new to OpenClaw.

Use the Node extension if you want the AI to work inside your editor. The 40+ IDE commands mean OpenClaw can read your files, find references, run diagnostics, execute tests, and commit changes without you copying context manually. This is the setup for developers who want AI-assisted coding where the agent operates on the same workspace you're editing.

Use the ACP Client if you work with multiple AI coding agents and want a unified interface. ACP lets you switch between OpenClaw, Claude Code, Copilot, and others from the same chat panel. This is the right choice if you use different agents for different tasks, or if your team standardizes on ACP as the protocol layer.

Combine them for the most capable setup. Run the official extension for Gateway management, the Node extension for IDE command access, and optionally the ACP Client if you also use other agents. The extensions don't conflict since they serve different roles.

A practical starting configuration for most developers: install the official extension first to get the Gateway running, then add the Node extension once you want the AI to interact with your codebase directly. Add ACP later if your workflow grows to include multiple agents.

The OpenClaw VS Code setup handles the IDE side, but agent-generated output needs somewhere to persist beyond your local machine. Code files stay in your git repository, but agents also produce research notes, analysis reports, configuration drafts, and documentation that doesn't belong in version control.

Fast.io provides persistent workspaces where agents and humans share the same files. When your OpenClaw agent generates a project plan, competitive analysis, or client deliverable, it can write that output to a Fast.io workspace through the MCP server rather than leaving it scattered across local directories. The workspace indexes uploaded files automatically through Intelligence Mode, making them searchable by meaning rather than just filename.

For teams running OpenClaw alongside other AI tools, Fast.io acts as the shared storage layer. An OpenClaw agent writes a draft to a workspace, a human reviews it through the browser UI, and a different agent picks it up for further processing. The ownership transfer feature lets an agent build a complete workspace and hand control to a human when the work is ready for review.

Local storage, S3, and Google Drive also work for persisting agent output. Local storage is free but limited to one machine. S3 gives you programmatic access but requires infrastructure setup. Google Drive works for sharing but lacks the built-in indexing and agent-aware features. Fast.io plans start with a 14-day free trial (Solo at $29/month, Business at $99/month), with storage, monthly credits, and workspaces scaled to each tier, which covers most individual developer workflows with OpenClaw.