github.com/chrispyers/openkiwi @main

Navigation

• What is it?
• How Agents Work
• Agent Skills
• Memory System
• Context Compaction
• Multi-Agent Orchestration
• Heartbeats
• Visual Workflow Builder
• Quickstart
• Launch the Services
• Connect to the gateway
• Setup your first model
• Setup your first agent
• Setup messaging
  • WhatsApp
  • Telegram
• Enable tools
• Security: Allowlists
• Use Cases

What is it?

OpenKIWI (Knowledge Integration & Workflow Intelligence) is a secure, multi-channel agentic automation system.

OpenKIWI sits in the same automation space as other tools like Openclaw, but differentiates itself with a security-first design and a streamlined onboarding experience that gets you started in minutes.

It provides a web interface where you can create, configure, and manage any number of AI agents. Each agent can be dynamically bound to either local models (LM Studio, Ollama, etc.) or remote providers (OpenAI, Anthropic, Google, etc.), making it easy to swap models without breaking your workflow.

---

Self-Healing Agent Loop

Agents don't just answer a question and stop. Every task runs through a continuous reasoning loop — the agent plans, executes tools, observes the results, self-corrects on failure, and iterates until the goal is reached. Read more →

Visual Workflow Builder

Chain tools together into automated pipelines using a drag-and-drop node editor — no code required. Read more →

Security by Default

Every component runs inside isolated Docker containers. Agents only see the files and tools you explicitly grant. OpenKIWI is built to be enterprise-ready, with a clear and auditable security posture.

Multi-Model, Agent-First

Switch providers or run local models (LM Studio, Ollama, etc.) without touching your workflow logic.

Multi-Channel Interactivity

Agents can be seamlessly connected to WhatsApp and Telegram. This allows users to directly text their agents from their phones, secured behind strict allowlists.

Rapid Onboarding

Clone the repo, run one command and you're up in about 30 seconds. A few quick settings in the UI and you're running your first agent. The whole process takes about 3 minutes — no 20-minute YouTube tutorial required.

Autonomous Scheduling ("Heartbeats")

Instead of just waiting for user prompts, agents can be configured with cron-based "heartbeats." This enables them to run autonomously in the background to execute workflows.

Agent Skills

Extend what agents can do without touching code. Install community-built skills from skillsmp.com/search or author your own. Skills are discovered automatically at startup and activated by the agent when the task calls for it. Read more →

Extensible Tooling Ecosystem

Agents are equipped with a powerful suite of explicitly granted tools, allowing them to browse the internet, read and write files securely, analyze images, interface with external APIs like GitHub and Google Tasks, and query semantic vector stores via Qdrant for long-term memory and RAG capabilities.

---

In short, OpenKIWI transforms raw language models into secure, schedule-driven assistants that seamlessly integrate into the platforms you already use.

How Agents Work

Most AI chat tools work in a single shot: you ask a question, the model generates a response, done. OpenKIWI agents work differently.

Every task runs through a self-healing agent loop — the same architecture behind tools like Claude Code. Instead of a one-shot response, the agent:

1. Receives the task or prompt
2. Plans an approach and selects the right tools
3. Executes — reads files, runs searches, calls APIs, writes code
4. Observes the result of each action
5. Self-corrects — if something fails or the result is unexpected, the agent adjusts its plan and tries again
6. Iterates through as many steps as needed
7. Completes only when the goal is actually achieved

This means agents can handle genuinely complex, multi-step tasks — ones where the path to the answer isn't known upfront. They recover from errors automatically, adapt to unexpected output, and keep working until they're done.

The loop is fully transparent in the UI: every tool call, file read, search query, and self-correction is shown in real time as it happens.

Visual Workflow Builder

OpenKIWI includes a node-based visual workflow editor inspired by tools like n8n. You can build automated pipelines by connecting tools together — without writing any code.

Each workflow is a directed graph of steps. Drag in a tool node, configure its inputs, connect it to the next step, and run. Workflows can be triggered manually, scheduled via a heartbeat, or called by an agent mid-task.

Workflows are managed from the Workflows page in the sidebar. You can create, rename, delete, and open workflows from there.

Agent Skills

Agent Skills are packages of instructions, scripts, and resources that agents can discover and activate on demand. A skill can encode anything from domain expertise to a complete multi-step research workflow — the agent loads it when the task calls for it, and ignores it otherwise.

Install a skill by using the Install Skill button on the Skills page or dropping a folder into the skills/ directory. Skills installed from the community marketplace at skillsmp.com/search work out of the box with no configuration required.

Skills can be installed directly from the UI via drag-and-drop:

Once installed, agents activate skills automatically during chat when the task matches:

For full details on the skill format, authoring your own skills, and advanced options, see docs/AGENT_SKILLS.md.

Context Compaction

Agents automatically manage their context window during long tasks. When the conversation history approaches the model's token limit, the system summarizes older messages to free up space — allowing the agent to continue working without stopping or losing track of progress. This works with any LLM provider and adapts to the model's context size. Read more

Memory System

