DEV Community: chowyu

AIClaw Now Returns Tool Output Attachments You Can Actually Download

chowyu — Sun, 28 Jun 2026 11:48:42 +0000

AIClaw already let agents run tools, generate files, and continue working across steps. The weak point was the handoff back to the user: a tool might create a report, image, or data file, but the final answer did not always make that output obvious or directly downloadable.

Recent AIClaw changes tightened that workflow. Tool-generated files are now collected, deduplicated, exposed in API responses and streaming completion chunks, linked into the final assistant message, and rendered by the chat UI through stable /public/files/<uuid> download URLs.

This is not a cosmetic change. It closes the loop between tool execution and user-visible results.

The problem

In a tool-using agent system, “I created the file” is not enough. Users need to:

know that a file was produced
see which final answer it belongs to
download it without searching through logs
keep that file associated with the conversation history

Without that, generated artifacts are easy to lose, especially when an agent uses multiple tools or delegates work to sub-agents.

What changed in AIClaw

The recent attachment work is visible across the backend and frontend.

On the execution side, AIClaw now:

collects file outputs returned by tools
scans sandbox directories for newly created files when a tool does not explicitly return a file result
pulls generated files back out of sub_agent results
deduplicates attachments before the final response is stored or streamed

You can see that in the tool execution path:

The final assistant response now appends an attachment section with Markdown links such as:

Attachment List:
- [report.csv](/public/files/<uuid>)
- [chart.png](/public/files/<uuid>)

In the current Chinese codebase revision, that section is rendered as 附件列表 in the saved final content.

The response payload also includes files directly:

blocking chat responses now return files
streaming done chunks now include files

That path is visible in:

On the frontend, the chat view turns those file objects into clickable downloads through /public/files/${file.uuid}:

/Users/yu/go/src/github.com/chowyu12/aiclaw/web/src/views/chat/Index.vue

Why this matters in practice

This feature is useful anywhere an AIClaw agent produces artifacts instead of pure text.

Examples:

A code_interpreter task generates a CSV and a PNG chart.
A browser automation flow saves a screenshot or extracted document.
A sub-agent writes a research summary file and passes it back to the parent run.
A shell command creates a log bundle or transformed dataset in the sandbox.

Before this improvement, users could still end up asking, “Where did the file go?”

Now the expected workflow is much cleaner:

The tool runs.
AIClaw captures the output files.
The final answer includes explicit download links.
The API and streamed completion both carry the file metadata.
The UI renders the attachments as part of the conversation result.

That means AIClaw behaves more like a practical work system and less like a text-only chatbot that happens to call tools.

A small detail that matters: sub-agent outputs

One useful part of this change is that file outputs are not limited to the top-level agent.

The executor now extracts file references from sub_agent results and folds them back into the parent response. That matters because many real AIClaw workflows split research, scraping, or data prep into delegated tasks. If child artifacts disappear at the parent boundary, the system feels unreliable.

Bringing those files back into the parent answer makes nested agent execution much easier to trust.

Another practical improvement: better streaming behavior

The same change set also adds SSE ping support in chat streaming handlers. That is separate from attachments, but it helps long-running tool workflows stay alive while the agent is still working.

For attachment-heavy runs, that pairing is useful:

streaming stays active during long tool work
the final done chunk can carry the generated files

Why I picked this feature

This is a good example of AIClaw’s local-first, tool-oriented design philosophy. The platform is not just trying to produce a nice paragraph. It is trying to complete work and return the artifacts that work produces.

Generated files are often the real output. Making them first-class in the response path is the right move.

If you are building with AIClaw, this is the kind of feature that improves daily usability more than another abstract prompt tweak.

AIClaw Separates Persistent Memory From Session Search

chowyu — Thu, 25 Jun 2026 11:55:44 +0000

One of the fastest ways to make an agent messy is to treat every kind of memory as the same thing.

User preferences, project conventions, environment facts, old debugging sessions, and last week's conversation snippets do not belong in one undifferentiated bucket. AIClaw's current design avoids that by splitting long-term memory into two explicit mechanisms:

persistent memory for durable facts
session search for historical conversation recall

That split is worth looking at because it solves real operating problems for self-hosted agents.

The design goal

There are three failure modes that show up quickly in agent systems:

everything is stuffed into the prompt, so context grows until it becomes noisy and expensive
everything is hidden in a database blob, so operators cannot inspect or edit it cleanly
old conversations are either forgotten completely or reloaded too aggressively

AIClaw addresses those problems with two different tools that do two different jobs.

Persistent memory is stored as editable files

The repository documents persistent memory in README.md and implements it in internal/tools/memorytool/memory.go.

Instead of hiding long-term memory in opaque storage, AIClaw keeps it in plain text files:

MEMORY.md for durable agent notes, environment facts, and conventions
USER.md for user preferences and communication style

This is a practical choice. Operators can inspect, review, and edit those files directly when needed, which is much easier than debugging memory behavior through serialized blobs.

The current session gets a frozen snapshot

AIClaw does not continuously mutate the active system prompt every time memory changes.

At session start, it loads a snapshot of MEMORY.md and USER.md and injects that into the prompt. The loader in internal/agent/prompt_loaders.go calls memorytool.LoadSnapshot(...) and joins the resulting memory blocks into the runtime prompt.

That means memory writes during a session affect future sessions, not the already-running one.

This is a strong constraint, and I think it is the right one. It keeps prompt behavior stable inside a run and avoids a hard-to-debug class of issues where the agent silently changes its own instructions halfway through execution.

Memory growth is bounded

The memory tool also has explicit limits:

MEMORY.md is capped at 2200 characters
USER.md is capped at 1375 characters

When usage gets high enough, AIClaw switches the injected snapshot into an index mode. Instead of pushing full entry bodies into the prompt, it injects a compact list of entry IDs, tags, and short summaries.

If the agent later needs one of those full entries, it can fetch it explicitly with memory(action=recall, ids=[...]).

That is a smart tradeoff. Long-term memory stays available, but the prompt does not have to pay the full token cost every time.

Memory writes are treated as a security surface

This part is easy to miss, but important.

The memory tool scans content before saving it. The implementation rejects suspicious injection-style patterns and invisible Unicode characters that could be used to smuggle prompt instructions into future sessions.

That makes sense because memory is not just stored data in AIClaw. It is future system-prompt material.

Session search solves a different problem

Persistent memory is for stable facts. Historical conversation lookup is different.

Sometimes the agent does not need a durable note. It needs to answer questions like:

What did we discuss in the earlier deployment thread?
Which error message showed up last time?
What did the user say about this workflow in a prior session?

That is what internal/tools/sessionsearch/session_search.go is for.

The tool has two modes:

no query: return recent conversations with previews
query provided: search prior messages and return matching snippets

SQLite gets FTS5, other databases still work

The search implementation in internal/store/gormstore/fts.go adds a practical optimization.

When AIClaw runs on SQLite, it initializes an FTS5 virtual table plus triggers to keep the search index synchronized with new and deleted messages. It also backfills existing data on startup.

