DOCSEARCHbyAlgolia
Submit Docs

ClawPort

repository·main·Indexed 21 days ago

https://github.com/johnriceml/clawport-ui

An open-source dashboard and visual command center for managing, monitoring, and interacting with OpenClaw AI agents. ClawPort provides tools for chat, Kanban-based task management, cost tracking, agent orchestration visualization, and memory file browsing. It includes a CLI for setup and environment diagnostics via the `clawport doctor` command.

Tokens
32K
Snippets
109
Records
149
Agent score
75%

What's inside clawport-ui

  1. What is the Agent Client Protocol (ACP)?

    main

    ACP is OpenClaw's protocol for external tools to interact with running agent sessions. ClawPort uses ACP implicitly through gateway endpoints and CLI commands.

    Key concepts:

    • Sessions: Identified by a sessionKey (e.g., agent:main:clawport), sessions scope conversations between a client and an agent.
    • Device keys: Keypair-based authentication for write operations; the CLI manages these automatically.
    • Scopes:
      • operator.read: Accessible via HTTP.
      • operator.write: Accessible via CLI with device keys.

  2. Understand the ClawPort Component Tree

    main

    The ClawPort UI is structured as a hierarchical tree of components. At the top level, RootLayout provides the foundation, wrapping the application in ThemeProvider and SettingsProvider. These providers enable global state for themes and user settings, which are then consumed by various layout components (like Sidebar and GlobalSearch) and page-specific views (such as HomePage, ChatPage, KanbanPage, and SettingsPage).

    RootLayout
  └── ThemeProvider
      └── SettingsProvider
          ├── DynamicFavicon
          ├── OnboardingWizard
          ├── LiveStreamWidget
          ├── Sidebar
          │   ├── NavLinks
          │   ├── ThemeToggle
          │   ├── MobileSidebar
          │   └── GlobalSearch
          └── <main> (page content)

  3. Understand the relationship between ClawPort and OpenClaw

    main

    ClawPort and OpenClaw operate in a layered architecture. OpenClaw is the runtime layer responsible for agent execution, the gateway API, cron scheduling, memory management, and the CLI. ClawPort is the UI layer responsible for the dashboard, visualization, chat interface, and settings.

    ClawPort does not execute agents directly. Instead, it reads workspace data from disk, calls OpenClaw gateway HTTP endpoints, and invokes the openclaw CLI to present information and relay user actions.

  4. Reference agent registry workspace path

    main

    The user's agent registry override is located at a specific path relative to the workspace. This path is used by lib/agents-registry.ts to locate the configuration file.

    Path Pattern: $WORKSPACE_PATH/clawport/agents.json

  5. Override agent emojis and profile images

    main

    ClawPort allows per-agent visual customization via the agentOverrides setting. This is managed using setAgentOverride(agentId, override) and clearAgentOverride(agentId).

    AgentOverride Structure:

    • emoji: A custom string emoji to replace the agent's default.
    • profileImage: A base64 JPEG data URL (maximum 200px dimension).

    Key Behaviors:

    • Shallow Merging: Calling setAgentOverride merges the new properties into the existing override for that agent rather than replacing the entire object.
    • Resolution: The getAgentDisplay(agent) function is used by components (like AgentAvatar) to resolve the final visual state by checking the override first, then falling back to the agent's default properties.
    • Global Toggle: The emojiOnly setting in ClawPortSettings can be used globally to force all agents to show only their emoji without a colored background circle.
    // Apply a custom emoji to a specific agent
setAgentOverride('agent-123', { emoji: '🤖' });

// Remove all overrides for an agent
clearAgentOverride('agent-123');

  6. How ClawPort discovers agents

    main

    ClawPort uses two methods to populate the dashboard with agents:

    1. Auto-Discovery (Default)

    ClawPort automatically scans $WORKSPACE_PATH/agents/ for subdirectories containing a SOUL.md file.

    • ID: Derived from the directory name.
    • Name: Extracted from the first # Heading in SOUL.md (or directory name as fallback).
    • Role/Title: Extracted from Role: or Title: lines in SOUL.md (or "Agent" as default).
    • Orchestrator: If $WORKSPACE_PATH/SOUL.md exists, it acts as the root orchestrator.

    2. Custom Registry (Override)

    To gain full control over agent metadata (colors, emojis, hierarchy, tools), you can bypass auto-discovery by creating a custom registry file at: $WORKSPACE_PATH/clawport/agents.json

    If this file exists and is valid JSON, ClawPort will use it exclusively instead of scanning the filesystem.

  7. How ClawPort themes work

    main

    The theming system relies on three layers:

    1. data-theme attribute: Themes are scoped via the [data-theme="<id>"] attribute on the <html> element. The dark theme is also applied to :root by default.
    2. CSS Custom Properties: All visual elements (colors, shadows, radius, etc.) are controlled via CSS variables. Components consume these via var(--token-name) rather than direct Tailwind color classes.
    3. ThemeProvider: A React context (app/providers.tsx) manages the active theme. It persists the selection to localStorage under the key clawport-theme. For the system theme, it resolves to either dark or light based on the user's OS settings using window.matchMedia.
    import { useTheme } from '@/app/providers';

