Kyvero-Vexus/openclaw.el
2
0
Fork 0
Code Issues Pull requests Projects Releases Packages Activity
Emacs interface to OpenClaw
42 commits 1 branch 0 tags 104 KiB
  • Emacs Lisp 89.1%
  • JavaScript 5.8%
  • Shell 4.8%
  • Makefile 0.3%
Find a file
Exact
chrysolambda-ops e14873a281 docs: add AGENTS contribution and PR workflow guide
2026-04-02 00:08:26 -04:00
.beads feat: robust reconnect + incremental streaming + no refetch storms 2026-03-08 05:34:07 -04:00
.githooks fix: handle real gateway protocol for streaming events 2026-03-08 12:05:46 -04:00
docs feat: TUI feature parity with E2E test suite (61/61 pass) 2026-03-08 04:31:43 -04:00
test fix: handle real gateway protocol for streaming events 2026-03-08 12:05:46 -04:00
.gitignore fix: handle real gateway protocol for streaming events 2026-03-08 12:05:46 -04:00
AGENTS.md docs: add AGENTS contribution and PR workflow guide 2026-04-02 00:08:26 -04:00
LICENSE Initial commit: Emacs interface to OpenClaw 2026-03-08 04:31:42 -04:00
Makefile feat: TUI feature parity with E2E test suite (61/61 pass) 2026-03-08 04:31:43 -04:00
openclaw-pkg.el Add straight.el installation support 2026-03-08 04:31:42 -04:00
openclaw.el fix: handle real gateway protocol for streaming events 2026-03-08 12:05:46 -04:00
README.org docs: note history unification commit across GitHub/GitLab 2026-03-08 07:05:49 -04:00

README.org

openclaw.el

Overview

openclaw.el is an Emacs package that provides a complete interface to OpenClaw, your personal AI assistant.

Each OpenClaw session becomes its own Emacs buffer, and you get:

  • Leader-key based keybindings for all slash commands
  • Direct slash command support for those who prefer it
  • Full feature parity with the OpenClaw TUI
  • Multiple simultaneous sessions in separate buffers

Installation

With straight.el and use-package (recommended)

If you use straight.el with use-package, add this to your init file:

(use-package openclaw
  :straight (openclaw :type git :host github :repo "Kyvero-Vexus/openclaw.el")
  :config
  (setq openclaw-gateway-url "ws://127.0.0.1:18789"))

With straight.el only 

(straight-use-package
 '(openclaw :type git :host github :repo "Kyvero-Vexus/openclaw.el"))

With Quelpa 

(use-package openclaw
  :quelpa (openclaw :fetcher github :repo "Kyvero-Vexus/openclaw.el"))

Manual installation

Clone this repository and add to your load-path:

(add-to-list 'load-path "/path/to/openclaw.el")
(require 'openclaw)

Dependencies

  • Emacs 27.1 or later
  • websocket package (for WebSocket communication)

straight.el and package.el will install dependencies automatically.

Quick Start

  1. Connect to your OpenClaw gateway:

    M-x openclaw-connect RET

  2. Start chatting:

    M-x openclaw-chat RET
  3. Type your message and press C-c C-c to send.

Configuration

Gateway settings 

(setq openclaw-gateway-url "ws://127.0.0.1:18789"
      openclaw-gateway-token "your-token-here")

Leader key

By default, leader-style commands are accessible under C-c in openclaw-mode:

(setq openclaw-leader-key "C-c")  ; default

Keybindings

Chat mode (openclaw-chat-mode)

Key Command
RET Send message
C-c C-c Send message
C-c C-l List sessions
C-c C-s Switch session
C-c C-n New chat
C-c C-h Show history
C-c C-q Close connection

Leader keys

In openclaw-mode, single-letter commands are available:

Key Command
c Connect
C Close connection
l List sessions
s Switch session
n New chat
m Send message
h Show history
? Help

Slash Commands

You can still use OpenClaw slash commands directly by typing them in the chat buffer:

  • /status - Show session status
  • /clear - Clear chat history
  • /model - Change model
  • /help - Show gateway help

Gateway Protocol

openclaw.el communicates with the OpenClaw gateway via JSON-RPC over WebSocket:

  • Default URL: ws://127.0.0.1:18789
  • Protocol: JSON-RPC 2.0

  • Methods used:

    • sessions.list - List available sessions
    • chat.send - Send a message
    • chat.history - Fetch message history

See the OpenClaw Gateway documentation for more details.

Troubleshooting

Authentication failures with gateway v2026.3.7+

Starting with OpenClaw gateway v2026.3.7, the gateway.auth.mode configuration field is required. If you see authentication errors ("auth mode not configured" or similar), ensure your ~/.openclaw/openclaw.json includes:

{
  "gateway": {
    "auth": {
      "mode": "token",
      "token": "your-token-here"
    }
  }
}

Valid mode values: token, password, none. When mode is omitted the gateway will reject all connection attempts.

Repository History

On 2026-03-08, this repository's GitHub and GitLab histories were unified with a history-preserving merge commit on main:

  • Commit: e8cc6dc
  • Purpose: connect previously unrelated remote histories while preserving the canonical working tree from this repository.

If you're auditing old refs or bisecting across remotes, use e8cc6dc as the history unification point.

Development

Running tests 

make test

Byte compilation check 

make compile

License

GNU Affero General Public License v3.0 or later. See LICENSE for details.

Links