When FTS5 is unavailable, AIClaw falls back to a SQL LIKE search path.

That is exactly the kind of graceful degradation I want in a local-first system. SQLite gets a fast search path, but the feature does not disappear on other databases.

Why the split matters operationally

This is the real value of the feature:

durable facts go into editable memory files
old conversation details stay in searchable archives
the active prompt remains more compact
and both behaviors are explicit enough to inspect

That is better than trying to solve all recall problems with one giant "memory" abstraction.

A practical workflow

If I were operating AIClaw day to day, I would use it like this:

Save stable rules, preferences, and environment facts with the memory tool.
Use session_search when you need to retrieve something from older conversations.
Let the snapshot and index-mode design keep the active prompt lean.

That is a more durable model for long-running agents than simply loading more chat history and hoping the model figures out what still matters.

AIClaw's memory layer is not flashy, but it is disciplined. For self-hosted agent systems, that discipline is usually what keeps advanced features usable after the first demo.

How AIClaw Extends Agents with Custom Tools and MCP Servers

chowyu — Tue, 23 Jun 2026 11:54:53 +0000

Most agent demos look flexible until you need them to talk to your own systems.

That is where AIClaw takes a practical route. The project ships with a broad built-in toolset, but it also lets you extend agents through custom HTTP tools, script tools, and MCP servers without changing the core runtime.

This is not a new feature announcement. It is an existing part of the current repository that is worth a deeper look because it changes what an AIClaw deployment can actually do in day-to-day work.

The problem: built-ins are not enough

Built-in tools cover the common cases well: files, shell, browser automation, web search, web fetch, memory, session search, scheduled jobs, code interpretation, and sub-agents.

But real deployments usually need one more layer:

Call an internal HTTP API.
Wrap a small script around an existing operational workflow.
Reuse external MCP tools from another server process.

Without that layer, the agent can reason, but it cannot reach the systems that matter in your environment.

AIClaw's extension model

The current README describes AIClaw's tool system as a combination of:

built-in tools
custom HTTP tools
custom command tools
MCP server tools
skill-defined tools

In the runtime, those paths are normalized into the same execution flow.

internal/agent/tool.go builds tracked tools from the configured definitions. Built-ins get their native handlers, HTTP tools are wrapped with NewHTTPHandler, command tools use NewCommandHandler, script tools use NewScriptHandler, and MCP tools are loaded from connected servers before the model call.

That matters because extension points do not become second-class behavior. They still participate in the same execution loop, step tracking, and agent prompt assembly.

Custom tools from the web console

The current tool management UI gives you a practical authoring flow instead of requiring hand-written runtime config.

On the Tools page you can:

Create a tool with a name, description, timeout, and enabled state.
Choose a handler type.
Define the function schema that the model will see.
Bind the tool to agents that should be allowed to call it.

The form currently exposes two handler types directly in the UI:

HTTP Callback
Script

For HTTP tools, AIClaw lets you define a request URL and method, with {param_name} placeholders that are substituted from model-supplied arguments at runtime.

For script tools, the form supports:

Python
JavaScript
Shell
Go

The same page also lets you describe the function in a structured way or switch to raw JSON mode for the full function definition.

That is a useful design choice. It keeps the operational handler config and the model-visible function schema separate, which makes tools easier to tune without rewriting everything.

MCP servers as first-class runtime inputs

AIClaw also has a dedicated MCP management page.

The current MCP settings flow supports:

stdio transport
sse transport
endpoint configuration
argument lists
enabled or disabled state

The runtime API behind that page is straightforward: GET /api/v1/runtime/mcp reads the workspace MCP list, and PUT /api/v1/runtime/mcp replaces it.

The runtime side is more interesting.

internal/tools/mcp/client.go connects to each enabled MCP server, initializes the client, lists available tools, and then exposes them to the agent executor. In internal/agent/executor.go, MCP tools are connected before execution so they can be merged into the available tool set for the request.

This gives AIClaw two useful extension paths:

create narrow custom tools inside AIClaw when the integration is simple
mount an external MCP server when the tool suite already exists elsewhere

Safety and operability details that matter

The implementation is more pragmatic than flashy, and that is a good thing.

A few concrete examples from the current codebase:

HTTP tool calls use a shared HTTP client with connection pooling instead of rebuilding a client on every invocation.
Command tools apply additional safety checks on top of the normal shell safeguards, including blocking patterns like outbound shell access and risky recursive deletes.
Tool calls are wrapped as tracked steps, so custom and MCP-backed calls show up in the same execution timeline as built-ins.
The MCP manager is reused at the executor level instead of being torn down after every request.

These are not marketing details. They are the difference between "extensible in theory" and "usable under load".

A practical workflow

If you want to extend an AIClaw agent today, the workflow is roughly:

Start with the smallest possible integration.
If the system is just one API call, create a custom HTTP tool.
If the integration needs local logic, wrapping, or formatting, use a script tool.
If you already have a larger tool surface implemented elsewhere, register it as an MCP server.
Attach only the needed tools to the target agent.
Inspect the execution log after real runs to verify the tool contract is clear enough for the model.

A good example is an internal support workflow:

one HTTP tool for looking up a ticket by ID
one script tool for normalizing the raw result into a concise summary
one MCP server for a broader internal knowledge or operations toolkit

That combination keeps the default agent prompt small while still giving the agent a path into real systems.

Why this matters

The strongest agent products are not the ones with the longest built-in tool list. They are the ones that let you adapt the tool surface to your own environment without fighting the runtime.

AIClaw's current design gets that mostly right:

built-ins for common work
custom tools for narrow integrations
MCP for external tool ecosystems
shared execution logging so everything stays inspectable

If you are building self-hosted agents, that is the layer that turns a chat UI into an actual operations surface.

Repo: AIClaw on GitHub

AIClaw Adds Configurable Web Search Without Hiding Execution Details

chowyu — Sat, 20 Jun 2026 08:36:03 +0000

Most AI agent products say they can "search the web," but they often collapse several very different behaviors into one checkbox.

In the current AIClaw repository, web search is modeled more explicitly:

some models can use built-in provider-side search
other agents can call an external web_search tool through a configured search engine
both paths are visible in runtime behavior instead of being hidden behind vague magic

That separation matters if you run agents in production and want control over cost, provider choice, prompts, and auditability.

What changed in AIClaw

Recent AIClaw changes added a full search engine configuration surface and the agent-side wiring needed to use it:

a new Search Engine page in the web console
persisted search engine configs in the backend
external search support for Tavily, SerpAPI, and Aliyun IQS
agent settings for builtin versus external web search mode
runtime handling that enables model-native search only when that mode is selected
a follow-up UI fix that turns web search on automatically when an external engine is chosen

This is not just a README claim. The repository now includes:

internal/handler/search_engine.go for CRUD and test endpoints
internal/tools/websearch/search.go for provider-specific search execution
web/src/views/search-engine/Index.vue for the console UI
web/src/views/agent/Form.vue for per-agent mode and engine selection
tests covering built-in and external search behavior

Why two search modes are better than one

AIClaw now documents two distinct modes in README.md:

built-in mode: AIClaw sets extra_body: {"enable_search": true} for models that support provider-native search
external mode: AIClaw exposes a web_search tool and routes calls through a saved search engine config

That design solves a real operational problem.

Built-in model search is convenient when the provider already supports it well. In AIClaw, the prompt layer explicitly tells the model that recent and time-sensitive questions can use built-in search. The runtime also records a web_search execution step that shows the request configuration used for that model call.

External search is different. Sometimes you do not want your search behavior tied to one model vendor. Sometimes you want to standardize on a search provider across multiple model backends. Sometimes you want to rotate providers, test them independently, or keep search visible as a normal tool call with structured input and output.

AIClaw supports that split instead of forcing one compromise.

How the flow works

The user workflow is straightforward:

Open the Search Engine page in the AIClaw admin console.
Create one or more search configs.
Pick the provider: Tavily, SerpAPI, or Aliyun IQS.
Save the API key and optional base URL.
Test the config before using it live.
Open an agent.
Enable web search.
Choose external mode if you want tool-based search.
Select one enabled search engine for that agent.

On the backend, AIClaw validates that external mode is only accepted when a real enabled search engine is selected. That check lives in validateExternalWebSearch inside internal/handler/agent.go.

The frontend follow-up fix is also important. In web/src/views/agent/Form.vue, selecting external mode now auto-selects the first enabled engine when possible, and selecting an engine automatically enables web search. That sounds small, but it removes a common configuration footgun: "I picked an engine, why is search still off?"

Provider behavior is implemented, not hand-waved

AIClaw does not treat external search as a generic proxy blob. The repository includes explicit provider logic:

Tavily uses https://api.tavily.com/search
SerpAPI uses https://serpapi.com/search.json
Aliyun IQS uses https://cloud-iqs.aliyuncs.com/search/unified

The tool normalizes limits, validates config state, trims oversized snippets, and returns structured results with title, URL, and snippet fields.

That means the agent can use web results in a predictable format regardless of provider, while operators still choose the engine that fits their environment.

The observability part is the real strength

My favorite part is that AIClaw keeps search behavior observable.

For built-in search, the runtime records that model-native search was enabled and stores the request configuration in a web_search step.

For external search, the agent uses the regular web_search tool path, so tool input, output, duration, and errors stay visible in chat progress and execution logs.

This fits the broader AIClaw design direction: runtime plan state, generated files, execution steps, memory, and now search behavior are treated as first-class runtime objects instead of hidden implementation details.

If you are operating agents for real work, that is a better tradeoff than a black-box "browse the web" toggle.

A practical example

Imagine two agents:

a news-monitoring agent using a model with strong built-in search support
a research or compliance agent that must use a specific external search provider

In AIClaw, those do not need the same search path.

The first agent can stay in built-in mode for a tighter provider-integrated experience.

The second agent can switch to external mode, bind to a chosen engine, and keep the search action visible as a tool call with inspectable results.

That is a more production-friendly model than pretending every search use case is identical.

Why this feature stood out

I picked this topic because it is a concrete feature with recent implementation depth across backend, runtime, tests, and UI:

feature commit: configurable search engines
follow-up fix: external search becomes active as soon as an engine is selected
documented behavior in the README
explicit tests for built-in versus external execution

That combination makes it a good example of how AIClaw is evolving: not just adding another capability, but making the capability configurable and inspectable.

AIClaw is open source and self-hosted, so these details matter. When you control the stack, you also need to control how the agent reaches the outside world.

How AIClaw Compresses Long Agent Conversations Without Losing the Important Parts

chowyu — Fri, 19 Jun 2026 08:57:54 +0000

Long-running agent sessions eventually hit the same problem: the model keeps accumulating chat history, tool outputs, intermediate decisions, and execution traces until the prompt becomes expensive or unstable. AIClaw has a built-in answer for that problem. It does not simply drop old messages. It compresses the middle of the conversation into a structured summary and keeps the parts that still matter for the next step.

This is not a new release post. It is a deeper look at one existing AIClaw runtime feature: context compression.

The Problem

AIClaw is designed for tool-using work, not short chatbot replies. A single task can include:

multiple rounds of shell or browser tool calls
long tool outputs
plan-state progress updates
follow-up fixes after the first attempt
sub-agent results flowing back into the parent run

That is useful context, but it also means the prompt grows fast. If the runtime sends everything back to the model forever, cost increases and the model starts paying attention to the wrong parts of the history.

The README describes this capability briefly as:

Runtime compression: Long middle context can be summarized during execution.

The implementation behind that line is more specific than it sounds.

When AIClaw Decides To Compress

The decision lives in internal/agent/context_compressor.go and is wired into the main execution loop in internal/agent/run.go.

Before each LLM round, AIClaw checks whether the current prompt is too large relative to the model context window.

The current defaults are straightforward:

compress when prompt usage reaches 50% of the model context window
keep the system message at the head
keep at least the latest 20 messages at the tail
require at least 5 middle messages before compression is worth doing

If the model provider reports real prompt-token usage, AIClaw uses that. Otherwise it falls back to an internal estimate. That matters because the trigger is based on actual prompt pressure, not just message count.

What Gets Compressed, And What Stays Intact

AIClaw uses a four-phase flow.

1. Prune old tool output first

Before asking the model to summarize, AIClaw trims older tool messages outside the protected tail window. Tool outputs in that middle region are truncated to 200 runes. That keeps huge logs from dominating the summary prompt.

This is an important design choice. The runtime does not try to summarize raw noise at full size first. It reduces obviously low-value bulk before paying for the summarization call.

2. Protect the head and the tail

The compressor preserves:

the head of the conversation, especially the system prompt
the latest tail of the conversation, where the current working state lives

The part in the middle becomes the candidate for compression.

3. Ask an LLM for a structured summary

Instead of generating a vague paragraph, AIClaw asks for a strict template with sections like:

Goal
Constraints And Preferences
Progress
Key Decisions
Relevant Files
Next Steps
Critical Context

This is a practical choice for agent continuity. The summary is meant to preserve execution state, not produce pretty prose.

4. Rebuild the conversation with a summary message

After summarization, AIClaw inserts a [Context Compression Summary] message and appends a note to the system prompt that earlier conversation has been compressed.

The result is smaller than the original history, but still carries forward the task objective, decisions, blockers, touched files, and next action.

Tool Calls Are Not Split Apart

A subtle detail in the implementation is that AIClaw does not cut through an assistant/tool-call group. The compressor aligns the preserved tail boundary backward so a tool call and its tool results stay together.

That matters because broken tool-call sequences are confusing for the next model round. If an assistant message says it called a tool but the corresponding tool results are missing from the preserved tail, the reconstructed context becomes misleading.

There are tests for this behavior in internal/agent/context_compressor_test.go.

Compression Is Iterative, Not One-Shot

AIClaw also keeps the previous compression summary in memory during the active run. On the next compression pass, it does not start from zero. It sends:

the previous summary
the newly accumulated conversation slice

Then it asks the model to merge them into an updated structured summary.