const { theme, setTheme } = useTheme();
// theme is the ThemeId ('dark', 'glass', etc.)
// setTheme('light') applies immediately

  8. How ClawPort reads workspace data

    main

    ClawPort uses the $WORKSPACE_PATH environment variable to discover and read agent and operational data directly from the OpenClaw workspace on disk. The following mapping defines how ClawPort consumes workspace files:

    DataSourceClawPort usage
    Agents$WORKSPACE_PATH/agents/*/SOUL.mdAgent discovery, org map, profiles
    Root agent$WORKSPACE_PATH/SOUL.md, IDENTITY.mdRoot orchestrator node
    Memory$WORKSPACE_PATH/memory/Memory browser
    Cron runs$WORKSPACE_PATH/cron-runs/Cost dashboard, activity logs
    Agent registry override$WORKSPACE_PATH/clawport/agents.jsonCustom agent names, colors, hierarchy
    Pipeline config$WORKSPACE_PATH/clawport/pipelines.jsonCron pipeline DAG
    OpenClaw config$WORKSPACE_PATH/../openclaw.jsonMemory status, gateway settings

  9. Configure the operator name and its system impact

    main

    The operatorName setting identifies the human user. It is set via setOperatorName(name: string | null).

    System Flow:

    1. Storage: The name is stored in settings.operatorName.
    2. UI: The name (or initials) is displayed in the sidebar.
    3. AI Context: When sending a message to /api/chat/[id], the operator name is included in the request payload and injected into the system prompt, allowing agents to address the user by name.
    // Set the operator name
setOperatorName('John Doe');

  10. How ClawPort Agent Discovery Works

    main

    ClawPort automatically discovers agents by scanning your OpenClaw workspace. No manual configuration file is required for basic discovery.

    Scanned Files

    ClawPort looks for .md files in the following locations:

    • $WORKSPACE_PATH/SOUL.md (Root orchestrator)
    • $WORKSPACE_PATH/IDENTITY.md (Root agent name and emoji)
    • agents/<name>/SOUL.md (Top-level agents)
    • agents/<name>/sub-agents/*.md (Flat sub-agent files)
    • agents/<name>/members/*.md (Team member files)
    • agents/<name>/<subdir>/SOUL.md (Nested subdirectory agents)

    Ignored Files

    • Directories without a SOUL.md file (e.g., briefs/, data files).
    • Non-.md files located in sub-agents/ or members/ directories.

    Customization

    For full control over agent names, colors, hierarchy, and tools, you can create a custom configuration file at $WORKSPACE_PATH/clawport/agents.json.

  11. Install ClawPort from Source

    main

    If you prefer to run ClawPort from a local clone rather than the global npm package, use the following workflow:

    git clone https://github.com/JohnRiceML/clawport-ui.git
cd clawport-ui
npm install
npm run setup
npm run dev

  12. Change the default accent color globally

    main

    To change the default accent color for all themes, you must update the --accent and --accent-fill values in app/globals.css.

    1. Update the :root and [data-theme="dark"] blocks.
    2. Update specific theme blocks like [data-theme="glass"], [data-theme="color"], and the [data-theme="system"] media query.
    3. Note: The light theme uses a different accent color (#B8860B) for contrast; ensure your new value works well on white backgrounds.

    Note: This only affects the theme-level default. User-defined custom accent colors in settings take precedence via inline styles.

    :root, [data-theme="dark"] {
  --accent: #3B82F6;                    /* New default: Blue */
  --accent-fill: rgba(59,130,246,0.15); /* Same color at 15% opacity */
}