DOCSEARCHbyAlgolia
Submit Docs

nexu Documentation

repository·main·Indexed 23 days ago

https://github.com/nexu-io/nexu

An open-source desktop client that connects AI Agents (via OpenClaw) to messaging platforms including WeChat, Feishu, Slack, and Discord. Features include a GUI for managing AI workflows, the @nexu/web management frontend for bot lifecycles and channel integration, and a 'Research to Diagram' skill utilizing Graphviz for generating visual maps and PDFs from research data.

Tokens
199.7K
Snippets
368
Records
1.1K
Agent score
85%

What's inside nexu

  1. Overview of nexu-pal automation workflows

    main

    nexu-pal provides GitHub issue and discussion automation, including automated triage, translation, and Feishu notifications. It uses a pipeline of scripts to process incoming GitHub events.

    Core Workflows

    WorkflowTriggerScript
    nexu-pal: issue openedissues: [opened]scripts/nexu-pal/process-issue-opened.mjs
    nexu-pal: triage commandissue_comment: [created] (issues only)scripts/nexu-pal/process-triage-command.mjs
    Feishu Issue Notificationissues: [opened]scripts/notify/feishu-notify.mjs
    nexu-pal: needs-triage notifyissues: [labeled] (when label is needs-triage)scripts/notify/feishu-triage-notify.mjs
    Feishu Discussion Notificationdiscussion: [created]scripts/notify/feishu-notify.mjs
    Feishu Pull Request Notificationpull_request_target: [opened]inline workflow script

  2. Overview of nexu

    main

    nexu (next to you) is an open-source desktop client that allows you to run OpenClaw 🦞 Agents directly within Instant Messaging (IM) platforms such as WeChat, Feishu, Slack, and Discord.

    Key features include:

    • IM Integration: Connect to WeChat (via WeChat 8.0.7 OpenClaw plugin), Feishu, Slack, or Discord to interact with AI Agents from your mobile device or desktop.
    • Model Flexibility: Use top-tier models like Gemini via a nexu account, or bring your own API keys for other providers.
    • OAuth Support: One-click authentication for providers like MiniMax, OpenAI Codex, and GLM (Z.AI Coding Plan) without manual API key entry.
    • Privacy: A local-first approach where data stays on your device.
    • Ease of Use: A pure GUI experience designed for double-click installation without requiring CLI or complex environment setups.

  4. Introduction to nexu

    main

    nexu (next to you) is an open-source Electron-based desktop client designed to connect OpenClaw 🦞 agents to various Instant Messaging (IM) channels such as Feishu, Slack, and Discord.

    Key features include:

    • Graphical setup interface.
    • Built-in Feishu Skills.
    • Multi-model support.
    • Bring Your Own Key (BYOK) capability.
    • Local-first approach: Configuration and runtime state stay primarily on your machine.

  5. Navigate the Monorepo Layout

    main

    The Nexu repository is organized as a pnpm workspace with the following key directories:

    • apps/controller/: The single-user controller service. Contains routes (src/routes/), local store (src/store/), OpenClaw runtime integration (src/runtime/), and the compiler logic (src/lib/openclaw-config-compiler.ts).
    • apps/web/: The React frontend. Contains pages (src/pages/), the generated SDK (lib/api/), and the auth client (src/lib/auth-client.ts).
    • apps/desktop/: The Electron desktop shell that orchestrates the controller, web, and openclaw sidecars.
    • packages/shared/: Contains shared Zod schemas (bot, channel, gateway, invite, model, skill, and OpenClaw config).
    • nexu-skills/: The public skill repository. Skills are directories containing SKILL.md frontmatter; skills.json acts as the catalog index.
    • specs/: Design documents, product specs, and generated artifacts.

  6. Understand the nexu Agent concept

    main

    The Agent is the central runtime unit in nexu. It is a persistent AI assistant designed to connect to multiple chat platforms, maintain context, and execute tasks.

    Key characteristics:

    • Each workspace runs exactly one Agent instance.
    • The Agent can be configured with different Models.
    • The Agent can be extended with various Skills.
    • The Agent serves users and teams across multiple Channels.

  7. Understand OpenClaw Core Concepts

    main

    OpenClaw's architecture is built around several key entities that define how digital employees (Agents) interact with communication platforms (Channels):

    • Gateway: A single Node.js process that serves as the runtime core. It manages the lifecycle of all Agents, Channels, and Sessions. It is not a microservice, but a 'universal container' that listens on a single port (default 18789) and handles HTTP/WS requests, Channel monitoring, and Agent execution.
    • Agent: A logical identity defined in configuration (not a separate process). Each Agent has its own Workspace (personality/SOUL.md and memory/MEMORY.md), Session directory (conversation history), and Memory database (SQLite vector index).
    • Channel: The communication medium (e.g., Slack, Discord, WhatsApp). A Channel can host multiple Accounts.
    • Account: An abstraction of a specific identity within a Channel (e.g., a specific Slack bot token). Each Account runs an independent Monitor to listen for messages.
    • Binding: Routing rules that map a specific Channel Account to a specific Agent.
    • Session: A persistent record of a specific conversation context, isolated by an agentId, channel, and peerId.

  8. Manage Feishu Bitable (多维表格) with the Bitable SKILL

    main

    The feishu-bitable SKILL allows for creating, querying, editing, and managing Feishu Bitable databases. It supports 27 field types, advanced filtering, batch operations, and view management.

    Key Capabilities:

    • Create/manage Bitable Apps, Tables, Fields, and Views.
    • Create, query, update, and delete records (rows).
    • Perform batch imports and updates (up to 500 records per call).
    • Advanced filtering and sorting of records.

    Prerequisites:

    • Requires the @larksuite/openclaw-lark plugin.

  9. Understand Skill Installation Paths in OpenClaw

    main

    OpenClaw supports three distinct methods for installing skills, which determine where they are stored and how Nexu tracks them:

    1. SkillHub UI (install/import): Stored in ${stateDir}/skills/ (shared extraDirs). These are tracked in the Nexu ledger.
    2. Agent conversation (clawhub install): Stored in ${stateDir}/agents/${botId}/skills/ (workspace). These are considered workspace skills.
    3. Static/bundled: Stored in ${stateDir}/skills/ (shared). These are tracked via startup reconciliation.

  10. Understand the SkillHub Install Queue architecture

    main

    The SkillHub Install Queue is designed to manage skill installations via a FIFO (First-In-First-Out) mechanism to prevent ClawHub rate limiting.

    Key features include:

    • Concurrency Control: Limits installations to a maximum of 2 concurrent downloads.
    • Rate-Limit Handling: Automatically pauses the entire queue when ClawHub rate limits are hit, using the reset duration provided in the error message (with a 3s floor and 60s cap). It allows up to 5 retries per item for rate-limit errors.
    • External Change Detection: Uses a SkillDirWatcher to monitor the skills directory for SKILL.md additions or removals (e.g., from OpenClaw agent commands) and triggers ledger synchronization.
    • Atomicity: Skills are written to a temporary directory and then renamed to the final directory to ensure installation integrity.
    • Frontend Integration: The catalog API response is extended with a queue array to allow the frontend to display queued or downloading statuses on skill cards.

  11. Understand Model Provider Registry and Alias Normalization

    main

    The Model Provider Registry serves as the Single Source of Truth (SSoT) for provider metadata and capabilities. To prevent identity duplication, the registry uses an alias normalizer.

    Key Requirements for Registry Entries:

    • Every entry must have a valid canonical ID and metadata.
    • Alias normalization must be deterministic (e.g., treating aliases like kimi, glm, and gemini as related to their canonical providers rather than unrelated entities).
    • There must be no duplicate canonical IDs or alias collisions.

    Implementation Strategy:

    • Keep the registry focused on metadata and declarative capability policy.
    • Keep imperative runtime logic in the compiler/materialization code to avoid a monolithic registry.

  12. Understand the Slimclaw Runtime Unification architecture

    main

    Nexu is migrating to a unified runtime ownership model via packages/slimclaw. Previously, the OpenClaw runtime was fragmented across multiple producers (e.g., openclaw-runtime/, openclaw-runtime-patches/, and various dev/desktop scripts).

    Under the new architecture:

    • packages/slimclaw is the single owner of the runtime build, patching, and artifact contract.
    • packages/slimclaw/build.mjs is the single entry point for runtime builds.
    • Consumers (dev, controller, desktop, and tests) are strictly consumers of runtime artifacts and are no longer responsible for producing, patching, or staging them.

    This unification aims to reduce developer cold-start latency and build times by centralizing optimizations like prebundling and pruning.