This makes repeated compression cheaper and more stable in long tasks. Instead of re-summarizing the entire old middle history every time, AIClaw incrementally rolls forward the important state.

Which Model Handles Compression

The main execution loop prefers the agent's FastModelName for compression when one is configured; otherwise it falls back to the primary model.

That is a good default for a local-first agent platform:

the expensive or premium model stays focused on the real task
the cheaper or faster model can handle summarization work
prompt size stays under control during long sessions

A Practical Example

Imagine a debugging session where an AIClaw agent:

reads several Go files
runs tests
inspects logs
edits code
reruns tests
asks a sub-agent to inspect a failing subsystem
returns to the parent run for the final fix

Without compression, the conversation history gradually becomes a pile of stale tool output. With compression, AIClaw can keep the current tail intact while rolling earlier work into a structured checkpoint that still remembers:

which files were already inspected
which commands succeeded or failed
what the user asked for
which constraints matter
what remains unresolved

That is the difference between “shorter prompt” and “runtime continuity.”

Why This Feature Matters

AIClaw is opinionated about execution state. It already treats plan state, generated files, execution steps, memory, and conversation history as first-class runtime data. Context compression fits the same design philosophy.

The goal is not to make the transcript prettier. The goal is to keep an agent useful after a long stretch of real work.

If you are building agents that mostly answer in one turn, this feature is easy to ignore. If you are building agents that browse, edit, run commands, and recover from failure across many rounds, it becomes part of the reliability story.

AIClaw keeps that logic in the runtime rather than pushing the entire burden onto prompt engineering.

Where To Look In The Code

internal/agent/context_compressor.go: compression thresholds, protected windows, summary prompt, iterative summary logic
internal/agent/run.go: where compression is triggered in the execution loop
internal/agent/context_compressor_test.go: tests for summary injection, iterative updates, tool-group preservation, and duplicate-note prevention
README.md: product-level runtime compression description

AIClaw is open source, self-hosted, and built for agents that do more than chat. Context compression is one of the small runtime details that makes that practical over longer sessions.

How AIClaw Splits Main and Fast Models for Sub-Agent Work

chowyu — Thu, 18 Jun 2026 11:04:09 +0000

AIClaw is not just a chat wrapper around one model. In the current repository, it lets you configure multiple providers, choose a primary model per agent, and optionally assign a separate fast model for lightweight sub-agent work.

That matters because real agent runs are uneven. Some steps need a stronger model for planning or synthesis. Other steps are small delegated tasks: inspect a few files, try a shell command, summarize one branch of research, or explore a URL. Running every delegated step on the same expensive model is the simple design, but usually not the practical one.

The Problem

When an agent can call sub_agent, the main task and the delegated task often have different cost and latency requirements.

The parent agent may need the best reasoning model you have.
The child task may only need a cheaper and faster model.
You still want both to stay inside the same agent definition and provider setup.

AIClaw addresses that by separating:

the primary model used by the agent, and
an optional fast model reserved for lightweight sub-agent execution.

The repository states this directly in the README:

Each provider can define its base URL, API key, and model list. Agents choose a provider model and can optionally define a fast model for lightweight sub-agent tasks.

How The Provider Layer Is Structured

In the current codebase, AIClaw supports multiple provider types, including:

OpenAI
OpenAI-compatible APIs
Qwen
Kimi / Moonshot
OpenRouter
Claude
Gemini

Those provider definitions live in the backend model layer, and each provider stores:

a name
a provider type
a base URL
an API key
a model list

This is not a hardcoded single-vendor path. It is meant to let one deployment route different agents through different model backends while preserving a unified agent workflow.

What The Web Console Exposes

The admin console has a dedicated Providers page for managing model backends, and the Agent form consumes those provider definitions.

Two parts of the UI are especially useful here:

The Providers page can fetch remote model lists from the configured provider endpoint.
The Agent form lets you choose both a primary model and an optional fast model from the same provider.

The current provider UI merges remote and local model lists, and the agent editor exposes:

主模型 / main model
快速模型 / fast model

The tooltip for the fast model is explicit: it is the lightweight model used when a sub-agent is invoked with model=fast, and if left empty it falls back to the main model.

How The Runtime Uses The Fast Model

The interesting part is that this is not only a configuration field. The runtime actually switches models during delegated execution.

In internal/agent/subagent.go, AIClaw checks the sub-agent model hint before running the delegated task:

if modelHint == "fast" && ec.ag.FastModelName != "" {
    ec.ag.ModelName = ec.ag.FastModelName
}

So the parent agent can keep its primary model, while the child execution swaps to the fast model only for that delegated run.

That keeps the behavior predictable:

no extra provider objects are needed just to optimize sub-agent cost
the parent and child stay within the same agent configuration
the optimization is explicit instead of hidden behind heuristics

Why This Design Is Practical

This design works well for common agent patterns:

Deep reasoning in the parent, fast exploration in children
Expensive final synthesis, cheap parallel research branches
One provider account, multiple model tiers

For example:

Set the main model to gpt-4.1, claude-sonnet, or another stronger general model.
Set the fast model to something like gpt-4o-mini or another lower-latency option from the same provider.
Let delegated sub_agent tasks use model=fast when they are mostly collecting facts or doing narrow execution.

That gives you a more controllable tradeoff than “always use the big model” or “force every agent to be cheap.”

Why I Picked This Feature

Today’s article is not based on a brand-new release commit. Instead, it is a deeper look at an existing AIClaw capability that is already concrete in the repository and easy to miss if you only skim the README.

Recent drafts already covered runtime plan state, execution logs, skills, and channel session continuity. This provider-and-fast-model path is a different product surface and a useful one if you are designing multi-step agents that need cost control without losing structure.

Practical Workflow In AIClaw

A clean setup looks like this:

Add a provider in the Providers page with base URL, API key, and model list.
Fetch remote models from that provider when available.
Create or edit an agent.
Pick the main model for the parent task.
Optionally pick a fast model for lightweight sub-agent tasks.
Let the agent delegate narrow work through sub_agent.

Because AIClaw keeps sub-agent traces visible in the parent timeline, this remains observable instead of becoming a black box.

Closing

Many agent products talk about orchestration, but the useful details are usually in the runtime tradeoffs. AIClaw’s provider setup plus fast-model override is a good example of a small design choice that improves real-world agent operation: better latency and cost control without splitting your workflow across multiple disconnected agents.

If you are building with AIClaw, this is one of the settings worth using early instead of treating every subtask like it deserves your heaviest model.

How AIClaw Keeps Messaging-Channel Chats Stateful with `/new` and `/continue`

chowyu — Wed, 17 Jun 2026 11:54:21 +0000

External chat channels are convenient for AI agents, but they create a session problem fast.

In a web UI, users can see a sidebar of conversations and click back into old work. In WeCom, Feishu, Telegram, or WhatsApp, that structure usually does not exist. You get a thread, a sender, and a stream of incoming messages. If the agent cannot map that external thread back to an internal conversation reliably, the result is either context loss or messy session sprawl.