Each agent has persistent long-term memory stored as a human-readable Markdown file (MEMORY.md). Agents automatically save important facts — user preferences, project context, past decisions — and recall them in future sessions using hybrid search that combines vector embeddings with full-text keyword search. Memory can also be shared across agents via SHARED_MEMORY.md. Read more

Multi-Agent Orchestration

Agents can delegate tasks to other agents for parallel execution. A coordinator agent breaks a complex problem into subtasks, dispatches each to a specialized agent, and synthesizes the results — similar to how Claude Code's Agent Teams work. Agents share data in real time via a shared scratchpad. Read more

Local Development

1. Clone this repo
2. Install dependencies with npm install
3. Run npm run dev

Quickstart

1. Launch the Services

• Clone this repo
• cd to the directory where you cloned the repo
  • You should see a docker-compose.yml file in this directory
• Choose one of the following:
• Run docker compose up --build to run in isolation in docker containers (foreground)
• Run docker compose up --build -d to run in isolation in docker containers (background)

• Run npm install and npm run dev to run the services in the foreground in a development environment

• If this is your first time running OpenKIWI and you just want to check things out, I recommend running docker compose up --build

2. Connect to the gateway

• Copy the gateway token from the logs:

• Go to http://localhost:3000 and click on Gateway

• Enter your token and click Connect
• If done correctly, you will see GATEWAY CONNECTED at the top of the page.

3. Setup your first model

• Click on "Models" in the side bar
• Click on "Add Model"
• Select your provider
• For remote providers like OpenAI, Anthropic, Google, etc. you will need to enter your API key
• For local models like LM Studio, Ollama, etc. you will need to enter the IP address of your server
• Press the "Scan" button

• You will see a list of models
• Select your desired model
• Optionally enter a description
• Click "Save Model"

• You have now added your first model

4. Setup your first agent

• Click on "Agents" in the side bar
• Click on "Add Agent"
• Enter the agent's name
• Select the agent's persona
• The persona will shape the agent's behaviour and the way it interacts with you and other agents
• Click "Save Agent"

• You have now added your first agent
• Here you can set scheduled tasks
• You can view your agent's persona and make adjustments if desired

5. (optional) Setup Messaging

WhatsApp

Connect WhatsApp so you can message your agents from your phone.

Pairing

1. Go to the Settings page and click the WhatsApp tab
2. Scan the QR code with your phone (WhatsApp > Linked Devices > Link a Device)
3. Once paired, the status will show as connected
4. Start messaging agents from your phone

(Recommended) Restrict access

By default, any WhatsApp number that messages the linked account can interact with agents. Add an allowlist to restrict access:

WHATSAPP_ALLOW_LIST=447958673279, 1234567890

Accepts comma-separated phone numbers (digits only, no + prefix required). Numbers not on the list are silently ignored. LID-based JIDs (used by some WhatsApp versions) are automatically resolved to phone numbers for matching.

Heartbeat delivery

Agents can send scheduled heartbeat messages to WhatsApp. Add a channel to the agent's config.json:

{
  "heartbeat": {
    "enabled": true,
    "schedule": "0 9 * * 1",
    "channels": [
      { "type": "whatsapp", "jid": "447958673279@s.whatsapp.net" }
    ]
  }
}

The jid is the recipient's phone number followed by @s.whatsapp.net. WhatsApp must be connected for delivery to work — if disconnected, the channel is skipped and a warning is logged.

Telegram

Connect a Telegram bot so you can message your agents from Telegram.

Create a bot

1. Open Telegram and message @BotFather
2. Send /newbot and follow the prompts to name your bot
3. Copy the bot token BotFather gives you

Configure environment

Add to your .env file:

TELEGRAM_BOT_TOKEN=your_bot_token_here

(Recommended) Restrict access

By default, anyone who finds your bot can message it. Add an allowlist to restrict access to specific users:

TELEGRAM_ALLOW_LIST=123456789, @yourusername

Accepts comma-separated Telegram user IDs and/or @usernames. To find your user ID, message @userinfobot on Telegram.

Messaging agents

• Send any message to your bot — it goes to the default agent
• Mention a specific agent by name: @Oracle what happened this week?
• Use /agents to list all available agents

Heartbeat delivery

Agents can send scheduled heartbeat messages to Telegram. Add a channel to the agent's config.json:

{
  "heartbeat": {
    "enabled": true,
    "schedule": "0 16 * * 5",
    "channels": [
      { "type": "telegram", "chatId": "123456789" }
    ]
  }
}

The chatId is the Telegram chat where messages will be delivered (usually your user ID).

6. (optional) Enable tools

OpenKIWI ships with several built-in tools that extend your agents' capabilities. Enable them in the Settings page:

Tool	Description	Docs
Filesystem	Read/write workspace files	Built-in
Vision	Analyse images	Built-in
Web Browser	Browse and extract web content	Built-in
GitHub	Read/write files in GitHub repos	tools/github/
Google Tasks	Manage Google Tasks lists and items	tools/google_tasks/
Qdrant	Semantic search across vector stores	tools/qdrant/

See tools/README.md for the full list and how to create your own.

Heartbeats

Heartbeats let agents run autonomously on a schedule — no user prompt req