什么是 Niri IPC？

Niri IPC 技能提供了一个强大的接口，用于与 Linux 上的 Niri Wayland 合成器进行交互。通过利用原生 IPC 机制 ($NIRI_SOCKET) 或提供的 Python 辅助脚本，该工具允许 Openclaw Skills 以编程方式查询桌面环境的状态并执行复杂的布局操作。它是 AI 代理与 Linux 窗口管理器之间的桥梁，使得通过结构化的命令行界面自动化 GUI 相关任务成为可能。

无论您是需要根据标题聚焦特定窗口、在工作区之间移动应用程序，还是重新加载配置文件，此技能都能简化流程。它将原始的 JSON 套接字通信抽象为易于使用的命令，对于希望获得代理驱动桌面体验的开发者和高级用户来说，这是一个至关重要的组件。

下载入口:https://github.com/openclaw/skills/tree/main/skills/atefr/niri-ipc

安装与下载

1. ClawHub CLI

从源直接安装技能的最快方式。

2. 手动安装

将技能文件夹复制到以下位置之一

优先级：工作区 > 本地 > 内置

3. 提示词安装

将此提示词复制到 OpenClaw 即可自动安装。

Niri IPC 应用场景

• 根据当前项目上下文自动管理窗口布局。
• 通过代理使用自然语言切换工作区或聚焦特定应用程序。
• 坚控窗口事件以触发自动响应或通知。
• 在开发或测试期间快速重新加载合成器配置。
• 通过 IPC 命令生成新的终端实例或 GUI 应用程序。

1. 该技能通过定为Linux 系统上的 $NIRI_SOCKET 环境变量来识别活动的 Niri 会话。
2. 通过 niri msg 命令行工具或直接向 Unix 套接字写入换行符分隔的 JSON 来发布命令。
3. niri.py 和 niri_ctl.py 等 Python 封装脚本解析生成的 JSON 数据，以提供人类可读的摘要或高级过滤。
4. AI 代理处理结构化输出，以决定后续的布局或窗口管理操作。
5. 可以打开持续的事件流，以合成器状态的实时变化。

Niri IPC 配置指南

要在 Openclaw Skills 框架内使用此技能，请确保您在 Linux 上运行 Niri。您的环境中必须设置 $NIRI_SOCKET。

# 测试与 Niri 的连接
./skills/niri-ipc/scripts/niri.py version

# 列出所有当前打开的窗口
./skills/niri-ipc/scripts/niri.py windows

# 聚焦一个工作区
./skills/niri-ipc/scripts/niri_ctl.py focus-workspace 1

Niri IPC 数据架构与分类体系

该技能利用 JSON 进行所有数据交换。以下是主要数据结构的组织形式：

name: niri-ipc
description: Control the Niri Wayland compositor on Linux via its IPC (`niri msg --json` / $NIRI_SOCKET). Use when you need to query Niri state (outputs/workspaces/windows/focused window) or perform actions (focus/move/close windows, switch workspaces, spawn commands, reload config) from an OpenClaw agent running on a Niri session.

Niri IPC

Use Niri IPC through the niri msg CLI (preferred) or by writing JSON requests to $NIRI_SOCKET.

This skill assumes:

• You are on Linux with Niri running.
• $NIRI_SOCKET is set (usually true inside the Niri session).

Quick start (recommended)

Use the bundled helper script (wrapper around niri msg --json):

./skills/niri-ipc/scripts/niri.py version
./skills/niri-ipc/scripts/niri.py outputs
./skills/niri-ipc/scripts/niri.py workspaces
./skills/niri-ipc/scripts/niri.py windows
./skills/niri-ipc/scripts/niri.py focused-window

Deeper control

1) High-level helpers (window matching)

Use scripts/niri_ctl.py when you want to refer to windows by title/app_id substring instead of ids:

# List windows (optionally filtered)
./skills/niri-ipc/scripts/niri_ctl.py list-windows --query firefox

# Focus a window by substring match
./skills/niri-ipc/scripts/niri_ctl.py focus firefox

# Close a matched window (focus then close)
./skills/niri-ipc/scripts/niri_ctl.py close firefox

# Move a matched window to a workspace (by index or by name)
./skills/niri-ipc/scripts/niri_ctl.py move-to-workspace firefox 3
./skills/niri-ipc/scripts/niri_ctl.py move-to-workspace firefox web

# Focus a workspace by index or name
./skills/niri-ipc/scripts/niri_ctl.py focus-workspace 2
./skills/niri-ipc/scripts/niri_ctl.py focus-workspace web

2) Full IPC access (raw socket)

Use scripts/niri_socket.py to talk to $NIRI_SOCKET directly (newline-delimited JSON):

# Send a simple request (JSON string)
./skills/niri-ipc/scripts/niri_socket.py raw '"FocusedWindow"'

# Batch requests: one JSON request per line on stdin
printf '%s
' '"FocusedWindow"' '"Workspaces"' | ./skills/niri-ipc/scripts/niri_socket.py stdin

# Event stream (prints JSON events until interrupted)
./skills/niri-ipc/scripts/niri_socket.py event-stream

Actions

Pass through Niri actions:

# Focus workspace by index
./skills/niri-ipc/scripts/niri.py action focus-workspace 2

# Move focused window to workspace
./skills/niri-ipc/scripts/niri.py action move-window-to-workspace 3

# Focus a window by id
./skills/niri-ipc/scripts/niri.py action focus-window 123

# Close focused window
./skills/niri-ipc/scripts/niri.py action close-window

# Reload niri config
./skills/niri-ipc/scripts/niri.py action load-config-file

# Spawn (no shell)
./skills/niri-ipc/scripts/niri.py action spawn -- alacritty

# Spawn through shell
./skills/niri-ipc/scripts/niri.py action spawn-sh -- 'notify-send hello'

Output configuration

Use niri msg output ... via the wrapper:

./skills/niri-ipc/scripts/niri.py output --help

Working directly with niri msg

If you don’t want the helper script, call Niri directly:

niri msg --json windows
niri msg --json action focus-workspace 2

Tip: if niri msg parsing errors happen after upgrades, restart the compositor (new niri msg against old compositor is a common mismatch).

Event stream

For status bars/daemons: Niri can stream events.

# Raw JSON event lines (runs until interrupted)
./skills/niri-ipc/scripts/niri.py event-stream

# Just a few lines for a quick test
./skills/niri-ipc/scripts/niri.py event-stream --lines 5

Troubleshooting

• If commands fail with “NIRI_SOCKET is not set”: run inside your Niri session, or export the socket path.
• If you need the socket protocol details, read: ./skills/niri-ipc/references/ipc.md.
• If your goal is complex automation (pick the right window by title/app_id, etc.), first query windows, then act by window id.