AIClaw solves that with a channel bridge that does more than relay messages. It binds external thread keys to internal conversation UUIDs, keeps archive-backed history available, and exposes a few small slash commands that let users control session continuity from inside the channel itself.

The practical problem

A channel integration usually has three jobs:

accept inbound messages from an external system
route them to the right agent
send the reply back to the same place

That is enough for basic request/response behavior, but not enough for long-running agent work.

Real usage needs session control:

start a fresh conversation without deleting the old one
continue an earlier conversation from inside the channel
keep one external thread attached to one internal conversation
avoid duplicate conversations when the first inbound messages arrive concurrently

AIClaw handles those cases in its channel runtime instead of pushing the problem into prompts.

The core design: thread binding

When a channel message arrives, AIClaw derives one or more lookup keys from the inbound event. That can include the native thread key, alias keys, or the sender ID as a fallback.

Those keys are stored in a channel_threads mapping table that links:

channel_id
thread_key
conversation_uuid

If a mapping already exists, AIClaw reuses the conversation. If not, it creates a new conversation and binds every relevant lookup key to it.

That sounds simple, but it matters a lot operationally:

the same external thread stays attached to the same internal conversation
aliases can converge onto the same conversation
channel messages become inspectable in the normal AIClaw conversation model

There is also a concurrency guard. AIClaw uses a singleflight gate for the same (channel, thread) key set so that concurrent first messages do not create duplicate conversations or duplicate bindings.

Slash commands that work inside the channel

The interesting part is that AIClaw does not make users jump back to the admin panel just to manage sessions.

It intercepts a few slash commands before the LLM call:

/new
/reset
/continue
/continue N
/archives
/help

That gives channel users lightweight session control with no extra UI.

`/new`

/new creates a fresh conversation for the current channel thread.

If the thread was already bound to an older conversation, AIClaw removes that binding, creates a new conversation record, and rebinds the current thread keys to the new conversation. The older conversation is not deleted. It can still be recovered later.

This is the right behavior for channel-based agent usage because “start over” should not destroy prior work.

`/continue`

/continue lists recent archived conversations for the same agent and channel user. The archive list is scoped by user identity, so one person does not accidentally browse another person’s channel history.

/continue N switches the current thread binding to the selected archived conversation. After that, the next message in the same external thread continues that older context directly.

This is the part I like most: AIClaw turns a plain messaging thread into a recoverable working session without inventing a separate UI surface.

Why archives matter here

The /continue workflow depends on session archives instead of raw database rows alone.

AIClaw periodically regenerates a Markdown archive for a conversation after enough messages accumulate. The archive is generated without another model call and summarizes things such as:

user goals
tool usage counts
recent assistant decisions

Those archive files live under the agent workspace and are sorted by update time when AIClaw builds the /continue list.

That design gives channel users a workable “recent sessions” experience while keeping the implementation cheap and inspectable.

A realistic channel workflow

Here is a simple example:

A WeCom user starts a deployment investigation in one channel thread.
AIClaw binds that thread to a conversation and keeps all later messages in the same context.
After the task is done, the user sends /new to start a clean debugging session without mixing contexts.
A day later, the user wants the original deployment investigation back.
They send /continue, pick the archived session number, and the same thread is rebound to that old conversation.
The next message continues from the earlier session rather than starting cold.

That is a small feature on paper, but it removes a lot of friction from channel-native agent usage.

Why I think this design is good

There are a few design choices worth calling out:

session control is implemented in the runtime, not hidden in prompts
channel threads map onto first-class conversation records
archives are cheap to generate and easy to inspect
user-facing commands are small, memorable, and channel-friendly

Most importantly, the system acknowledges that messaging channels are not just notification sinks. For many teams, they are the primary operating surface.

If an agent platform wants to work there, it needs explicit session semantics, not only transport adapters.

AIClaw’s channel bridge takes that seriously.

AIClaw is an open-source, self-hosted AI agent platform written in Go with a Vue admin console. It supports built-in tools, custom tools, MCP servers, multi-provider models, runtime planning, sub-agents, persistent memory, execution logs, and messaging-channel integrations in one deployable binary.

How AIClaw Keeps Skills Small in Context but Ready at Runtime

chowyu — Mon, 15 Jun 2026 11:54:22 +0000

AIClaw has a lot of moving parts: tools, MCP servers, memory, planning, channels, and reusable Skills. One practical problem shows up quickly when you install many Skills: if every Skill is injected into every prompt in full, context usage grows for no real benefit.

This article is about an existing AIClaw feature, not a new release. The current codebase already uses a two-stage Skill design that keeps prompts smaller while still letting an agent pull in full instructions when they are actually needed.

The problem

In many agent systems, reusable instructions become expensive over time.

You want a library of focused Skills.
You do not want every conversation to pay the token cost for all of them.
You still need the agent to discover what is available and decide when to load more detail.

AIClaw solves that by separating Skill discovery from full Skill loading.

Stage 1: inject the Skill index

The README describes the core idea directly: AIClaw first injects Skill names, descriptions, and paths. That gives the model a compact catalog of what exists without forcing the full SKILL.md content into every request.

In practice, this means an agent can see:

the Skill name
a short description
where the Skill lives

That is enough for planning. If the agent decides a Skill is relevant, it can then read the full instructions.

Stage 2: read full instructions only when needed

The second stage is demand loading. Instead of paying prompt cost up front, AIClaw lets the model fetch the detailed Skill content only when the current task justifies it.

This matters for real usage:

large Skill libraries stay manageable
generic chats stay lightweight
specialized tasks can still pull in deep instructions

The result is a better tradeoff between capability discovery and prompt size.

Built-in, local, and pending Skills

AIClaw does not treat all Skills the same. The current app exposes three practical states.

1. Built-in Skills

Built-in Skills ship with the application. On startup, AIClaw syncs embedded builtin SKILL.md files to the workspace Skills directory, so the runtime has a consistent on-disk view.

2. Local Skills

Local Skills live under the workspace skills/ directory. The admin UI lists them separately, including metadata such as directory name, version, author, and whether the Skill has an executable entry file.

That makes Skills more than prompt snippets. They can also behave like reusable tool bundles.

3. Pending Skill candidates

This is the part I like most in the current implementation.

The Skills page explains that successful multi-tool Agent runs using three or more distinct tools can archive a candidate into skills-pending/. From there, a user can:

preview the candidate
promote it into an active Skill
discard it

This turns useful ad hoc agent behavior into a reviewable workflow instead of silently mutating the prompt library.

Why the promotion step matters

Auto-generated Skills are powerful, but automatic activation would be noisy and risky. AIClaw keeps a human checkpoint in the middle.

The promotion flow in the current handlers and UI requires:

a final Skill name
a description
explicit promotion into the active Skills directory

That gives teams a simple governance model:

agents can suggest reusable workflows
humans decide which ones become permanent assets

User workflow in practice

Here is the practical loop the current product supports:

Install or create Skills in the workspace.
Let agents see a compact Skill catalog during prompt construction.
Allow the agent to read a full Skill only when the task needs it.
Review pending Skill candidates created from successful multi-tool runs.
Promote the useful ones into the active Skill library.

This design is small, but it changes how an agent system scales. Instead of treating every reusable instruction as permanent prompt baggage, AIClaw treats Skills like indexed assets with on-demand expansion.

A concrete example

Imagine a team has Skills for:

deep research
web scraping
data cleanup
browser automation
report generation

With one-stage loading, every conversation drags all of that context around. With AIClaw's current two-stage approach, the agent only needs the index first. A simple file-editing task does not need the full research workflow. A browser-heavy task can load the browser Skill when it becomes relevant.

That is a cleaner model for both cost and reasoning.

Why this is a useful pattern beyond AIClaw

The broader idea is simple: agent capability catalogs should be cheap to expose and expensive details should be loaded lazily.

AIClaw applies that idea in a way that is easy to understand from the repo today:

compact discovery
explicit demand loading
reviewable Skill promotion
support for both instruction-only and executable Skills

For self-hosted agent platforms, that is a pragmatic design choice. It keeps the system extensible without making every prompt bloated by default.

If you are exploring AIClaw, the Skills page and the skills/ plus skills-pending/ workflow are worth a close look. They show how the project treats reusable agent behavior as something structured, inspectable, and incrementally promotable instead of just more text in the system prompt.

AIClaw’s Execution Logs Just Got Easier To Read Across Languages

chowyu — Sun, 14 Jun 2026 08:34:11 +0000

AIClaw already had one of the more useful operational surfaces in a self-hosted agent runtime: execution steps are not hidden behind a raw trace file or an opaque debug mode. They are part of the product.

The latest repository change, fix: localize execution step labels, improves that surface in a practical way. The chat view and the execution log view now render more of the plan and step metadata through the shared i18n layer instead of hard-coded mixed-language labels.

Project: https://github.com/chowyu12/aiclaw

Why this matters

A lot of agent products can show you a final answer. Fewer are good at showing what happened between the prompt and the answer:

which plan item was running;
which tools were called;
what input a tool received;
what output came back;
how long each step took;
where channel-specific metadata came from.

AIClaw has already been shipping that execution detail in both chat and the dedicated logs page. The new localization pass makes the same information more readable for operators switching between Chinese and English UI modes.

That is not cosmetic in the trivial sense. If a product wants execution logs to be part of normal operations, the labels around those logs have to be consistent.

What changed in the current repo

Today’s commit touches three frontend files:

web/src/stores/i18n.ts
web/src/views/chat/Index.vue
web/src/views/log/Index.vue

The concrete change is straightforward:

move execution-step labels, plan labels, timing labels, file labels, and log-table labels into shared translation keys;
remove hard-coded strings from the Chat page and Logs page;
keep the execution-step structure the same while making the UI language-aware.

Examples of newly localized UI copy include:

execution step counts;
total duration;
child step counts;
started / ended / duration timestamps;
input / output / error section labels;
channel labels;
untitled conversation fallback text;
execution log table headers and empty-state text.

So the feature story here is not “AIClaw added logs today.” The real story is that AIClaw’s existing execution-log workflow became easier to operate in multilingual environments.

The bigger design behind it

This repository is opinionated about observability.

From the current README:

AIClaw persists conversations, execution steps, generated files, and plan state.
The web console includes chat and execution logs.
Tool output is visible through execution steps instead of disappearing into an internal harness.

That design shows up directly in the UI:

the final assistant message can carry a plan snapshot;
execution steps can be expanded under a reply;
tool-only intermediate rounds are hidden from the normal timeline to reduce noise;
the detailed step trail still remains accessible under the final reply and in the dedicated logs view.

This is a good operational choice.

If every internal tool round is dumped directly into the visible conversation stream, the chat becomes hard to read. If those rounds are hidden completely, debugging becomes painful. AIClaw splits those concerns:

the conversation stays readable;
the execution trail stays inspectable.

What you can actually inspect in AIClaw

In the current product, execution steps can expose details such as:

step type, such as LLM, Tool, Agent, or Skill;
tool name, including special handling for web_search;
step status;
duration;
input;
output;
error text;
provider and model metadata;
channel metadata;
nested sub-agent depth and child steps.

That means the logs are useful for more than debugging crashes. They help answer normal operating questions:

Why did this answer take 18 seconds?
Did the agent use external web search or a normal tool?
Which sub-agent branch produced the result?
Was the failure in the LLM call, the tool call, or the surrounding workflow?

Why I picked this topic for today

There is a concrete new commit behind it, but it also points to a broader product surface that deserves a deeper article: AIClaw treats execution logs as a first-class UX, not as an afterthought.

Recent AIClaw writeups already covered configurable web search, the built-in scheduler, generated file attachments, and Runtime Plan State. Today’s change is a good reason to focus on another core surface in that rotation: tool execution logs and operator-facing observability.

A practical example

Imagine an agent that:

receives a prompt from web chat or a messaging channel;
creates a small runtime plan;
calls web_search;
delegates a verification task to a sub_agent;
returns a final answer with attached artifacts.

In AIClaw, the operator can inspect that run without reading backend code:

the plan panel shows which item ran and which item failed or completed;
the execution steps show tool inputs and outputs;
the logs page lets you inspect the same conversation later;
language-aware labels reduce friction for multilingual teams.

That is the kind of product detail that determines whether an agent system is usable in real operations.

The takeaway

The newest AIClaw commit is small in scope, but it improves an important part of the platform: the execution-log interface that operators actually use when they need to understand agent behavior.

If you care about self-hosted agents, the interesting thing is not just that AIClaw can run tools. It is that AIClaw keeps those tool runs visible, structured, and now more consistently localized across the main inspection surfaces.

Install or update:

curl -fsSL https://raw.githubusercontent.com/chowyu12/aiclaw/master/install.sh | bash

GitHub: https://github.com/chowyu12/aiclaw

How AIClaw Keeps Agent Plans Out of Chat History with Runtime Plan State

chowyu — Sat, 13 Jun 2026 16:35:21 +0000

Most agent products eventually hit the same UX problem: complex tasks need planning, but users do not want the final answer buried under noisy TODO updates.

AIClaw handles that with an existing core feature called Runtime Plan State. Instead of storing planning as ordinary assistant text, AIClaw treats the plan as runtime state owned by the executor. The model can propose or revise a plan, but the harness validates it, persists it, streams it live, and links the final snapshot to the assistant message after execution finishes.

This post is not announcing a brand-new feature. It is a deeper look at how AIClaw already implements planning in a way that stays useful during execution without polluting the conversation itself.

The problem with chat-visible plans

If an agent writes plans directly into chat, several issues show up quickly:

progress updates become part of the permanent conversational transcript
repeated plan rewrites waste tokens and distract from the real answer
tool errors and retries are hard to map back to the current step
users can see planning noise, but still cannot reliably inspect execution state

AIClaw's approach is to separate these concerns:

the user sees the final answer as an answer
the executor keeps the plan as structured runtime state
the log timeline shows both plan progress and tool activity

The repository README describes this directly: AIClaw uses Plan State instead of chat-visible TODO blocks, and streaming chat plus execution logs show the plan separately from the assistant answer.

What Runtime Plan State means in AIClaw

At a high level, AIClaw's execution loop does this:

Load the agent, tools, memory, files, and conversation history.
Inject compact runtime context, including the current plan state.
Call the model with tools.
Execute tool calls and track progress.
Let the harness advance the plan after success or failure.
Save the final assistant response and the plan snapshot.

The plan has a small lifecycle instead of being treated like free-form prose:

pending -> running -> completed
                  -> failed
                  -> blocked
pending -> skipped

That lifecycle matters because the harness can enforce behavior the model should not be trusted to enforce by itself.

The design choice: model proposes, harness owns

In internal/agent/plan.go, the internal plan control tool supports actions such as set, update, revise, and read. But the important part is not the tool surface. The important part is ownership:

the model proposes plan changes
PlanManager normalizes and validates state
the store persists the active run and items
the executor refreshes the compact plan block before each LLM round

That split keeps the model flexible without giving it full control over task state.

For example, AIClaw enforces that only one plan item can be running at a time. The tests in internal/agent/plan_test.go explicitly verify that if multiple items are proposed as running, the plan is normalized back to a single running item.

Why the prompt stays compact

One subtle but important implementation detail is that AIClaw does not inject the full plan history into every model call.

The PromptBlock path in internal/agent/plan.go builds a compact <plan_state> block with:

the goal
the current running step
a short pending-step summary
the latest revision reason
numeric progress

The design notes in docs/design/agent-improvements.md call this out clearly: only the goal, current running item, remaining pending summary, and recent revision reason are injected each round so the full history does not consume context budget.

This is a practical design choice. Planning helps the model stay oriented, but dumping the whole plan transcript back into the prompt every round would work against that goal.

How execution advances the plan

The main run loop in internal/agent/run.go refreshes plan state before each model call. When tool or LLM work fails, the harness can mark the current step as failed. When a step succeeds, the harness can complete it and advance to the next pending one.

That behavior is also covered by tests:

a failed running step advances the next pending step into running
linking the final assistant message marks the last running step as completed
failed plans stay failed when the final message is attached

This is the difference between "the model wrote a checklist" and "the system is actually operating a task state machine."

What the user sees

From the product side, Runtime Plan State gives AIClaw a cleaner split between response and observability:

the final answer is not cluttered by plan chatter
streaming progress can still expose the live plan
execution logs keep the plan snapshot, assistant response, and tool timeline separate

That matters for real tool-using agents. If an agent reads files, runs commands, searches the web, or delegates to sub-agents, users need to inspect progress and failures without turning the final answer into a debug trace.

A practical example

Imagine an AIClaw agent is asked to:

inspect a codebase
find the cause of a failing behavior
patch the code
run tests
summarize the result

With Runtime Plan State, the plan can exist as structured execution state while the tool timeline records the underlying work. If the test step fails, AIClaw can mark that step as failed and continue the state transition logic cleanly. If the work completes, the final answer can stay focused on outcome, not internal bookkeeping.

That is a better fit for production-style agent work than chat-visible TODO spam.

Why I think this is the right abstraction

AIClaw's design makes a strong distinction:

planning is operational state
answers are user-facing output
logs are for inspection

Those should not all be the same thing.

A lot of agent systems blur the line between them. AIClaw's Runtime Plan State is interesting precisely because it does not.

If you are building self-hosted agents and want both cleaner chat UX and better execution observability, this is one of the AIClaw features worth studying in the codebase.

AIClaw is open source here: github.com/chowyu12/aiclaw

AIClaw's Generated File Attachments Keep Tool Output In The Chat Loop

chowyu — Thu, 11 Jun 2026 16:35:26 +0000

AIClaw is a self-hosted agent runtime, so "the answer" is often not the most useful output. In real workflows you usually want the file the agent created: a screenshot, a CSV, a Markdown report, a PDF, or some artifact produced by a tool run.

AIClaw already persists conversations, execution steps, and files in the same runtime. What makes that useful is that generated files are not treated as an afterthought. They are attached to the conversation, returned from chat APIs, and rendered directly in the web chat UI.

Project: https://github.com/chowyu12/aiclaw

The Problem

Many agent demos stop at plain text:

a tool writes a file somewhere under /tmp
the model mentions that the file exists
the user has to go find it manually
the next turn may not reliably carry that artifact forward

That breaks down fast once agents start using browser automation, code execution, shell commands, or document-style outputs.

AIClaw's current design closes that gap in three places:

request-time file loading for uploaded files and URL-based files
tool-output persistence for files created during execution
chat/UI attachment rendering for both user-provided and agent-generated artifacts

How Files Enter The Runtime

AIClaw's chat request model supports file references through files on ChatRequest, with two transfer modes:

local_file
remote_url

On the server side, internal/agent/file.go loads those inputs into the execution context. Local uploads are resolved from persisted file records, and remote URLs can be fetched into temporary storage. Text and document types also get text extraction when possible, so the model can work with the content instead of only a file pointer.

There is one design detail here that matters a lot in practice: AIClaw also loads prior conversation files with ListFilesByConversation(...), so files stay in the conversation context instead of disappearing after one turn.

That makes attachments part of the working session, not just part of one HTTP request.

How Tool Output Becomes A Conversation Attachment

The interesting part is what happens after a tool runs.

In internal/agent/tool_call.go, AIClaw wraps each tool call with file-aware persistence logic:

it snapshots the sandbox directory before the tool runs
it executes the tool
it checks whether the tool returned a structured file result
if not, it scans the sandbox for newly created files
it persists those files into the uploads area and creates file records in storage

That gives AIClaw two ways to capture artifacts:

Explicit file results
New files detected from the sandbox after execution

The sandbox scan intentionally skips script carrier files like .py, .js, .sh, .rb, and .ts, so it focuses on outputs rather than execution scaffolding.

This is a pragmatic design choice. It means tool authors do not always need a perfect custom return path for every artifact-producing workflow. If a tool or interpreter creates a real output file, AIClaw still has a chance to preserve it.

Why This Matters For Actual Agent Work

This file flow is especially useful for tools that naturally produce artifacts:

browser can produce screenshots
code_interpreter can generate plots, tables, and exported files
shell-oriented tools can write reports or transformed datasets
sub-agents can bubble their files back to the parent run

sub_agent output is also handled explicitly in the same tool-call path, so the parent conversation can inherit generated files from delegated work instead of losing them inside nested execution.

That is the difference between "the agent said it did something" and "the result is now attached to the conversation and available to open."

API And Streaming Behavior

The chat API returns files as first-class response data.

In internal/handler/chat.go, the non-streaming response includes:

message
steps
files
plan

The streaming shape in model.StreamChunk also includes files, so generated artifacts can be delivered as part of the same execution session rather than requiring a separate polling flow.

This fits the rest of AIClaw's runtime model well:

execution steps show what happened
plan state shows task progress
attachments carry the concrete output

What The Chat UI Does With It

The Vue chat page under web/src/views/chat/Index.vue renders attachments directly inside the message bubble.

Current behavior is straightforward and useful:

images render as preview cards with thumbnails
non-image files render as clickable file cards
file type and size are shown in the UI
user-side pending uploads and URL attachments are visible before send

That matters because it keeps the artifact in the same visual flow as the model response and the execution timeline. You do not have to jump into another admin page just to confirm that a generated file exists.

A Practical Workflow

Here is a realistic AIClaw flow using this design:

Upload a CSV to the conversation.
Ask the agent to analyze it and generate a summary report plus a chart.
Let a code-oriented tool write the chart image and report file.
Receive the assistant answer, execution steps, and the generated attachments in the same conversation.
Open the files directly from the chat UI or reuse them in the next turn.

The same pattern applies to browser screenshots, exported markdown notes, or files produced by a delegated sub-agent.

Why I Like This Design

What stands out in AIClaw's implementation is that attachments are part of the runtime contract, not a bolt-on download feature.

The executor loads files into context.
The tool layer persists produced artifacts.
The store keeps them associated with the conversation.
The API returns them.
The chat UI renders them.

That end-to-end path is what makes an agent platform usable for work that produces assets instead of only text.

If you're building local-first or self-hosted agents, this is one of the surfaces worth getting right early. Text answers are cheap. Reliable artifact handling is what makes the system operational.

AIClaw’s Built-In Scheduler: Run Agent Prompts and Shell Commands on Cron

chowyu — Wed, 10 Jun 2026 16:36:00 +0000

AI agents are useful when they can do work on demand. They become much more practical when they can also do that work on a schedule.

AIClaw includes a built-in cron tool and Scheduler page for exactly that. Instead of depending on system crontab glue or an external workflow service, AIClaw runs scheduled jobs inside the same runtime that already knows about your agents, tools, workspace, and execution logs.

Project: https://github.com/chowyu12/aiclaw

The problem with bolting cron onto agents

A lot of agent setups can answer a prompt right now, but recurring work is usually handled outside the agent runtime:

a system crontab entry;
a CI workflow;
a separate automation server;
or a custom script that calls the agent through another interface.

That works, but it breaks the operating model. The schedule lives in one place, the agent runtime lives in another, and the execution trail is often incomplete.

AIClaw takes a different approach. The scheduler is part of the product runtime, so scheduled work can be created, persisted, executed, and inspected without leaving the platform.

What AIClaw actually ships

From the current repository:

AIClaw exposes a built-in cron tool for agents.
Jobs can be prompt jobs or command jobs.
The scheduler runs in-process using robfig/cron with seconds enabled.
Jobs are persisted under scheduler/jobs.json.
Per-job execution logs are appended as JSONL files under scheduler/logs/{id}.jsonl.
Jobs support enable/disable control, run counts, and optional max_runs.
The web console includes a Scheduler page where you can inspect jobs and view recent logs.

This is not “LLM asks cron to call a webhook later.” It is part of the same local runtime.

Two job types: agent prompt or shell command

The built-in tool definition exposes two execution modes:

prompt: send a scheduled prompt back into an AIClaw agent;
command: execute a shell command.

That split matters in practice.

Use prompt when the recurring work should go through the full agent loop: prompt, tools, plan state, memory, files, and final response.

Use command when you already know the exact shell operation you want to run and do not need model reasoning for that step.

Cron syntax that is useful in real operations

AIClaw’s scheduler accepts:

6-field cron expressions with seconds;
descriptors such as @daily and @hourly;
interval expressions such as @every 30m.

Examples from the tool definition:

0 0 9 * * *      -> daily at 9:00 AM
0 */5 * * * *    -> every 5 minutes
@every 30m       -> every 30 minutes
@daily           -> once a day at midnight

That makes it usable for both product-style reminders and more operational polling loops.

Why the in-process design matters

The key design choice is that scheduled jobs execute inside AIClaw itself.

For prompt jobs, the scheduler can call the agent executor directly. For command jobs, it can run shell work directly. Because both paths stay inside the product runtime, AIClaw can keep a consistent operational surface:

one place to define the work;
one place to inspect the job;
one place to review success or failure;
one place to see output and error text.

The design doc in this repo explicitly calls out why this replaced a more traditional crontab-based approach: system cron is Unix-specific and cannot directly drive the agent execution engine.

Persistence and restart behavior

This is one of the most practical parts of the implementation.

When the scheduler starts, it loads persisted jobs from disk and re-schedules enabled entries. That means scheduled work survives process restarts instead of disappearing with the current session.

The job record tracks fields such as:

expression
type
agent_uuid
prompt
command
enabled
max_runs
run_count
last_run_at
next_run_at

For recurring production use, this is much more useful than “fire and forget.”

Inspectable run logs instead of invisible background work

Each execution produces a structured run record with:

run time;
duration;
status;
output;
error.

AIClaw stores those records as JSONL and exposes them through the Scheduler UI and scheduler API routes. The web console can load recent logs for a job, reverse them for readability, and show output or failure text inline.

That gives you a real audit trail for recurring work. If a daily prompt stopped doing what you expected, you can inspect the logs instead of guessing whether the scheduler even fired.

There is also a small but important operational safeguard: per-job log files rotate after a size threshold instead of growing forever.

`max_runs` is a good fit for temporary automations

Not every schedule should be permanent.

AIClaw jobs can optionally define max_runs. Once the run count reaches that limit, the job disables itself automatically.

This is a strong fit for practical workflows like:

“run this migration check 10 times while we watch rollout health”;
“summarize this project standup every workday for two weeks”;
“poll a dependency update status until the cutover is done.”

You do not need a second cleanup task to stop the first one.

How this fits the rest of AIClaw

The scheduler makes more sense when you look at the rest of the product:

AIClaw already has a tool runtime.
It already has agents with configurable prompts and models.
It already persists conversations, execution steps, generated files, memory, and plan state.
It already has a web console for inspection.

So a built-in scheduler is not an unrelated extra. It extends the same operating model into recurring work.

Practical examples

Here are a few concrete patterns this enables:

Daily research brief: schedule a prompt job that asks an agent to gather updates and produce a short report.
Workspace hygiene: schedule a command job to collect disk usage, rotate artifacts, or run a repo maintenance command.
Release watch: schedule a prompt job that checks a dependency or upstream project and writes back a structured summary.
Inbox triage or channel follow-up: schedule an agent workflow at fixed times instead of manually triggering it.

The important part is not just that these jobs run. It is that they run inside the same local-first system where the rest of the agent work already happens.

Why I think this feature is worth highlighting

Many AI agent demos stop at interactive chat. AIClaw treats agent execution more like an operating system concern: prompts, tools, plans, memory, files, logs, and now scheduled recurrence all belong to the same runtime.

That makes the scheduler a meaningful feature even without a brand-new release attached to it. It shows how AIClaw is designed for repeatable work, not just one-off conversations.

If you are building local-first agents and want recurring jobs without handing control to an external automation platform, this part of AIClaw is worth a look.

Install or update:

curl -fsSL https://raw.githubusercontent.com/chowyu12/aiclaw/master/install.sh | bash

GitHub: https://github.com/chowyu12/aiclaw