AI Learning Library

Real-world AI tools,
one page at a time

One concept per page. Learn by turning pages like a book — no endless scrolling. Built from hands-on, verified material.

macmini ~ agents
Mac mini Agent Practical Guide
MAC·MINI
Mac mini Agent — Practical Guide
Run AI agents 24/7 on a Mac mini (M4/M5) with NanoClaw and HermesClaw — from hardware choice and install to auto-start, security, and real-world cases, one page at a time.
NanoClaw·HermesClaw · 19 parts Start
claude ~ code
CLAUDE
Claude Code Guide
Anthropic's official CLI. Hooks, MCP, agent orchestration.
Coming soonComing Soon
codex ~ cli
CODEX
Codex CLI Guide
OpenAI terminal agent. AGENTS.md, sandboxing.
Coming soonComing Soon
midjourney ~ v7
MIDJOURNEY
Midjourney V7 Guide
V7 prompts, reference images, style consistency.
Coming soonComing Soon
Mac mini Agent — Practical Guide
Section 01 / 19

Mac mini Agent — Practical Guide

A practical, beginner-friendly guide to running AI agents 24/7 on a Mac mini (M4/M5) with NanoClaw and HermesClaw — all 19 parts. From hardware choice and install to auto-start, security, troubleshooting, and real-world cases.

1. What You Can Do with This Guide

01Why Create a Personal AI Agent Environment on Mac mini?

Today, there are two main ways to use AI.

The first is to go to a website or app and ask AI questions whenever you need them. You open services like ChatGPT, Claude, or Gemini in a browser, type questions yourself, and copy-paste answers elsewhere.

The second is to bring AI into your favorite messaging app, run it continuously on your computer, and have it handle tasks for you.

Your Mac mini on the desk becomes a personal AI workspace that never shuts down, and you delegate tasks to it through your everyday messenger.

Users message in apps like Telegram, Discord, Slack, WhatsApp, or WeChat, while an agent running inside Mac mini receives and processes the message, then sends a reply back.

02Understanding NanoClaw and HermesClaw

NanoClaw is a personal AI agent environment that runs on your computer. When you message in a messaging app, NanoClaw receives the message, passes it to an AI model, executes necessary tasks, and sends a reply. According to official descriptions, it can connect to multiple messaging apps like WhatsApp, Telegram, Slack, Discord, and Microsoft Teams, with each agent group running isolated inside Docker containers.

HermesClaw serves a more specialized purpose. It's meaningful when you want to use Hermes Agent and OpenClaw together on the same WeChat account. HermesClaw holds one iLink connection and provides local proxies to both Hermes and OpenClaw sides, designed as a community project to avoid connection conflicts.

For beginners, understanding the role is more important than the names:

And Mac mini serves as a small personal server good for running both 24 hours.

03Why Choose Mac mini

Mac mini is small, quiet, relatively low power consumption, and easy to leave running continuously on a desk or near a router.

Unlike laptops that you carry around, it's designed to stay in one place and operate, making it ideal for personal automation servers, messaging bot servers, home servers, and development testing equipment.

Especially M4 Mac mini, based on Apple Silicon, offers good power efficiency relative to performance and is sufficient as a starting point for installing development tools like Docker, Node.js, and pnpm to set up a personal AI agent environment.

However, for products like M5 Mac mini that are not officially announced yet or whose specifications are not finalized, do not assume performance, and recheck CPU, GPU, memory, storage, Docker compatibility, heat output, and power consumption after official announcement.

04What You Can Do with This Environment

Learning this environment enables you to create practical automations like:

The key difference is this: regular AI chat requires you to open a browser and ask every time, but a personal AI agent server waits continuously in your favorite messaging app and handles repeated work for you.

05Learning Order for Beginners

You don't need to build grand automation from the start. A beginner's goal should be very small.

First step: The agent starts on my Mac mini, and when I message from a messaging app, I get a reply.

Second: It runs again after rebooting.

Third: API keys and configuration files are managed securely.

Fourth: Add practical automations one by one like personal assistant, work summaries, alerts, and trading journal helpers.

This order is crucial. If you try to build a perfect AI secretary from the start, most people get stuck at installation, authentication, Docker, API keys, and log checking. Conversely, creating small wins first reveals the whole structure.

06The Goal of This Guide

This guide covers how to use Mac mini M4/M5 as a personal AI agent server.

Specific goals are:

The core of this guide is not "how to ask AI questions" but "how to create a personal work environment where AI is waiting."

07What You'll Be Able to Do After Reading This

Basic Setup

Basic Operation

08Practical Use Cases and Explanation Style

Practical Use Cases

Where Beginners Get Stuck

This guide doesn't write like a developer documentation translation. It focuses on places where beginners actually get stuck — what program to install first, terminal commands, execution failure after installation, where API keys go, Docker concepts, messaging app connection, restart execution, error log interpretation — around these actual pain points.

09Classifying Information by Three Criteria

Confirmed Information

Content verified from official documentation, official repositories, and official specification pages. For example, Mac mini M4 official specifications are written based on Apple's official specification page. Apple's current Mac mini specification page shows M4 and M4 Pro configurations, with M4 offering 10-core CPU and 10-core GPU, and M4 Pro offering base 12-core CPU and 16-core GPU configurations.

Pre-Launch Information

Information like M5 Mac mini that is not officially announced yet or is pre-announcement is marked as speculation, pre-launch basis, and needs verification after official announcement.

Practical Tips

Important parts in actual operation that official documentation covers briefly. This includes not connecting all messaging apps initially, separating test accounts, API key security, and automatic startup order.

10Mac mini Recommendations by Use Case

First installation practice
Basic Mac mini is sufficient
Telegram/Discord personal bot
M4 base or memory upgrade
Multiple messaging apps simultaneously
Configuration with memory headroom
Hermes / OpenClaw / multiple agents in parallel
Consider M4 Pro or M5 class
Local LLM experimentation
Larger memory configuration first
24-hour stable operation
Prioritize stability over top specs, backup, log management

Mac mini M4 starts at 16GB unified memory according to Apple's official specifications, and some configurations can be upgraded to 24GB. M4 Pro configurations start at 24GB unified memory and go up to 48GB.

M5 Mac mini must be rechecked for CPU, GPU, memory options, storage, port configuration, Docker compatibility, heat output, and power consumption after official announcement.

11Five Principles Beginners Must Follow

Principle 1. Connect one at a time — Don't connect Telegram, Discord, Slack, WhatsApp, and WeChat all at once from the start. Begin with local CLI test → a test channel like Telegram or Discord → your actual messaging app → automatic startup → security hardening → add practical automation, in that order.

Principle 2. Don't connect your actual account first — When you first install, use a test account. Messaging app integration is more sensitive than you think.

Principle 3. Never expose API keys — API keys are like passwords. Don't post them on blogs, GitHub, messengers, or mix them with test keys.

Principle 4. Do automatic startup last — A common mistake is setting up automatic startup when manual execution isn't even working. Follow this order: manual execution → test message → log check → verify repeated execution → restart and rerun → automatic startup setup.

Principle 5. Back up before updating — Agent tools can change configuration methods after updates. Back up configuration files, .env files, memory files, skill files, logs, and Docker compose files.

12The Final Outcome of This Guide

Minimum Complete State

Production-Ready State

Stable Operation State

Section 1 · Key Takeaways

Key Takeaways from This Section

This guide is not a simple installation guide for NanoClaw or HermesClaw on Mac mini. The goal is to create a personal AI agent environment that beginners can operate themselves.

There are three core principles:

Your Mac mini agent starts, receives messages, sends replies, and recovers even after restart.

After reaching this state, you can expand into personal assistant, work automation, and trading alert helpers.

Next Section

2. Checking Prerequisites and Installing

2. Understanding the Big Picture First

01What Do NanoClaw and HermesClaw Do?

NanoClaw and HermesClaw are both tools that enable you to use AI agents in messaging apps.

Simply put, the structure works like this.

User → Messaging apps like Telegram / Discord / WhatsApp / WeChat → Agent running on Mac mini → AI model call → Generate reply → Deliver back to messaging app

In other words, Mac mini is not just a computer but a personal AI relay server that's always on.

02NanoClaw: A Personal AI Assistant Attachable to Multiple Messengers

NanoClaw supports multiple channels like WhatsApp, Telegram, Discord, Slack, Microsoft Teams, iMessage, Matrix, Google Chat, Webex, Linear, GitHub, WeChat, and email. Each agent group runs isolated inside Docker containers, and you can structure it to use independent agents per channel or group multiple channels into one session.

The structure works like this:

Ask a question on Telegram → NanoClaw receives it → Ask Claude / another AI model → Generate reply → Send back to Telegram

NanoClaw is good for beginners to understand. The reason is that the structure is relatively simple, and official documentation highlights "easy to understand and customize codebase" as an advantage.

03HermesClaw: A Traffic Controller for Running Multiple Agents Inside WeChat

HermesClaw has a slightly different purpose. It's a bridge for using Hermes Agent, OpenClaw, and OpenCode together on the same WeChat account. Running Hermes Agent and OpenClaw simultaneously on the same WeChat account can create iLink connection conflicts, so HermesClaw solves the problem by becoming a single iLink poller itself and providing local proxies to the Hermes and OpenClaw sides.

The structure works like this:

WeChat message input → HermesClaw receives first → If /hermes command, forward to Hermes → If /openclaw command, forward to OpenClaw → If /both command, use both → Return result to WeChat

HermesClaw lets you switch agents with commands like /hermes, /openclaw, /opencode, /both, and /three.

04Why Is Mac mini Well-Suited for This Purpose?

In this guide, Mac mini is viewed as a small, quiet, always-on device.

In AI agent operations, the highest performance alone is not what matters most. What's more important are these four things.

1. Can you keep it on for long periods? 2. Is noise and heat low? 3. Is power consumption not burdensome? 4. Is automatic recovery after restart easy?

According to Apple's official specifications, the Mac mini M4 is 5.0 x 5.0 x 2.0 inches in size, the M4 model weighs 0.67kg, and the M4 Pro model weighs 0.73kg. It also provides Gigabit Ethernet by default and can be configured with 10Gb Ethernet.

The Ethernet port is important. When operating a messaging agent 24 hours, wired LAN is more stable than Wi-Fi. If you want to reduce problems with delayed messages or dropped connections, prioritize wired connections when possible.

05Complete Operation Structure: NanoClaw Standard

Based on NanoClaw, you can understand the structure like this:

[Messaging App] Telegram / Discord / Slack / WhatsApp, etc. ↓ [Router] Identify which channel the message came from ↓ [Agent Container] Each agent runs inside Docker ↓ [AI Model] Call Claude / OpenAI / other models ↓ [Response Delivery] Send reply back to original messaging app

According to the official NanoClaw documentation, a single Node host orchestrates agent containers per session, and each session uses separate SQLite file structures. It also states that each agent group has its own CLAUDE.md, memory, container, and allowed mount scope.

Beginners only need to understand one thing here.

"The agent doesn't use my entire Mac arbitrarily; the key is to make it run within a defined space."

That's why Docker or containers are used. Docker is a platform that enables building, sharing, and running applications in container units, and Docker's official page also describes container-based execution and isolation as core concepts.

06What's Possible with M4 Mac mini

M4 Mac mini is sufficiently practical equipment for messaging-based AI agent operations.

According to Apple's official specifications, Mac mini M4 has 10-core CPU, 10-core GPU, 16-core Neural Engine, and 120GB/s memory bandwidth. M4 Pro has 12-core CPU, 16-core GPU, 273GB/s memory bandwidth, and can also be selected with 14-core CPU and 20-core GPU configurations.

Realistic tasks you can do with M4 Mac mini include:

- Telegram personal secretary bot - Discord task assistant bot - Slack work summary bot - Send alerts at scheduled times - Message summarization - Simple file organization automation - Trading journal writing assistance - News summary and message delivery - API-based price alerts

Even the basic M4 model is sufficient to start operating 1-2 messaging agents. However, if you plan to connect multiple channels simultaneously, run multiple Docker containers, or run a local LLM in parallel, memory headroom becomes important.

According to Apple's official specifications, Mac mini M4 starts with 16GB unified memory and can be configured with 24GB or 32GB, while M4 Pro starts with 24GB unified memory and can be configured with 48GB or 64GB.

07What to Expect from M5 Mac mini

Apple has officially announced the M5 chip itself. According to Apple, M5 is based on third-generation 3-nanometer process, features Neural Accelerator on each GPU core in the 10-core GPU structure, has AI GPU peak compute performance over 4x M4, and has unified memory bandwidth of 153GB/s, about 30% higher than M4.

However, the important criterion in this guide is one.

"M5 chip information" and "M5 Mac mini product specifications" must be distinguished.

The fact that M5 chip information was officially announced doesn't mean that M5 Mac mini's port configuration, memory options, storage options, heat output, price, and release date are all confirmed. It's safer to verify official specifications from Apple's Mac mini specification page or Apple Support documentation after they are updated.

When M5 Mac mini officially launches, specific items to check in this guide include:

- Base memory capacity - Maximum memory options - Base SSD capacity - Thunderbolt 4 / Thunderbolt 5 configuration - 10Gb Ethernet option maintained or not - Docker Desktop compatibility - Heat output during extended operation - Automatic execution stability after reboot - Compatibility with existing NanoClaw / HermesClaw installation

M5's advantages can be expected especially in AI processing and memory bandwidth. However, if you use NanoClaw or HermesClaw simply as messaging agents, network stability, memory headroom, automatic recovery settings, and log management may be more important than CPU/GPU performance.

08"AI Model" and "Agent" Are Different

An AI model is the thinking brain that creates answers.

For example:

Claude OpenAI models Local LLM Other API-based models

An agent is the executor who connects that brain to actual work.

Receive message Read file Execute command Check schedule Call API Send reply

Beginners often confuse these two. Here's the breakdown:

AI Model = Thinking brain Agent = Employee handling work NanoClaw / Hermes / OpenClaw = System that makes employees work Mac mini = Office where employees work Docker = Separate workspace where employees work

09"Docker" Is More Like a Safety Device Than an Optional Choice

You don't need to find Docker difficult.

In beginner's terms, Docker is a tool that makes a program run inside a defined room instead of using my entire Mac.

When granting file access, network access, and command execution permissions to an agent, you always need to be careful. Using containers helps reduce the scope of access an agent can reach.

NanoClaw's official documentation also describes Docker sandboxes on macOS, Linux, and WSL2 environments as the default isolation method, and mentions Docker Sandboxes micro-VM or macOS's Apple Container as additional isolation choices.

10"Channel" Is Where Messages Come In

Channel refers to messaging apps like Telegram, Discord, Slack, WhatsApp, and WeChat.

Telegram = Channel Discord = Channel Slack = Channel WeChat = Channel Email = Channel

It's not good to connect multiple channels from the start. The recommended beginner order is:

1. Connect only one test channel 2. Confirm message reception 3. Confirm reply sending 4. Check logs 5. Confirm recovery after restart 6. Then add a second channel

If you attach multiple channels at once, it becomes hard to find the cause when problems occur.

11"Memory" Has Two Meanings: RAM and Agent Memory

This is easy to get confused here.

Mac mini's memory is RAM.

16GB 24GB 32GB 48GB 64GB

Agent memory is a record that stores user conversations, settings, preferences, work methods, etc.

User profile Conversation history Work rules Frequently used commands Skill settings

They are completely different. Here's the breakdown:

Mac Memory
Work space the computer can process simultaneously
Example
16GB, 24GB, 32GB
Agent Memory
User information the agent remembers
Example
Preference settings, work rules, conversation history

12Criteria for Choosing Between NanoClaw and HermesClaw

Beginners can choose based on these criteria:

Starting out for the first time
Review NanoClaw first
Want to attach multiple messaging apps
NanoClaw
Focused on Telegram, Discord, Slack
NanoClaw
Want to use Hermes and OpenClaw together on WeChat
HermesClaw
Already using Hermes Agent
Review HermesClaw
Already using OpenClaw
Review HermesClaw
Want to keep structure simple
NanoClaw
Need WeChat multi-agent routing
HermesClaw

The Hermes Agent official GitHub README also introduces HermesClaw as a community WeChat bridge and describes it as intended for running Hermes Agent and OpenClaw on the same WeChat account.

13Simplest NanoClaw Structure

Example 1: The best structure for beginners

Mac mini M4 └── Docker └── NanoClaw └── Telegram personal secretary bot

What you can do:

- Simple question and answer - Organize today's tasks - Save notes - Schedule alerts - News summaries

Advantages:

- Structure is simple - Easy to find cause when problems occur - Low cost and resource burden

14NanoClaw Structure Using Multiple Channels

Example 2: Structure for expanding channels

Mac mini M4 / M4 Pro └── Docker └── NanoClaw ├── Telegram agent ├── Discord agent └── Slack agent

What you can do:

- Receive personal messages on Telegram - Summarize team conversations on Slack - Receive community alerts on Discord

Things to watch out for:

- As channels increase, logs increase - API usage increases - Permission management becomes important - Testing per channel is necessary

15HermesClaw-Based WeChat Structure

Example 3: HermesClaw-based structure

Mac mini └── HermesClaw ├── Hermes Agent ├── OpenClaw └── OpenCode

According to HermesClaw's official structure, HermesClaw acts as a single poller connected to iLink API, provides local proxies to OpenClaw and Hermes respectively, and provides ACP bridge to OpenCode.

This structure is more suitable for people matching these conditions than for those just starting out:

- Must use WeChat - Already using Hermes Agent - Want to use OpenClaw too - Want to switch between multiple agents in one WeChat account

16Recommended Starting Order for Beginners

Trying to build a complete structure from the start often gets blocked. The recommended order is:

1. Basic Mac mini setup 2. Prepare Homebrew / Git / Docker 3. Choose only one: NanoClaw or HermesClaw 4. Connect test messaging account 5. Confirm simple message sending and receiving 6. Learn how to check logs 7. Confirm execution again after Mac restart 8. Set up automatic execution 9. Set up security 10. Add one practical automation

The first goal is not "create a cool bot." The first goal is this:

Agent starts on my Mac mini. Receives messages. Sends replies. Can check error logs. Can restart after rebooting.

Once you reach this state, then you can attach features one by one.

17Tip 1: Attach Only One Channel at First

When you attach multiple channels simultaneously, it becomes hard to find the cause when problems occur. At first, keep it simple like this:

Mac mini → NanoClaw → Telegram test bot

Once this structure is stable, then add channels like Slack, Discord, WhatsApp, and WeChat.

18Tip 2: Divide Agent Names by Purpose

Building an "all-purpose bot" from the start makes management difficult. For example, it's better to divide them like this:

personal-assistant trading-alert work-summary test-bot

Dividing like this makes it easy to check logs and immediately find which agent has a problem when issues occur.

19Tip 3: Separate Production and Test Accounts

Beginners must start with test accounts.

Test Telegram bot Test Discord server Test WeChat account Test API keys

It's safer to move to production accounts after testing is done.

20Tip 4: "Getting Replies" and "Operating Safely" Are Different

Beginners often think success means just getting a reply. But in real operation, you need to confirm:

- Are logs recorded normally? - Are errors not repeating? - Have API keys not been exposed? - Does it restart after rebooting? - Are external ports not unnecessarily open? - Is it not executing unexpected commands?

21Tip 5: Even While Waiting for M5, You Can Learn Installation Structure First

Even if you're waiting for M5 Mac mini, you can learn the installation structure first based on M4.

The important basic flow in NanoClaw and HermesClaw operations doesn't change much even if the chip changes:

Terminal use Git use Docker execution Environment variable setup API key management Log checking Automatic execution Security setup

What might change when M5 officially launches is mainly hardware conditions like performance, memory options, port configuration, price, heat output, and power efficiency. The installation flow itself is likely to remain mostly similar unless the official repository changes.

Section 2 · Key Takeaways

Key Takeaways from This Section

NanoClaw
Personal AI agent environment good for connecting to multiple messaging apps
HermesClaw
Bridge for using Hermes / OpenClaw / OpenCode together on WeChat
Mac mini
Personal AI server role available 24 hours
Docker
Safety device for running agents in separate space
Channel
Message entry point like Telegram, Discord, Slack, WeChat
AI Model
Thinking brain that creates answers
Agent
Execution handler who receives messages and processes tasks

The most important sentence beginners should remember is this:

At first, connect only one Mac mini, one tool, and one messaging channel. Then confirm normal operation, logs, restart recovery, and security before expanding features.

3. Mac mini Selection Guide

01Cloud-Centric vs. Local LLM Crossroads

When using Mac mini as an AI agent server, the first distinction you must make is this.

It's the fundamental difference between running a cloud AI provider and running a local LLM. These two require completely different specs.

If you install NanoClaw or HermesClaw, connect it to Telegram, Discord, WhatsApp, WeChat, and outsource actual inference to external providers like Claude, Gemini, OpenAI, or OpenRouter, then Mac mini isn't directly running a massive AI model.

02Mac mini's Role When Cloud-Centric

When using cloud providers as your center, Mac mini mainly does the following:

At this level, more important than CPU or GPU is "adequate memory", "sufficient storage", and "stable network".

03Spec Changes When Running Local LLMs

Conversely, if you're planning to directly install and run local LLMs like Gemma, Qwen, Llama, or Mistral inside Mac mini, and keep running models through runtimes like Ollama, LM Studio, llama.cpp, or MLX, the story changes.

From this point on, memory and memory bandwidth become much more important.

Core Principle

The biggest criterion for determining specs is: "Will I run local LLMs?"

04Memory Decision Guide Summary

The required memory is determined by your usage pattern:

NanoClaw/HermesClaw + external provider
16GB possible, 24GB stable for real use
Multiple agents + Docker + IDE
Realistic from 24GB, 32GB more comfortable
Direct local LLM execution
Start from 32GB, 48GB and above recommended
Continuous local LLM operation
48GB or 64GB and above recommended

05Price Dominates Spec Selection

In Mac mini selection, price is very important. The reason is simple: Mac mini cannot be easily upgraded with more memory after purchase, and Apple's upgrade costs are steep.

The costs of upgrading from 16GB to 24GB, 24GB to 32GB, M4 to M4 Pro, and SSD 512GB to 1TB all accumulate.

Core of price judgment: You must view it not by spec sheet but by cost increase relative to real-world benefit.

06Five Pricing Judgment Principles

Principle 1
If you'll only use NanoClaw/HermesClaw, prioritize memory and SSD over Pro chip
Principle 2
View the 16GB→24GB cost as real-use stability cost
Principle 3
View the 24GB→32GB cost as long-term usage cost
Principle 4
The Pro upgrade cost only makes sense with local LLM, fast external SSD, and multiple Docker
Principle 5
1TB internal + external SSD combination is more practical than large internal SSD

07Five Pricing Judgment Categories

Value for money
The cheapest configuration that handles needed work without strain
Real-use stability
Configuration that suffers less from swap and storage shortage over 2+ years
Long-term operation
Configuration that endures multiple agents, Docker, and local LLM experimentation
Overspending
Buying Pro chip and high memory first when actual usage is light
Insufficient config
Cheap initially but want to buy again after 6 months due to memory or SSD

08NanoClaw/HermesClaw Burden Viewed Realistically

The important point is that NanoClaw and HermesClaw themselves are not massive local LLMs. They connect to messaging apps, execute agents inside containers, and call external AI providers — this structure resembles more of a lightweight coordinator.

Therefore, judging by NanoClaw/HermesClaw alone, Mac mini's burden tends to be relatively light:

09Memory Judgment Based on NanoClaw

You don't need to choose 48GB or 64GB just because "I'll use NanoClaw." For beginners, judge like this:

One NanoClaw + one Telegram/Discord
16GB possible
NanoClaw real use + Docker + CLI tools
24GB recommended
NanoClaw + HermesClaw + automation
32GB recommended
Multiple agents + local LLM experimentation
48GB and above recommended
Continuous local LLM operation
64GB and above consider

10Decide First: Run Local LLMs?

The biggest fork point when choosing Mac mini specs is this:

Will I use AI models only through cloud providers? Or will I directly install and run local LLMs inside Mac mini?

If cloud provider-centric, Mac mini is less of an "AI executor" and more of an "agent operations device." In this case, you can start with 16GB or 24GB.

But if you directly install local LLMs, Mac mini must handle model weights, runtime, KV cache, prompt context, Docker, and agent processes all together. From this point on, memory decisions change.

11Five Memory-Consuming Elements in Local LLMs

Model size
As parameters grow like 12B, 26B, 31B, memory usage increases
Quantization
8-bit, 4-bit models use far less memory than BF16
Context length
The longer documents or conversations you input, the more KV cache grows
Concurrent execution
Changes available memory whether running only one local LLM or together with NanoClaw/Docker/IDE
Runtime
Memory usage varies with environment: Ollama, LM Studio, llama.cpp, MLX, etc.

For local LLMs, you cannot calculate "model file is 7GB so 8GB memory is enough." In reality, runtime, context, system memory, and other apps all go up together.

12Memory Judgment Based on Gemma 4 (1/2)

Gemma 4 is a good reference point in Mac mini selection guides. It's relatively recent and has options from small models to mid-range.

For beginners, understand it this way:

Gemma 4 E2B / E4B
Small, light model. Experimentation possible even on 16GB Mac
Gemma 4 12B
Mid-range model. Possible on 16GB with 4-bit quantization, but 24GB+ more comfortable for real use
Gemma 4 26B A4B
MoE model. Must load entire model in memory, realistic from 32GB and above
Gemma 4 31B
Dense model. Even with 4-bit, 48GB and above safe for comfortable use

13Memory Judgment Based on Gemma 4 (2/2) — Memory Compatibility Table

This table is not "running model alone" but conservatively sized for running NanoClaw/HermesClaw, Docker, browser, terminal, logs, and automation server together.

Gemma 4 E2B
16GB: Possible | 24GB: Comfortable | 32GB+: Comfortable
Gemma 4 E4B
16GB: Possible | 24GB: Comfortable | 32GB+: Comfortable
Gemma 4 12B Q4
16GB: Tight | 24GB: Realistic | 32GB+: Comfortable
Gemma 4 26B A4B Q4
16GB: Not recommended | 24GB: Tight | 32GB: Possible | 48GB: Recommended
Gemma 4 31B Q4
16GB: Not recommended | 24GB: Not recommended | 32GB: Tight | 48GB: Recommended
70B-class Q4
16-32GB: Not recommended | 48GB: Experimentation possible | 64GB: Recommended

14Final Criteria for Local LLM Memory Decision

If you're considering local LLMs, the conclusion is:

Light local LLM experimentation
24GB possible
Comfortable use of Gemma 4 12B class
32GB recommended
Frequent use of 26B-31B class models
48GB recommended
Continuous local LLM operation
64GB and above consider

1516GB Memory: Cheapest Start (1/3)

Advantages:

Disadvantages:

16GB is not a bad choice. But it's a "cheap start" choice, not a "long-lasting" one.

1624GB Memory: Most Realistic Choice (2/3)

Advantages:

Disadvantages:

24GB is the most realistic baseline for beginners. If you can afford the extra cost over 16GB, it's the first option to upgrade.

1732GB Memory: Regret Prevention (3/3)

Advantages:

Disadvantages:

32GB is closer to "regret prevention" than "value for money." For 2+ year equipment, 32GB has less regret than 24GB.

1848GB and 64GB+: Serious Operations

48GB advantages: Suited for multiple agents, Docker, development automation, local LLM experimentation | Much more realistic handling of Gemma 4 26B A4B or 31B Q4 class | Reduced swap burden in long-running operation

48GB disadvantages: Overkill for NanoClaw/HermesClaw only users | If not running local LLM, cost-benefit may be less noticeable

64GB and above: Good for continuous local LLM operation, 31B+ models, long context, vector DB, multiple agents together | But clearly overkill for beginner single agent use

64GB+ is not a beginner recommendation but a local AI server recommendation.

19When M4/M5 Base Model is Right

Recommended users:

Recommended configuration:

Minimum budget
16GB / 512GB
Real-use recommended
24GB / 1TB
Long-term use
32GB / 1TB

For this user, memory and storage matter before Pro chip.

20When M4 Pro / M5 Pro is Right

Recommended users:

Recommended configuration:

Pro entry
24GB / 512GB or 1TB
Full-scale operation
48GB / 1TB
Local LLM-focused
64GB+ / 2TB

Caution: Pro 24GB improves CPU/GPU and ports, not memory headroom significantly. For pure NanoClaw/HermesClaw and Docker, base 32GB may be more practical than Pro 24GB.

21Final Decision Table by Use Case

Find your use case and check recommended configuration:

Installation practice
16GB / 512GB | Cheapest config sufficient
NanoClaw single bot
16-24GB / 512GB | If 24GB cost manageable, choose 24GB
Personal assistant agent
24GB / 1TB | Most balanced
Claude Code + Codex + Gemini CLI
24-32GB / 1TB | 32GB for long-term use
NanoClaw + HermesClaw concurrent
32GB / 1TB | Prioritize memory over Pro
Development automation + many Docker
32-48GB / 1TB | 48GB if many Docker containers
Gemma 4 12B local LLM
24GB possible, 32GB recommended | 32GB for comfortable use
Gemma 4 26B/31B experimentation
48GB recommended | Start considering Pro from here
Continuous local LLM operation
64GB+ | Mac Studio/cloud GPU comparison needed

22Four Realistic Beginner Recommendations (1/2)

For those wanting cheapest start:

Configuration

16GB / 512GB

Condition: Test only one NanoClaw, one messaging app, minimal local LLM, light Docker. Caution: May be insufficient for long-term operation

For most beginners:

Configuration

24GB / 1TB

Reason: Sufficient for real NanoClaw/HermesClaw use, Docker and CLI tools concurrent possible, reduced storage shortage possibility, even small models or 12B class LLM experimentation possible. Conclusion: Most trouble-free real-use config

23Four Realistic Beginner Recommendations (2/2)

For long-term users:

Configuration

32GB / 1TB

Reason: Better long-term stability than 24GB, browser/IDE/Docker/agent concurrent use advantageous, Gemma 4 12B local models handled more comfortably, less regret for 2+ years

For those serious about local LLMs:

Configuration

48GB+ / 1TB or 2TB

Reason: 26B-31B model experimentation possible, vector DB and local search concurrent possible, multiple agents and Docker concurrent operation possible. Conclusion: Start seriously considering Pro from here

For those building local AI server:

Configuration

64GB+ / 2TB+

Caution: From this price point, don't look only at Mac mini but compare with Mac Studio, cloud GPU, separate Linux server

24Purchase Decision Before and After M5 Launch

Before M5 Mac mini official launch, don't be hasty, but if launch is very imminent, judge like this:

Before launch
Confirm price, memory options, SSD options, port config after M5 official announcement, then final decision
Shortly after launch
Core is comparing M4 discount and M5 base price

Specific judgment:

M4 heavy discount
M4 / 24GB or 32GB also excellent choice
Small price difference
M5 / 24GB or 32GB check first
Planning local LLM
M5 Pro / 48GB+ consider
Only NanoClaw/HermesClaw
No need to go M5 Pro
Long-term local AI server
M5 Pro / 64GB+ or Mac Studio comparison

25Chip Selection Final Guide

Just because M5 came out doesn't mean everyone needs M5 Pro. What matters is not the chip name but the work I'll run:

Messaging agent-focused
Base M4/M5 + 24GB or 32GB
Local LLM experimentation
Base M4/M5 32GB or Pro 48GB
Continuous local LLM operation
Pro 64GB+

26This Section's Core Summary

The two biggest mistakes in Mac mini selection are:

Final conclusion:

NanoClaw/HermesClaw only
16GB possible, 24GB recommended
Beginner real use
24GB / 1TB
Long-term personal AI agent server
32GB / 1TB
Local LLM experimentation
48GB+
Continuous local LLM operation
64GB+

27Final Decision by Price

With price included, the conclusion is clearer:

Cheapest choice
16GB
Most realistic choice
24GB
Base model with least regret
32GB
Full-scale AI server
48GB
Long-term local LLM operation
64GB+
NanoClaw/HermesClaw is not as heavy as you think. The moment expensive memory becomes necessary is when local LLM, multiple Docker, vector DB, and development automation all come together.

4. Prerequisites and Installation Preparation

01What You'll Do in This Section

Before installation, let's first organize the following four things.

1
Verify Mac mini basic state
2
Verify essential programs
3
Prepare Claude / Codex / Gemini accounts
4
Prepare API keys and backup folders

Beginners often jump straight to install commands. But without preparation, you'll get stuck at most of these points.

Docker won't start · Git is missing · Node version is old · pnpm is missing · Claude / Codex / Gemini login is broken · Don't know where to put API keys · .env file gets overwritten · Can't restore to original state after installation failure

In this section, we verify whether your Mac mini is in a state ready for installation before actually installing.

02Complete Prerequisites Summary

Required Prerequisites

Hardware

Basic Programs

AI Tools

Accounts

Security Setup

According to official README, NanoClaw's nanoclaw.sh will install Node, pnpm, and Docker if missing, and guide through Anthropic credential registration and first channel pairing. Still, beginners are safer checking the current state before installation rather than relying solely on automatic setup.

03Verify Mac mini Basic State

Open Terminal and enter the following command.

sw_vers

Check: ProductName · ProductVersion · BuildVersion

Verify Apple Silicon:

uname -m

If you see the following result, it's Apple Silicon.

arm64

Check disk free space:

df -h

Check memory:

system_profiler SPHardwareDataType | grep "Memory"

Check chip:

system_profiler SPHardwareDataType | grep "Chip"

Real-World Criteria

Disk free space
Minimum 50GB or more recommended
Memory
16GB possible · 24GB or more recommended · 32GB or above is comfortable
Network
Wired LAN recommended over Wi-Fi

Docker Desktop supports the current macOS version and the two previous major versions, and requires minimum 4GB RAM. On Apple Silicon Macs, Rosetta 2 installation may be recommended for some optional command-line tools.

04Create Working Folder

It's good to keep all AI agent-related files in one place.

Recommended structure:

$ mkdir -p ~/ai-agents $ mkdir -p ~/ai-agents/backups $ mkdir -p ~/ai-agents/logs $ mkdir -p ~/ai-agents/projects $ mkdir -p ~/ai-agents/secrets

Navigate:

$ cd ~/ai-agents

Folder structure:

~/ai-agents ├── backups ├── logs ├── projects └── secrets

Each Folder Purpose

backups
Configuration file backups
logs
Error logs, execution logs
projects
NanoClaw, HermesClaw, test projects
secrets
API key notes, .env samples, authentication records

Practical Tips

05Terminal Basic Usage

Here's only the commands beginners absolutely need to know.

Check current location

pwd

View files in folder

ls

View details:

ls -la

Navigate to folder

cd ~/ai-agents

Go to parent folder

cd ..

View file contents

cat filename

Edit file

nano filename

How to save in nano

Save
Control + O
Confirm
Enter
Exit
Control + X

Stop running command

Control + C

View previous command again

Arrow key ↑

06Verify Homebrew Installation

Homebrew is a package manager frequently used to install terminal programs on macOS. According to official description, Homebrew is a tool for installing needed software that Apple doesn't provide by default, and on Apple Silicon Macs, it installs under /opt/homebrew.

Check:

brew --version

If installed, it looks like this:

Homebrew 5.x.x

Check installation location:

which brew

On Apple Silicon Macs, it typically shows:

/opt/homebrew/bin/brew

If not installed, check the latest install command on the official Homebrew page and install it.

Update after installation:

brew update

Diagnose:

brew doctor

Practical Tips

07Verify Git Installation

Git is a tool for downloading GitHub repositories and managing configuration changes. The official Git site describes it as a free and open-source distributed version control system for handling small to large projects quickly and efficiently.

Check:

git --version

If not installed, install via Homebrew:

brew install git

Check again after installation:

git --version

Set Git user name:

git config --global user.name "YOUR_NAME"

Set Git email:

git config --global user.email "[email protected]"

Verify settings:

git config --global --list

Practical Tips

08Verify Node.js / npm

NanoClaw, Claude Code, Codex CLI, and Gemini CLI often use Node.js or npm-based installation. Node.js is a free open-source cross-platform JavaScript runtime for creating servers, web apps, command-line tools, and scripts.

Check:

node -v npm -v

If not installed, install via Homebrew:

brew install node

Check after installation:

node -v npm -v

Claude Code's npm installation requires Node.js 18 or later, and official documentation doesn't recommend sudo npm install -g. This can cause permission issues and security risks.

Practical Tips

09Verify pnpm

pnpm may be needed for NanoClaw installation or development setup. While the official README says nanoclaw.sh will install pnpm if missing, it's good to check before installation.

Check:

pnpm -v

If missing, install:

npm install -g pnpm

Check again:

pnpm -v

Practical Tips

10Verify Docker Desktop Installation

NanoClaw uses container isolation as important structure. The official site explains that NanoClaw agents run in Docker sandboxes, and each agent group has its own container, memory, and mount range.

Check Docker:

docker --version

Check Docker Compose:

docker compose version

Check Docker running status:

docker info

If normal, Docker server info appears. If you see the following, Docker Desktop isn't running:

Cannot connect to the Docker daemon

In this case:

  1. Launch Docker from Applications folder
  2. Verify Docker icon in top menu bar
  3. After Docker Desktop fully starts, run docker info again

Docker Desktop official documentation instructs to run /Applications/Docker.app after installation on Mac.

Practical Tips

11Verify Python 3 / pip3

HermesClaw includes Python-based files, and the official installation process installs Python dependencies like requests and python-dotenv.

Check:

python3 --version pip3 --version

If not installed, install via Homebrew:

brew install python

Check again:

python3 --version pip3 --version

Practical Tips

12Prepare Claude Code

Claude Code is a tool for using Claude in the terminal. According to official documentation, npm installation uses the following command.

npm install -g @anthropic-ai/claude-code

Verify installation:

claude --version

Run:

claude

After Claude account login, verify:

Check environment variables:

env | grep ANTHROPIC

If ANTHROPIC_API_KEY is set, it may operate via API key method instead of subscription login, so verify if you want subscription-based operation.

Remove from current terminal only:

unset ANTHROPIC_API_KEY

13Prepare OpenAI Codex CLI

Codex CLI is OpenAI's local terminal coding agent. The official GitHub README mentions installation scripts work on Mac or Linux, and npm or Homebrew installation is available. Running codex and logging in with your ChatGPT account enables use within Plus, Pro, Business, Edu, and Enterprise plan ranges.

Installation method example:

curl -fsSL https://chatgpt.com/codex/install.sh | sh

npm method:

npm install -g @openai/codex

Homebrew method:

brew install --cask codex

Verify installation:

codex --version

Run:

codex

When logging in, verify:

Security Note

Recently, unofficial packages impersonating Codex or Gemini CLI have been reported. Use only official OpenAI GitHub or official documentation installation paths for Codex, and only official package names from official google-gemini/gemini-cli repositories or documentation for Gemini CLI.

14Prepare Gemini CLI

Gemini CLI is an open-source AI agent for using Gemini in the terminal. The official GitHub README provides installation methods: npx @google/gemini-cli, npm install -g @google/gemini-cli, brew install gemini-cli.

Run immediately:

npx @google/gemini-cli

Global npm install:

npm install -g @google/gemini-cli

Homebrew installation:

brew install gemini-cli

Run:

gemini

There are three main authentication methods.

  1. Google account login
  2. Gemini API Key
  3. Vertex AI

Official README explains Google account login is suitable for individual developers or Gemini Code Assist license users, while API Key method is suitable for developers needing specific model control or paid tier access.

Gemini CLI usage is summed with Gemini Code Assist agent mode. The official Google quota document shows 1,000 requests/user/day for individual, 1,500 requests/user/day for Google AI Pro, and 2,000 requests/user/day for Google AI Ultra. Additionally, individual, Google AI Pro, and Google AI Ultra users should note that Gemini CLI will stop handling Gemini Code Assist requests starting June 18, 2026.

Practical Tips

15Prepare NanoClaw

NanoClaw is a structure for running personal AI agents inside containers. The official site explains it supports multiple channels like WhatsApp, Telegram, Discord, Slack, Microsoft Teams, iMessage, Matrix, Google Chat, Webex, Linear, GitHub, WeChat, and email, adding channels and providers as needed.

Before NanoClaw installation, verify:

The official Quick Start follows this flow. Actual installation is covered in Section 6.

git clone https://github.com/nanocoai/nanoclaw.git nanoclaw-v2 cd nanoclaw-v2 bash nanoclaw.sh

NanoClaw official README explains nanoclaw.sh guides through named agent and first messaging channel setup on a fresh machine.

Prompt to Give Your Agent Before Installation

Please check my Mac state before installing NanoClaw.

Items to verify:

Items you can't verify precisely, mark as UNKNOWN and don't guess. Only list problems needing resolution before installation.

16Prepare HermesClaw

HermesClaw is a bridge for using Hermes Agent, OpenClaw, and OpenCode together on the same WeChat account. The official README explains /hermes, /openclaw, /opencode, /both, /three commands to switch between agents.

Essential prerequisites for installation:

At least one of the following is required.

  1. OpenClaw + clawbot(openclaw-weixin)
  2. Hermes Agent + WeChat gateway

Official README also states either OpenClaw clawbot or Hermes WeChat gateway must be installed and configured before HermesClaw installation.

Important caution:

The official HermesClaw installation explanation includes systemd service setup. Mac mini's macOS autostart is covered separately using launchd in a later section. Therefore, before running installation scripts blindly on Mac mini, you must read README and install.sh first.

The official installation script performs gateway detection, iLink token extraction, OpenClaw and Hermes base URL patching, Python dependency installation, and systemd service setup.

Prompt to Give Your Agent Before Installation

Please verify the state before installing HermesClaw.

Items to verify:

Items you can't verify precisely, mark as UNKNOWN without guessing.

17Prepare Messaging Accounts

Don't connect real accounts from the start.

Recommended order:

  1. Test Telegram bot
  2. Test Discord server
  3. Test Slack workspace
  4. Real messaging app
  5. WeChat / WhatsApp and sensitive accounts

Choose only one channel for first connection.

Recommendation:

Telegram or Discord

Why:

Avoid:

18Prepare API Keys and Subscription Logins

This guide distinguishes three usage methods.

1
Subscription login method
2
API key method
3
Subscription + API fallback method

Subscription Login Method

Claude Code
Claude account login
Codex
ChatGPT account login
Gemini CLI
Google account login

API Key Method

Claude
ANTHROPIC_API_KEY
OpenAI
OPENAI_API_KEY
Gemini
GEMINI_API_KEY or GOOGLE_API_KEY

Check environment variables:

env | grep -E "ANTHROPIC|OPENAI|GEMINI|GOOGLE"

.env file sample:

cd ~/ai-agents/secrets nano .env.example

Example:

# Claude ANTHROPIC_API_KEY= # OpenAI OPENAI_API_KEY= # Gemini GEMINI_API_KEY= # Google Cloud / Vertex AI GOOGLE_API_KEY= GOOGLE_CLOUD_PROJECT= GOOGLE_GENAI_USE_VERTEXAI=

Practical Tips

19Create .gitignore First

Before installation, create .gitignore so sensitive files don't get pushed to Git.

cd ~/ai-agents nano .gitignore

Content:

# Secrets .env .env.* *.key *.pem *.token secrets/ credentials/ auth/ # Logs logs/ *.log # macOS .DS_Store # Node node_modules/ # Python .venv/ __pycache__/ *.pyc # Docker *.pid # Backups backups/

Practical Tips

20Prepare Backups

Create backup folder before installation.

mkdir -p ~/ai-agents/backups/pre-install

Record current environment:

{ echo "DATE: $(date)" echo "macOS:" sw_vers echo "" echo "ARCH:" uname -m echo "" echo "BREW:" brew --version 2>/dev/null || echo "brew not installed" echo "" echo "GIT:" git --version 2>/dev/null || echo "git not installed" echo "" echo "NODE:" node -v 2>/dev/null || echo "node not installed" echo "" echo "NPM:" npm -v 2>/dev/null || echo "npm not installed" echo "" echo "PNPM:" pnpm -v 2>/dev/null || echo "pnpm not installed" echo "" echo "DOCKER:" docker --version 2>/dev/null || echo "docker not installed" echo "" echo "PYTHON:" python3 --version 2>/dev/null || echo "python3 not installed" echo "" echo "CLAUDE:" claude --version 2>/dev/null || echo "claude not installed" echo "" echo "CODEX:" codex --version 2>/dev/null || echo "codex not installed" echo "" echo "GEMINI:" gemini --version 2>/dev/null || echo "gemini not installed" } > ~/ai-agents/backups/pre-install/environment.txt

Verify:

cat ~/ai-agents/backups/pre-install/environment.txt

Practical Tips

21Complete Pre-Installation Verification Command

Running the command below at once quickly verifies basic state.

echo "=== macOS ===" sw_vers echo "\n=== Architecture ===" uname -m echo "\n=== Disk ===" df -h / echo "\n=== Homebrew ===" brew --version 2>/dev/null || echo "Homebrew not installed" echo "\n=== Git ===" git --version 2>/dev/null || echo "Git not installed" echo "\n=== Node ===" node -v 2>/dev/null || echo "Node not installed" echo "\n=== npm ===" npm -v 2>/dev/null || echo "npm not installed" echo "\n=== pnpm ===" pnpm -v 2>/dev/null || echo "pnpm not installed" echo "\n=== Docker ===" docker --version 2>/dev/null || echo "Docker not installed" docker compose version 2>/dev/null || echo "Docker Compose not available" echo "\n=== Python ===" python3 --version 2>/dev/null || echo "Python3 not installed" pip3 --version 2>/dev/null || echo "pip3 not installed" echo "\n=== AI CLIs ===" claude --version 2>/dev/null || echo "Claude Code not installed" codex --version 2>/dev/null || echo "Codex CLI not installed" gemini --version 2>/dev/null || echo "Gemini CLI not installed" echo "\n=== AI ENV KEYS ===" env | grep -E "ANTHROPIC|OPENAI|GEMINI|GOOGLE" || echo "No AI env vars found"

22Final Pre-Installation Verification Prompt for Your Agent

You can paste the sentence below to Claude Code, Codex, or Gemini CLI.

I'm going to install NanoClaw or HermesClaw on Mac mini.

Please verify my installation readiness state.

Verify based on these items:

  1. macOS version
  2. Apple Silicon presence
  3. Disk free space
  4. Homebrew installation status
  5. Git installation status
  6. Node.js / npm installation status
  7. pnpm installation status
  8. Docker Desktop installation and running status
  9. Python3 / pip3 installation status
  10. Claude Code installation status
  11. Codex CLI installation status
  12. Gemini CLI installation status
  13. ANTHROPIC / OPENAI / GEMINI / GOOGLE environment variable existence
  14. ~/ai-agents folder structure existence
  15. Backup folder existence
  16. .gitignore existence

Mark items you can't verify precisely as UNKNOWN. Don't guess.

Output format:

## Pre-Installation Verification Results

### Passed
-

### Needs Verification
-

### Must Resolve Before Installation
-

### Recommended Next Steps
-

23Beginner Mistakes (1/5)

Mistake 1. Installed Docker but didn't run it

docker --version works but docker info fails sometimes. This likely means Docker is installed but not running.

Check:

docker info

Mistake 2. Mixed API keys and subscription login

Check:

env | grep -E "ANTHROPIC|OPENAI|GEMINI|GOOGLE"

24Beginner Mistakes (2/5)

Mistake 3. Copied installation command from random blogs

AI CLI tools handle account tokens and API keys. Running unauthorized installation scripts risks exposing authentication info. With malicious npm packages impersonating Codex and Gemini CLI sightings, always use official repositories and official documentation for installation.

Mistake 4. Connected real accounts immediately

Start with test accounts first.

Mistake 5. Installed without backup

At minimum, keep these before installation:

25Pre-Installation Checklist

Mac State

Basic Tools

AI CLI

NanoClaw / HermesClaw

Security

Backup

26Key Takeaways from This Section

Pre-installation preparation is more important than installation itself.

Most beginner problems stem from Docker, Node, authentication, API keys, and backup.

Minimum preparation state looks like this:

The practical principle to remember is this:

Before typing installation command, record your Mac's current state and decide which accounts and which provider you'll use.

5. Which Should You Choose: NanoClaw or HermesClaw?

01Conclusion First

For beginners starting out, it's best to start with NanoClaw.

If you're already using Hermes Agent, OpenClaw, or WeChat integration, or if you want to use Hermes, OpenClaw, and OpenCode together on one WeChat account, consider HermesClaw.

First installation
NanoClaw
Want to connect multiple messaging apps
NanoClaw
Want to understand the structure easily
NanoClaw
Want to use Hermes and OpenClaw together on WeChat
HermesClaw
Already using Hermes Agent
Consider HermesClaw
Already using OpenClaw
Consider HermesClaw
Want to add Claude/Codex/Gemini routing for all three providers
NanoClaw or design Provider Router on top of Hermes-based structure

NanoClaw's official site describes NanoClaw as a personal AI agent that safely runs within a container, and notes it supports multiple channels like WhatsApp, Telegram, Discord, Slack, Microsoft Teams, iMessage, Matrix, Google Chat, Webex, Linear, GitHub, WeChat, and email.

HermesClaw is a bridge created to use Hermes Agent and OpenClaw together on the same WeChat account. Its official README explains that HermesClaw becomes a single iLink poller, provides local proxy servers to Hermes and OpenClaw, and provides an ACP bridge to OpenCode.

02What is NanoClaw?

From a beginner's perspective, NanoClaw is a personal AI assistant executor that runs inside my Mac mini.

1User sends message via Telegram / Discord / Slack / WhatsApp, etc.
2NanoClaw receives the message
3Claude Code or connected provider handles the task
4Result is sent back to the messaging app

NanoClaw's official GitHub description calls NanoClaw an AI assistant that safely runs each agent inside its own container. It also says the tool is designed to be lightweight, easy to understand, and easy for users to customize to their needs.

It's good for beginners because:

03What is HermesClaw?

Unlike NanoClaw, HermesClaw is less of a personal AI assistant from the start, and more of a connection tool to use Hermes Agent and OpenClaw together on WeChat.

1WeChat message
2HermesClaw receives it first
3If /hermes command, pass to Hermes Agent
4If /openclaw command, pass to OpenClaw
5If /opencode command, pass to OpenCode
6Result passes back to WeChat

HermesClaw's official README explains that you can choose which agent to send messages to using commands like /hermes, /openclaw, /opencode, /both, and /three.

When HermesClaw is needed is fairly clear.

In other words, beginners don't necessarily need to start with HermesClaw. HermesClaw is more suited to solving connection conflict problems experienced by existing Hermes/OpenClaw/WeChat users.

04Differences at a Glance

Category
Beginner recommendation
NanoClaw: High / HermesClaw: Situation-dependent
Core purpose
NanoClaw: Operate personal AI agent / HermesClaw: Hermes / OpenClaw / OpenCode WeChat bridge
Main channel
NanoClaw: Multiple channels like Telegram, Discord, Slack, WhatsApp / HermesClaw: Primarily WeChat
Structure
NanoClaw: Container-based personal agent / HermesClaw: Single iLink poller + local proxy
Setup difficulty
NanoClaw: Relatively low / HermesClaw: Requires understanding existing Hermes/OpenClaw
Suitable users
NanoClaw: First-time installers / HermesClaw: Existing Hermes/OpenClaw users
Mac mini utilization
NanoClaw: Personal AI server / HermesClaw: WeChat-based multi-agent bridge
Claude/Codex/Gemini routing
NanoClaw: Easy to attach Provider Router / HermesClaw: Can be designed with Hermes structure

In practical terms, you can think of it this way.

NanoClaw
When you want to use a personal AI agent across multiple messaging apps
HermesClaw
When you want to use Hermes, OpenClaw, and OpenCode together on WeChat

05Recommended Order for First-Time Users

Don't install both from the start. The recommended order for beginners is:

  1. Install NanoClaw first
  2. Connect just Telegram or Discord
  3. Test sending and receiving messages
  4. Add Claude / Codex / Gemini provider routing policy
  5. Set up automatic execution and log management
  6. After stabilization, decide if HermesClaw is needed

If you're already using WeChat, Hermes Agent, and OpenClaw, the order is different.

  1. Back up current Hermes / OpenClaw state
  2. Check WeChat gateway status
  3. Verify why HermesClaw is needed
  4. First experiment in test account or test environment
  5. After success, apply to production account

06Selection Criteria Checklist

Answering the questions below makes selection easy.

  1. Am I installing for the first time? → Yes: Prioritize NanoClaw
  2. Do I want to use channels like Telegram, Discord, Slack? → Yes: Prioritize NanoClaw
  3. Must I use WeChat? → Yes: Consider HermesClaw
  4. Am I already using Hermes Agent? → Yes: Consider HermesClaw
  5. Am I already using OpenClaw? → Yes: Consider HermesClaw
  6. Do I want to understand the structure easily and modify it myself? → Yes: Prioritize NanoClaw
  7. Do I want to use Hermes / OpenClaw / OpenCode all on one WeChat account? → Yes: HermesClaw
  8. Do I want to attach Claude / Codex / Gemini routing for all three? → Start with NanoClaw and design Provider Router

07Complete Beginner Example

Situation

Just bought a Mac mini. Have no experience installing AI agents. Want to create a personal assistant on Telegram. Want to use Claude Code, Codex, and Gemini CLI together.

Recommendation

Start with NanoClaw

Reason: Simpler structure • Good for connecting multiple messaging apps • Easy to test with just Telegram initially • Easy to attach Provider Router later

08Trading Support Alert Bot Example

Situation

Price alerts • News summaries • Trading log organization • Risk checklist • Telegram or Discord alerts

Recommendation

Prioritize NanoClaw

Reason: Good for messaging-channel-centric operation • Can start small with one alert bot • Easy to distribute Claude / Codex / Gemini by role

At the beginner stage, start with these features rather than automated trading.

09Example When WeChat is Essential

Situation

Use WeChat as main messaging app. Already using Hermes Agent. Want to use OpenClaw as well. Want to divide agents by command on one WeChat account.

Recommendation

Consider HermesClaw

Reason: HermesClaw's core purpose fits this situation • Can route with commands like /hermes, /openclaw, /opencode • Single iLink poller structure aims to reduce conflict issues

10Development Automation-Focused Example

Situation

Design review with Claude Code • Code modifications with Codex • Repeated tasks with Gemini CLI • Multiple project automation on Mac mini • Task instructions from messaging apps

Recommendation

NanoClaw + Provider Router

Reason: Use NanoClaw as personal agent entrance • Use Claude / Codex / Gemini as providers • Attaching routing policies for task types works well

11Existing OpenClaw User Example

Situation

Already have OpenClaw configuration. Want to migrate to or run alongside Hermes Agent. WeChat integration is important.

Recommendation

Review Hermes Agent migration documentation and consider HermesClaw

Reason: Hermes Agent official docs provide hermes claw migrate guide to bring OpenClaw / Clawdbot setup into Hermes • Can verify existing settings, memory, skills, and API key mapping and migrate them

The Hermes Agent migration documentation covers procedures for bringing OpenClaw or legacy Clawdbot/Moldbot setup into Hermes, config key mapping, and post-migration verification items.

12When to Choose NanoClaw

If many of these apply, NanoClaw is right for you.

Recommended structure when choosing NanoClaw:

1Mac mini
2Docker
3NanoClaw
4Telegram test bot
5Claude Code
6Then add Codex / Gemini

Initial goals:

  1. Run NanoClaw
  2. Receive test messages
  3. Send replies
  4. Check logs
  5. Recover after reboot
  6. Add provider routing

13When to Choose HermesClaw

If many of these apply, consider HermesClaw.

Recommended structure when choosing HermesClaw:

1Mac mini
2HermesClaw
3Hermes Agent
4OpenClaw
5OpenCode
6WeChat command routing

Important cautions:

14Can You Install Both?

It's possible, but not recommended for beginners from the start. Installing both initially makes it hard to identify causes when problems arise.

Confusing aspects when problems occur:

Recommended order:

Beginners
Install NanoClaw only
WeChat users
Install HermesClaw first in test environment
Users needing both
1. Stabilize NanoClaw / 2. Organize logs and automatic startup / 3. Install HermesClaw in separate folder / 4. Check port conflicts / 5. Separate provider routing

15Considering Claude / Codex / Gemini Routing

The core of this guide isn't simply NanoClaw vs HermesClaw. The final goal is this structure.

1Mac mini
2NanoClaw or HermesClaw
3Provider Router
4Claude Code / OpenAI Codex / Gemini CLI
5Return results to messaging app

For beginners, NanoClaw is easier to use as the Provider Router entrance.

NanoClaw
Messaging app entrance role
Provider Router
Assigns work between Claude / Codex / Gemini
Claude Code
Deep analysis
Codex
Code fixes and testing
Gemini CLI
Fast iterative work

HermesClaw is attached when WeChat-side routing is needed.

HermesClaw
Route Hermes / OpenClaw / OpenCode from WeChat
Provider Router
If needed, add Claude / Codex / Gemini selection rules to Hermes-side work policy

16Avoiding Selection Mistakes (1/4)

Mistake 1. Thinking they're the same tool because of similar names

NanoClaw and HermesClaw are not tools with the same purpose.

NanoClaw
Personal AI agent environment
HermesClaw
Bridge to use Hermes / OpenClaw / OpenCode together on WeChat

Mistake 2. Installing both from the start

Installing both initially makes root cause analysis difficult. Beginners install one. After the first tool stabilizes, review the second.

Mistake 3. Trying to install HermesClaw without WeChat

HermesClaw strongly prioritizes WeChat-based Hermes / OpenClaw / OpenCode routing. If you don't need WeChat and have no existing Hermes/OpenClaw environment, it's more natural to review NanoClaw first.

17Avoiding Selection Mistakes (2/4)

Mistake 4. Mixing provider routing with messaging gateway

NanoClaw / HermesClaw
Entrance connecting messaging app and agent
Claude / Codex / Gemini
Provider that processes work
Provider Router
Manager choosing which provider to use

To clarify:

Messaging entrance
NanoClaw or HermesClaw
Work processing
Claude Code / Codex / Gemini CLI
Selection policy
Provider Router

18First Goals After Selection

If you chose NanoClaw, your first goal is this.

1Run NanoClaw
2Connect one test channel
3Receive message
4Send reply
5Check logs
6Recover after reboot

If you chose HermesClaw, your first goal is this.

1Back up existing Hermes / OpenClaw
2Check WeChat gateway status
3Set up HermesClaw test environment
4Test /hermes command
5Test /openclaw command
6Check logs

Never go from first installation to final automation all at once.

  1. Successful message send/receive
  2. Provider connection
  3. Log verification
  4. Automatic execution
  5. Security settings
  6. Real-world automation

19Selection Checklist

NanoClaw is right if:

HermesClaw is right if:

Not ready yet if:

20Key Takeaway from This Section

Beginners start with NanoClaw. Those who must use Hermes / OpenClaw / OpenCode together on WeChat consider HermesClaw.

Make final judgment this way.

Telegram / Discord / Slack focused
NanoClaw
Personal AI assistant introduction
NanoClaw
Trading support alert bot
NanoClaw
Claude / Codex / Gemini routing
NanoClaw + Provider Router
WeChat essential
Consider HermesClaw
Existing Hermes Agent user
Consider HermesClaw
Existing OpenClaw user
Consider HermesClaw or Hermes migration

One sentence for beginners to remember:

Initially connect just one messaging channel with NanoClaw, and consider HermesClaw only when WeChat and Hermes/OpenClaw actually become necessary.

6. NanoClaw Installation

01What We Do in This Unit

In this unit, we install NanoClaw on Mac mini.

The official NanoClaw Quick Start begins installation with the following 3 lines. According to the official README, nanoclaw.sh guides through creating named agents in a new environment, verifying or installing Node / pnpm / Docker, registering Anthropic credentials, building agent containers, and pairing the first channel. The first channel can be chosen from Telegram, Discord, WhatsApp, or local CLI.

Beginner Checklist
Homebrew installed, Git installed, Node.js / npm installed, pnpm installed, Docker Desktop installed and running, Claude Code login status verified, test messaging account prepared, ~/ai-agents folder prepared, backup folder prepared

02Final Check Before Installation

Run the following commands in the terminal.

$ echo "=== Git ===" $ git --version $ echo "\n=== Node ===" $ node -v $ echo "\n=== npm ===" $ npm -v $ echo "\n=== pnpm ===" $ pnpm -v $ echo "\n=== Docker ===" $ docker --version $ docker compose version $ docker info $ echo "\n=== Claude Code ===" $ claude --version

Normal status example: all tools should display a version. Docker should show normal output from docker info, and Claude Code should recognize the claude command.

03Docker Daemon Error Handling

If you see the following, Docker Desktop is not running:

Cannot connect to the Docker daemon

In this case:

  1. Run Docker from the Applications folder
  2. Check the Docker icon in the top menu bar
  3. Wait for Docker Desktop to fully start
  4. Run docker info again

04Choose Installation Location

In this guide, we gather all AI agents in the following folder.

$ mkdir -p ~/ai-agents/projects $ cd ~/ai-agents/projects

Verify current location:

$ pwd

If normal, it should look something like this:

/Users/username/ai-agents/projects

Create the NanoClaw installation folder as nanoclaw-v2.

$ git clone https://github.com/nanocoai/nanoclaw.git nanoclaw-v2 $ cd nanoclaw-v2

Verify the installation folder:

$ ls -la

05Run the Installation Script

The official NanoClaw installation command is as follows.

$ bash nanoclaw.sh

The installation typically goes through the following flow:

  1. Check for required programs
  2. Verify Node / pnpm / Docker status
  3. Register Claude or Anthropic credentials
  4. Build agent container
  5. Set the first agent name
  6. Choose the first messaging channel
  7. Test message connection

According to the official README, if a failure occurs, Claude Code is automatically invoked to diagnose and continue from the stopping point.

06Choose Agent Name During Installation

When prompted for an agent name during installation, keep it simple at first.

Recommended names: personal-assistant, test-bot, trading-alert, work-helper

There is no need to create a fancy name from the start. In practice, short names with clear purposes make logs easier to read.

Names to avoid: my-super-ultra-agent-final-v3, main-real-live-production-bot, everything-bot

07Choose Your First Channel

According to the official NanoClaw README, the first channel can be chosen from Telegram, Discord, WhatsApp, or local CLI.

Recommended order for beginners:

  1. local CLI — No messaging app authentication required, quick verification of installation itself, easy error diagnosis
  2. Telegram — Easy to create test bots, can be separated from actual accounts, suitable for personal alert bots / trading assistant bots
  3. Discord
  4. WhatsApp — High likelihood of connecting to actual personal account, recovery from authentication issues is tedious

08Claude / Anthropic Authentication During Installation

The NanoClaw installation script includes a process for registering Anthropic credentials. Beginners need to distinguish two approaches here.

1. Claude Subscription Login Method

This is the approach of logging into Claude Code with a subscribed account like Claude Pro / Max and using it.

$ claude (inside Claude Code) /status /usage

2. API Key Method

This is the approach of directly registering an Anthropic API key.

$ env | grep ANTHROPIC

If you see the following, the API key is set:

ANTHROPIC_API_KEY=sk-ant-...

If you want to use only subscription login, in the current terminal:

$ unset ANTHROPIC_API_KEY

09Tips for Choosing Authentication Method

Decide first whether you will use Claude subscription or API key.

Mixing the two can result in unexpected charges or authentication confusion.

It is safer to test with subscription login at first and add API fallback later.

10Prompt to Use Right Away If Stuck During Installation

If an error occurs during installation, copy the error message and paste it into Claude Code, Codex, or Gemini as follows.

An error occurred during NanoClaw installation.

My environment: Mac mini Apple Silicon, macOS version: [enter here], installation location: ~/ai-agents/projects/nanoclaw-v2, command executed: bash nanoclaw.sh

Request:

  1. Don't guess the error cause, analyze based on the logs
  2. Distinguish whether it's a Docker issue, Node/pnpm issue, or Claude authentication issue
  3. Tell me verification commands I can run right away
  4. Provide recovery commands, but ask for confirmation before deletion commands
  5. Be careful not to delete configuration files or authentication information that have already been created

11Things to Check After Installation is Complete

Do not use immediately after installation. First, verify the following.

$ pwd $ ls -la

Check Docker containers:

$ docker ps $ docker ps -a $ docker images

Check if log viewing is possible:

$ ls -la $ find . -maxdepth 3 -type f -name "*.log"

12Criteria for Judging Successful Installation

13Send Your First Test Message

Keep the first test short.

Test message: "Hi. If you're working normally now, reply 'NanoClaw test successful'."

Normal response: "NanoClaw test successful"

Next, do a slightly more practical test.

Criteria for normal response: message is received, reply is sent, response doesn't take too long, same error doesn't repeat, no critical errors in logs

14Default Agent Prompt Right After Installation

Once NanoClaw can receive messages, immediately input the following prompt.

You are a personal AI agent running NanoClaw on Mac mini. Your current goal is stability testing, not actual use.

Rules: explain before modifying files, explain the purpose before executing commands, never output API keys, tokens, or passwords, do not guess unverified information and mark as UNKNOWN, do not execute long tasks immediately and ask for confirmation first, if Docker, authentication, or messaging connection errors occur, report the cause separately, if provider selection between Claude / Codex / Gemini is needed, decide which provider to use first

Response format: current judgment, work to execute, things to be careful about, next steps

This prompt is to prevent the test agent from starting arbitrary long and complex tasks right after installation.

15Provider Router Connection is Done After Installation

Don't try to attach Claude / Codex / Gemini 3-way routing immediately after basic NanoClaw installation is complete.

Installation order:

  1. NanoClaw installation
  2. local CLI or Telegram test
  3. Verify message send/receive
  4. Check logs
  5. Verify re-execution
  6. Verify Claude authentication
  7. Verify Codex CLI
  8. Verify Gemini CLI
  9. Add Provider Router policy

Right after installation, input only the following instruction: "Don't start automatic Claude / Codex / Gemini routing yet. First verify that NanoClaw itself operates stably."

16Status Check Prompt After Installation

After installation is complete, send the following sentence to the agent.

Check the status after NanoClaw installation. Items to verify:

  1. Is it currently running
  2. Can it receive messages
  3. Can it send replies
  4. Is the Docker container normal
  5. Are there repeated errors in logs
  6. Is Claude authentication normal
  7. Where are configuration files located
  8. What files need to be backed up
  9. Is it OK to move to the next step

Mark items that cannot be verified precisely as UNKNOWN.

17Backup After Installation

If the installation was successful, back up immediately.

$ mkdir -p ~/ai-agents/backups/nanoclaw-after-install

Save file list from installation folder:

$ cd ~/ai-agents/projects/nanoclaw-v2 $ find . -maxdepth 3 -type f > ~/ai-agents/backups/nanoclaw-after-install/file-list.txt

Save current Docker status:

$ docker ps -a > ~/ai-agents/backups/nanoclaw-after-install/docker-ps-a.txt $ docker images > ~/ai-agents/backups/nanoclaw-after-install/docker-images.txt

Save environment information:

$ ({ echo "DATE: $(date)" echo "PWD: $(pwd)" echo "" echo "Git:" git rev-parse --short HEAD 2>/dev/null || echo "No git commit" echo "" echo "Node:" node -v echo "" echo "npm:" npm -v echo "" echo "pnpm:" pnpm -v echo "" echo "Docker:" docker --version echo "" echo "Claude:" claude --version 2>/dev/null || echo "claude not found" } > ~/ai-agents/backups/nanoclaw-after-install/environment.txt

Verify:

$ ls -la ~/ai-agents/backups/nanoclaw-after-install

Backup right after successful installation is very important. The state at this point becomes the best recovery baseline later.

18Re-execution Test

After installation, you must verify that it can be re-executed after stopping.

Check currently running processes or containers:

$ docker ps

Close the terminal and open it again. Navigate to the installation folder:

$ cd ~/ai-agents/projects/nanoclaw-v2

Check Docker status:

$ docker ps -a

Follow the command guided during installation for how to run NanoClaw. Create a reference file:

$ nano ~/ai-agents/projects/nanoclaw-v2/RUNBOOK.md

19Common Problems and Solutions

Problem 1. git clone fails

Symptom: command not found: git

Solution:

$ brew install git $ git --version

Problem 2. pnpm not found

Symptom: command not found: pnpm

Solution:

$ npm install -g pnpm $ pnpm -v

Problem 3. Permission error

Symptom: permission denied. First check the current location and file permissions:

$ pwd $ ls -la

Beginners should not immediately add sudo. Ask the agent.

20Claude Authentication Error Response

Things to check:

$ claude --version $ claude $ env | grep ANTHROPIC

Sentence to ask the agent:

A Claude or Anthropic authentication error occurred during NanoClaw installation. Check if subscription login method and API key method are mixed. Don't guess, separate verifiable items and UNKNOWN items.

21Things Beginners Should Not Do

Especially do not immediately run the following command after installation failure:

$ rm -rf nanoclaw-v2

When deletion is needed, back up first:

$ mv nanoclaw-v2 nanoclaw-v2-broken-$(date +%Y%m%d-%H%M%S)

22Practical Prompt for NanoClaw Installation

You can also put the following sentence in Claude Code before installation.

I want to install NanoClaw on Mac mini. Installation location: ~/ai-agents/projects/nanoclaw-v2. Official installation commands: git clone https://github.com/nanocoai/nanoclaw.git nanoclaw-v2, cd nanoclaw-v2, bash nanoclaw.sh

Your role: check the environment before I run the installation command, if an error occurs during installation, analyze the cause based on logs, distinguish Docker / Node / pnpm / Claude authentication issues, ask for confirmation before deletion commands, never output API keys or tokens, mark unverified content as UNKNOWN

23Operational Prompt for NanoClaw After Installation

After installation is complete, input the following sentence.

NanoClaw installation is complete. Now do a stability check before actual use.

Things to verify: message receive capability, reply send capability, Docker container status, log location, repeated error presence, Claude authentication status, files to be backed up, whether it's OK to move to the next step

Don't do yet: provider automatic routing, connect actual accounts, automatic execution setup, open external access, activate API fallback

24Completion Criteria

When all items pass, Section 6 is complete.

Installation: cloned from official repository, nanoclaw-v2 folder created, ran bash nanoclaw.sh, installation script progressed to final stage

Execution: Docker Desktop running, verified related container status with docker ps, proceeded with first channel or local CLI test, responded to test message

Authentication: verified Claude Code or Anthropic credential status, distinguished subscription login method from API key method, verified that ANTHROPIC_API_KEY is not inadvertently set

Security: did not expose API keys, did not share .env file, used test accounts instead of actual accounts

Backup: saved file-list.txt after installation, saved docker-ps-a.txt, saved docker-images.txt, saved environment.txt, created RUNBOOK.md

25Key Takeaway of This Section

NanoClaw installation can start with 3 lines according to official standards.

git clone https://github.com/nanocoai/nanoclaw.git nanoclaw-v2 cd nanoclaw-v2 bash nanoclaw.sh

But in practice, the following is more important than 3 lines:

The goal of day one installation is not a finished AI secretary, but creating a state where NanoClaw receives messages, sends replies, and keeps logs.

7. Installing HermesClaw

01What This Section Covers

In this section, before installing HermesClaw on Mac mini, you'll understand the structure and verify whether it can be used alongside Hermes Agent or OpenClaw.

First, an important point: Don't assume HermesClaw is a simple beginner-friendly installation package like NanoClaw. The HermesClaw currently available is more accurately described as a lightweight proxy designed to use Hermes Agent and OpenClaw together on the same WeChat account or iLink account flow.

HermesClaw itself doesn't handle all AI functions. Rather, it's like a connection layer that receives messages and forwards them to the Hermes Agent gateway or OpenClaw gateway.

Goals of this section:

Beginners should read this section not as "a chapter where you must install" but rather as "a chapter to determine whether installation is appropriate."

02Understanding HermesClaw Architecture

HermesClaw is typically easiest to understand with this structure:

1Messaging account
2iLink or gateway layer
3HermesClaw proxy
4Hermes Agent gateway or OpenClaw gateway
5AI agent execution
6Send reply

The key point is that HermesClaw is not "an AI brain."

03What HermesClaw Does and Doesn't Do

What HermesClaw mainly does:

What HermesClaw directly does not do:

The most common point of confusion for beginners: Don't think "Installing HermesClaw = Finishing AI agent installation." A more precise statement is "Installing HermesClaw = Adding a proxy layer to connect Hermes Agent or OpenClaw gateway to a messaging account."

04Understanding the Relationship with Hermes Agent

Hermes Agent is closer to the actual AI agent side.

Key features handled in Hermes Agent:

Basic verification commands after installing Hermes Agent:

$ hermes

$ hermes model

$ hermes tools

$ hermes setup

$ hermes doctor

Messaging gateway verification flow:

$ hermes gateway

$ hermes gateway setup

$ hermes gateway start

$ hermes status

If the hermes command is not recognized, do not install HermesClaw first. You must first resolve Hermes Agent installation and shell path issues.

05Understanding the Relationship with OpenClaw

OpenClaw can be viewed as a personal AI secretary-type gateway / agent environment. Based on the OpenClaw official README, supported channels include WhatsApp, Telegram, Slack, Discord, Google Chat, Signal, iMessage, Matrix, WeChat, and others.

If OpenClaw is already installed, you must verify the following before installing HermesClaw:

$ openclaw --version

$ openclaw gateway status

$ ls -la ~/.openclaw

$ find ~/.openclaw -maxdepth 3 -type f

06Backing Up OpenClaw Configuration

If you have OpenClaw configuration, do not run migration immediately. Back up first:

$ mkdir -p ~/ai-agents/backups/openclaw-before-hermes

$ cp -R ~/.openclaw ~/ai-agents/backups/openclaw-before-hermes/openclaw-backup

Also keep a separate file list:

$ find ~/.openclaw -maxdepth 4 -type f > ~/ai-agents/backups/openclaw-before-hermes/file-list.txt

Practical tip

If you're already actively using OpenClaw, HermesClaw installation is not a "fresh installation" but a "change to the messaging agent structure you're operating." In this case, backup and rollback planning is more important than the installation itself.

07Final Verification Before Installation (1/2)

Run the following commands in the terminal:

$ echo "=== macOS ===" $ sw_vers $ echo "\n=== CPU ===" $ uname -m $ echo "\n=== Shell ===" $ echo $SHELL $ echo "\n=== Git ===" $ git --version $ echo "\n=== Python ===" $ python3 --version $ echo "\n=== pip ===" $ python3 -m pip --version

08Final Verification Before Installation (2/2)

$ echo "\n=== Node ===" $ node -v $ echo "\n=== npm ===" $ npm -v $ echo "\n=== Docker ===" $ docker --version $ docker compose version $ docker info $ echo "\n=== Hermes ===" $ hermes --version 2>/dev/null || echo "hermes not found" $ echo "\n=== OpenClaw ===" $ openclaw --version 2>/dev/null || echo "openclaw not found"

Normal state examples:

If docker info shows an error:

Cannot connect to the Docker daemon
— Docker Desktop is not running.

09What to Check on M4 / M5 Mac mini

On M4 Mac mini, verify the following items based on Apple Silicon:

$ uname -m

If normal, it typically shows like this:

arm64

Items to check for M4:

Items to check after M5 Mac mini official release:

Don't change installation commands just because you see "M5." Unless official documentation requires separate commands for M5 Mac mini, verify based on Apple Silicon macOS standards.

10Installing Hermes Agent First

Before installing HermesClaw, verify that Hermes Agent itself operates normally.

Based on the official README, on macOS / Linux / WSL2, you can begin installation with this command:

$ curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash

After installation, reload shell configuration:

$ source ~/.zshrc

If you're using bash:

$ source ~/.bashrc

Verify Hermes execution:

$ hermes

Right after installation, do not connect messaging accounts. First, run basic diagnostics:

$ hermes doctor

Run setup wizard:

$ hermes setup

Verify model provider:

$ hermes model

Verify tool configuration:

$ hermes tools

Practical tip

HermesClaw makes sense only when Hermes Agent operates normally. Installing HermesClaw when the hermes command doesn't even work doubles the sources of errors.

11First Hermes Agent Test Run

Once Hermes Agent is installed, run a brief test in the terminal:

$ hermes

In the Hermes conversation window or CLI, type this sentence:

Hello. If you're operating normally right now, answer "Hermes Agent test successful."

Normal response example: Hermes Agent test successful

Then run a more practical test:

I'm checking Hermes Agent installation status on Mac mini. I haven't connected messaging accounts yet. Summarize this situation in one sentence.

Normal criteria:

12Configuring Hermes Gateway

Once Hermes Agent operates normally in CLI, next configure the messaging gateway:

$ hermes gateway setup

After configuration, start the gateway:

$ hermes gateway start

Check status:

$ hermes status

Or depending on installed version:

$ hermes gateway status

Check logs:

$ ls -la ~/.hermes

$ find ~/.hermes -maxdepth 4 -type f

Check environment variable file:

$ ls -la ~/.hermes/.env

However, do not share the .env file contents directly.

Practical tip

When the messaging gateway won't start, check authentication status first before code. Authentication state, tokens, account connections, allowed users, and home directory settings frequently cause problems.

13Moving from OpenClaw to Hermes

If you're already using OpenClaw, you can review Hermes Agent's migration feature. Based on the official README, Hermes can detect ~/.openclaw during the hermes setup process and offer migration.

Beginners should not run immediately. Start with dry-run:

$ hermes claw migrate --dry-run

If you want to move only user data excluding sensitive information:

$ hermes claw migrate --preset user-data

Don't use the overwrite option from the start:

$ hermes claw migrate --overwrite

Use this option only after fully understanding it.

14Backup Before Migration

$ mkdir -p ~/ai-agents/backups/hermes-migration-before

$ cp -R ~/.openclaw ~/ai-agents/backups/hermes-migration-before/openclaw

$ cp -R ~/.hermes ~/ai-agents/backups/hermes-migration-before/hermes 2>/dev/null || true

Save current state:

{ echo "DATE: $(date)" echo "PWD: $(pwd)" echo "" echo "Hermes:" hermes --version 2>/dev/null || echo "hermes not found" echo "" echo "OpenClaw:" openclaw --version 2>/dev/null || echo "openclaw not found" echo "" echo "Hermes status:" hermes status 2>/dev/null || echo "hermes status failed" } > ~/ai-agents/backups/hermes-migration-before/environment.txt

Important: The process of moving from OpenClaw to Hermes is not a simple installation. Items like persona, memory, skills, command allowlist, messaging settings, and API keys may be migration targets. Therefore, you must read the dry-run results first and verify what files change.

15Deciding Before HermesClaw Installation

Only review HermesClaw installation when Hermes Agent is normal and OpenClaw or WeChat gateway structure is prepared.

Conditions where you can review HermesClaw installation:

Conditions where you should delay HermesClaw installation:

16Creating HermesClaw Installation Folder

In this guide, HermesClaw-related files go in this folder:

$ mkdir -p ~/ai-agents/projects $ cd ~/ai-agents/projects

Set the installation folder as hermesclaw:

$ mkdir -p ~/ai-agents/projects/hermesclaw $ cd ~/ai-agents/projects/hermesclaw

Verify current location:

$ pwd

Normal example: /Users/username/ai-agents/projects/hermesclaw

Record the current state before installation:

{ echo "DATE: $(date)" echo "PWD: $(pwd)" echo "" echo "Python:" python3 --version echo "" echo "pip:" python3 -m pip --version echo "" echo "Hermes:" hermes --version 2>/dev/null || echo "hermes not found" echo "" echo "OpenClaw:" openclaw --version 2>/dev/null || echo "openclaw not found" echo "" echo "Docker:" docker --version 2>/dev/null || echo "docker not found" } > PREINSTALL-CHECK.txt

Verify:

$ cat PREINSTALL-CHECK.txt

17Installing HermesClaw

The Quick Install in the currently available HermesClaw README guides this command:

$ curl -fsSL https://raw.githubusercontent.com/AaronWong1999/hermesclaw/main/install.sh | bash

However, beginners are recommended to download and review the contents before running external scripts:

$ curl -fsSL https://raw.githubusercontent.com/AaronWong1999/hermesclaw/main/install.sh -o install.sh

Verify file:

$ ls -la install.sh

Check first 80 lines:

$ sed -n '1,80p' install.sh

Grant execute permission:

$ chmod +x install.sh

Execute:

$ bash install.sh

Non-interactive installation options exist, but beginners should not use automatic yes mode from the start.

Practical tip

curl | bash is fast, but can be risky for beginners. The first time, save install.sh as a file, verify what files and configurations it changes, then run it. It's safer that way.

18What to Check During Installation

During HermesClaw installation, these items are typically important:

On Mac mini, systemd on Linux differs from macOS launchd. So if you see systemd-related messages in the installation log, don't assume success right away. On macOS, you may need to configure automatic service startup separately with launchd.

Check ports:

$ lsof -i :19999

$ lsof -i :19998

If either is already in use, don't proceed with installation immediately:

$ lsof -nP -iTCP -sTCP:LISTEN | grep -E '19999|19998|hermes|openclaw'

19Verifying First Run

After installation finishes, first check process status:

$ ps aux | grep -i hermesclaw | grep -v grep

Check Hermes status:

$ hermes status

Check gateway:

$ hermes gateway status 2>/dev/null || hermes status

If you have OpenClaw, check status:

$ openclaw gateway status 2>/dev/null || echo "openclaw gateway status unavailable"

Check ports:

$ lsof -nP -iTCP -sTCP:LISTEN | grep -E '19999|19998'

Check files:

$ find ~/ai-agents/projects/hermesclaw -maxdepth 3 -type f

Find log candidates:

$ find ~/ai-agents/projects/hermesclaw ~/.hermes ~/.openclaw -maxdepth 4 -type f \( -name "*.log" -o -name "*.out" -o -name "*.err" \) 2>/dev/null

Normal judgment criteria:

20Sending Test Message

Based on HermesClaw README, the flow after installation is to restart the gateway and send /whoami from WeChat.

Keep test messages short at first: /whoami

Then test the Hermes Agent side:

Hello. If you've received this message through HermesClaw, answer "HermesClaw test successful."

Normal response example: HermesClaw test successful

Next, run a test closer to actual use:

Summarize the message I sent in one sentence. Message: I'm checking Hermes Agent and HermesClaw connection status on Mac mini, and haven't yet enabled production automation.

Normal criteria:

21Basic Operation Prompt to Add After Installation

When the Hermes Agent or HermesClaw-routed agent can receive messages, add this prompt first:

You're a Hermes Agent-based personal AI agent running on Mac mini. Your current goal is not production use, but testing HermesClaw connection stability.

Rules:

Response format:

This prompt prevents the agent from starting excessive work right after installation.

22Status Check Prompt After Installation

After installation finishes, send this sentence to the agent:

Check status after HermesClaw installation. Items to verify: 1. Whether Hermes Agent is executable, 2. Whether Hermes gateway is running, 3. Whether OpenClaw configuration exists, 4. Whether HermesClaw proxy is running, 5. Whether ports 19998 / 19999 are open as intended, 6. Whether messages can be received, 7. Whether replies can be sent, 8. Whether logs show repeated errors, 9. Whether authentication files or tokens are exposed, 10. What files should be backed up, 11. Whether you can proceed to the next step

Mark items you cannot verify with UNKNOWN.

Output format:

23Backing Up After Installation

If installation succeeds, back up immediately:

$ mkdir -p ~/ai-agents/backups/hermesclaw-after-install

Save installation folder file list:

$ find ~/ai-agents/projects/hermesclaw -maxdepth 4 -type f > ~/ai-agents/backups/hermesclaw-after-install/file-list.txt

Save Hermes configuration file list:

$ find ~/.hermes -maxdepth 4 -type f > ~/ai-agents/backups/hermesclaw-after-install/hermes-file-list.txt 2>/dev/null

Save OpenClaw configuration file list:

$ find ~/.openclaw -maxdepth 4 -type f > ~/ai-agents/backups/hermesclaw-after-install/openclaw-file-list.txt 2>/dev/null

Save port status:

$ lsof -nP -iTCP -sTCP:LISTEN > ~/ai-agents/backups/hermesclaw-after-install/listening-ports.txt

Save environment info:

{ echo "DATE: $(date)" echo "PWD: $(pwd)" echo "" echo "macOS:" sw_vers echo "" echo "CPU:" uname -m echo "" echo "Python:" python3 --version echo "" echo "Node:" node -v 2>/dev/null || echo "node not found" echo "" echo "Docker:" docker --version 2>/dev/null || echo "docker not found" echo "" echo "Hermes:" hermes --version 2>/dev/null || echo "hermes not found" echo "" echo "OpenClaw:" openclaw --version 2>/dev/null || echo "openclaw not found" } > ~/ai-agents/backups/hermesclaw-after-install/environment.txt

Verify:

$ ls -la ~/ai-agents/backups/hermesclaw-after-install

Practical tip

HermesClaw's gateway configuration and token flow easily become entangled. You must preserve file lists, port status, and environment info immediately after successful installation.

24Restart Test

Right after installation, you must verify it restarts and runs again:

Check current state:

$ ps aux | grep -i hermes | grep -v grep

$ ps aux | grep -i hermesclaw | grep -v grep

$ lsof -nP -iTCP -sTCP:LISTEN | grep -E '19998|19999'

Restart Hermes gateway:

$ hermes gateway stop

$ hermes gateway start

Check status:

$ hermes status

How to run HermesClaw follows the method the installation script guided. You must record the run command shown in the installation log:

$ nano ~/ai-agents/projects/hermesclaw/RUNBOOK.md

Example content: # HermesClaw Runbook / ## Installation location: ~/ai-agents/projects/hermesclaw / ## Related configuration: Hermes Agent: ~/.hermes, OpenClaw: ~/.openclaw, HermesClaw: ~/ai-agents/projects/hermesclaw / ## Installation command: curl -fsSL https://raw.githubusercontent.com/AaronWong1999/hermesclaw/main/install.sh -o install.sh / bash install.sh / ## Status check: hermes status / hermes doctor / ps aux | grep hermes / ps aux | grep hermesclaw / lsof -nP -iTCP -sTCP:LISTEN | grep -E '19998|19999'

25Common Problems (1/5) — hermes command not found

Symptom:

command not found: hermes

Check:

$ echo $SHELL

$ echo $PATH

$ ls -la ~/.local/bin

Resolution candidates:

$ source ~/.zshrc

Or:

$ source ~/.bashrc

If still not working, recheck Hermes Agent installation log:

$ find ~ -maxdepth 4 -iname "*hermes*" 2>/dev/null

26Common Problems (2/5) — Python dependency installation failure

Symptom:

ModuleNotFoundError
or
pip: command not found

Check:

$ python3 --version

$ python3 -m pip --version

Resolution candidates:

$ python3 -m pip install --upgrade pip

Install only when required packages are clearly identified:

$ python3 -m pip install requests python-dotenv

However, if the installation script uses a virtual environment, don't install globally—install within that virtual environment.

27Common Problems (3/5) — Port already in use

Symptom:

Address already in use
}

Check:

$ lsof -i :19999

$ lsof -i :19998

Full check:

$ lsof -nP -iTCP -sTCP:LISTEN | grep -E '19999|19998'

Beginners don't immediately kill. Ask the agent like this:

Port conflict occurred during HermesClaw installation. Check result: lsof -i :19999 result: [paste], lsof -i :19998 result: [paste]. Request: 1) Analyze which process uses the port, 2) Distinguish whether it relates to Hermes / OpenClaw / HermesClaw, 3) Provide safe shutdown method instead of kill, 4) Advise which file to check if port needs changing

28Common Problems (4/5) — WeChat / iLink authentication issues

Symptoms:

Check:

$ ls -la ~/.hermes

$ ls -la ~/.openclaw

$ find ~/.hermes ~/.openclaw -maxdepth 5 -type f | grep -Ei 'account|token|weixin|wechat|ilink|env|json'

However, don't share file contents directly. Check by masking:

$ sed 's/=.*/=***REDACTED***/' ~/.hermes/.env 2>/dev/null

Practical tip

Don't try to fix authentication errors by modifying code. Most are account login, token location, gateway configuration, and allowed user issues.

29Common Problems (5/5) — Gateway anomaly after OpenClaw migration

Symptoms:

First verify backup status:

$ ls -la ~/ai-agents/backups/hermes-migration-before

Check OpenClaw backup files:

$ find ~/ai-agents/backups/hermes-migration-before -maxdepth 5 -type f | head -100

Check Hermes configuration:

$ ls -la ~/.hermes

Check OpenClaw configuration:

$ ls -la ~/.openclaw

Beginners don't overwrite immediately. Ask the agent: Gateway problem occurred after OpenClaw to Hermes migration. My check results: hermes status: [paste], ~/.hermes file list: [paste excluding sensitive], ~/.openclaw file list: [paste excluding sensitive], backup location: ~/ai-agents/backups/hermes-migration-before. Request: 1) Distinguish whether it's missing configuration or authentication token, 2) Advise which files to check from original OpenClaw backup, 3) Teach diff or file list comparison before overwriting, 4) Never output tokens or API keys

30What Beginners Should Not Do

  • Don't install HermesClaw first when hermes command doesn't work
  • Don't test immediately with only one production WeChat account
  • Don't repeatedly run curl | bash without verification
  • Don't share .env, token, or account json files directly
  • Don't use kill -9 immediately when port conflict happens
  • Don't migrate without backing up OpenClaw configuration
  • Don't delete ~/.openclaw or ~/.hermes immediately after migration failure
  • Don't confuse systemd guidance with macOS launchd
  • Don't misunderstand HermesClaw as an AI model provider router

    • Especially don't run these commands immediately:

    $ rm -rf ~/.openclaw

    $ rm -rf ~/.hermes

    $ rm -rf ~/ai-agents/projects/hermesclaw

    When deletion is needed, first rename it for safekeeping:

    $ mv ~/ai-agents/projects/hermesclaw ~/ai-agents/projects/hermesclaw-broken-$(date +%Y%m%d-%H%M%S)

    31Practical Prompt for HermesClaw Installation

    Before installation, you can add the following sentence to one of Claude Code, Codex, or Gemini:

    I'm checking whether HermesClaw is installable on Mac mini Apple Silicon. Current goals: Verify Hermes Agent operates normally, back up OpenClaw configuration if it exists, verify HermesClaw prerequisites, check messaging gateway and port conflicts, proceed based on test account, not production account

    My environment: macOS version: [enter], Mac mini chip: M4 / M4 Pro / M5 official release to be confirmed, installation location: ~/ai-agents/projects/hermesclaw, Hermes Agent in use: [yes/no/UNKNOWN], OpenClaw in use: [yes/no/UNKNOWN], WeChat or iLink account prepared: [yes/no/UNKNOWN]

    Your role: Verify environment before running installation commands, distinguish Hermes Agent / OpenClaw / HermesClaw problems, check port 19998 / 19999 conflicts, guide dry-run first if migration is needed, ask confirmation before deletion commands, never output API keys, tokens, cookies, or session values, mark unverified content as UNKNOWN

    First tell me in order what verification commands I should run.

    32Operation Prompt After HermesClaw Installation

    After installation completes, use this sentence:

    HermesClaw installation is complete. Now do stability verification before production use.

    Things to check: Hermes Agent executability, Hermes gateway status, OpenClaw configuration existence, HermesClaw proxy running status, ports 19998 / 19999 status, message receipt capability, reply send capability, log location, repeated error presence, authentication file exposure risk, files needing backup, whether to proceed to next step

    Don't do yet: Expand production account connection, automatic provider routing, automatic execution setup, open external access, enable API fallback, delete OpenClaw configuration, migration overwrite

    Output format: ## HermesClaw Post-Installation Check Results / ### Normal —, ### Needs verification —, ### Risk —, ### Don't do now —, ### Next steps —

    33Installation Completion Criteria

    Section 7 is complete when you pass all of these items:

    Before installation

    Hermes Agent

    OpenClaw

    HermesClaw

    Security

    Backup

    34Key Takeaway From This Section

    HermesClaw is closer to a proxy layer connecting Hermes Agent and OpenClaw gateway flow than an AI agent body itself.

    It's safe to set the installation order like this:

    1. Install Hermes Agent
    2. Test hermes CLI
    3. Run hermes doctor
    4. Configure hermes gateway
    5. Check OpenClaw usage
    6. Back up OpenClaw configuration
    7. Check ports before HermesClaw installation
    8. Install HermesClaw
    9. Verify /whoami or test message
    10. Organize logs and backups

    One sentence beginners should remember:

    The goal on your first day of HermesClaw installation is not a complete automation, but verifying that Hermes Agent and gateway safely exchange messages.

    After finishing this section, don't immediately move to automatic execution or expand production account connections. The next step in Section 8 is to validate process, logs, message send/receive, API calls, and post-reboot execution one by one based on "What to verify after first run."

    8. Must-Check Items After First Run

    01What This Section Does

    This section covers essential items you must verify after first running NanoClaw or HermesClaw.

    Successful installation usually means:

    But operational readiness requires many more checks:

    Beginners should view this section not as "what to read when problems happen" but as "a checklist you must pass before actual use."

    02First, Identify How It's Running

    NanoClaw, Hermes Agent, OpenClaw, and HermesClaw may have different execution structures, so you must first identify what you're running.

    Possible execution methods are:

    First, check the overall status at once:

    echo "=== Current location ===" pwd echo "\n=== Running Docker containers ===" docker ps echo "\n=== All Docker containers ===" docker ps -a echo "\n=== Hermes status ===" hermes status 2>/dev/null || echo "hermes status unavailable" echo "\n=== Related processes ===" ps aux | grep -Ei 'nanoclaw|hermes|openclaw|claw|gateway' | grep -v grep

    This command is for observing current state, not for solving problems.

    Field Tip

    The most dangerous misconception after first run is thinking "the command finished, so it must be running." In reality, installation commands may have completed, but gateways or containers might be shut down.

    03Verify Process is Running — Docker-Based

    NanoClaw can use container-based architecture, so first verify Docker status:

    docker ps

    docker ps shows only running containers. To see stopped containers too, run:

    docker ps -a

    Normal examples look similar to this:

    STATUS
    Up ... | healthy | maintained for extended time
    Warning state
    Exited | Restarting | stuck at Created | Up time resets every few seconds

    To check if container keeps restarting, monitor continuously:

    watch -n 2 docker ps -a

    If macOS lacks watch, check repeatedly this way:

    while true; do date docker ps -a sleep 2 clear done

    To stop, press Ctrl + C.

    04Verify Process is Running — Docker Compose & Gateway

    If using Docker Compose, check the installation folder:

    ls -la | grep -Ei 'compose|docker-compose'

    Verify Compose status:

    docker compose ps

    If using Hermes gateway, check status first:

    hermes status

    Verify gateway configuration:

    hermes gateway status 2>/dev/null || hermes status

    When you need to start Hermes gateway directly:

    hermes gateway start

    If using OpenClaw, verify with:

    openclaw gateway status

    When you need to run directly in debug mode, stop existing gateway first:

    openclaw gateway stop

    Then run in foreground debug mode:

    openclaw gateway --port 18789 --verbose

    This method is for problem analysis. For 24-hour operation, you need separate daemon or auto-startup configuration.

    05Verify Logs Accumulate Normally

    Logs are not "things to check when problems exist" but "establish normal operation baseline." After first run, always check logs.

    Check Docker container logs:

    Verify running container name, then query it. Assuming container name is nanoclaw-agent:

    docker logs --tail 100 nanoclaw-agent

    To view in real-time:

    docker logs --tail 100 --follow nanoclaw-agent

    Check Docker Compose logs:

    If using Compose, run from project folder:

    docker compose logs --tail 100

    Real-time check:

    docker compose logs --tail 100 --follow

    Criteria for normal logs:

    Normal signal
    service started | gateway listening | connected | message received | message sent | auth ok | ready | no repeated errors
    Warning signal
    authentication failed | invalid token | missing API key | rate limit | permission denied | address already in use | cannot connect to Docker daemon | module not found | restart loop
    Log judgment tip

    Seeing one error word in logs doesn't immediately mean failure. You must check if the same error repeats, if message send/receive actually fails, and if process dies.

    06Verify Can Receive Messages

    Message reception verification comes before "whether agent thinks well." Don't send complex requests initially.

    Local CLI test:

    NanoClaw or Hermes Agent may offer local CLI. Check with local CLI first if available.

    Test message: "Hi. If you received this message, just reply 'Reception test successful.'"

    Expected response: "Reception test successful."

    This test's purpose is not to verify model performance but to verify:

    Messaging app test:

    From messaging app, send very short message first: "ping" or "Test. If you got it, reply with 'pong'."

    If no response, check in this order:

    If received but no reply:

    If there's reception log but no reply, problem scope narrows. Possible causes are model provider call failure, API key error, rate limit, agent internal error, outbound delivery error, etc.

    If Docker-based, separate inbound and outbound logs:

    docker logs --since 10m container-name | grep -Ei 'receive|received|inbound|send|sent|outbound|error|fail'

    07Verify Can Send Messages

    Message sending creates more problems than receiving. If receiving works but sending doesn't, cause might be messaging channel permission issues rather than agent itself.

    NanoClaw send test:

    Common test sentence: "Reply exactly to the following sentence. NanoClaw send test successful"

    Expected response: "NanoClaw send test successful"

    Normal judgment criteria:

    Hermes Agent send test:

    If using Hermes gateway, check gateway status first:

    hermes status

    Send this from messaging app: "This is Hermes send test. If you got it, reply 'Hermes send test successful.'"

    OpenClaw send test:

    OpenClaw provides openclaw message send examples in documentation. Actual target value varies by connected channel and account settings:

    openclaw message send --target target-id --message "Hello from OpenClaw"

    Beginners should not send to actual targets initially. Test with test account, test chat room, DM with yourself, or ops-only alert channel first.

    If message sends multiple times:

    If same reply arrives multiple times, immediately stop automation tests and verify:

    ps aux | grep -Ei 'nanoclaw|hermes|openclaw|gateway' | grep -v grep

    Possible causes are duplicate gateway execution, Docker container and local process running simultaneously, launchd auto-run and manual run overlap, same messaging account viewed by two agents simultaneously, retry logic interpreting failure as success, etc. In this case, resolve duplicate execution first before adding features.

    08Verify API Calls Work Normally

    API call verification is not the stage to check "is model smart." First, distinguish:

    Subscription login method
    Claude Code, ChatGPT/Codex, Gemini CLI etc. use login session | must verify CLI status command or provider-specific login status
    API key method
    ANTHROPIC_API_KEY, OPENAI_API_KEY, GEMINI_API_KEY etc. use environment variables or config files | must verify key existence, permissions, rate limit, billing status

    Verify environment variables:

    Check if API keys are set unintentionally:

    env | grep -Ei 'ANTHROPIC|OPENAI|GEMINI|GOOGLE|API_KEY|TOKEN'

    Verify Claude Code subscription login:

    If using Claude Code, first verify CLI runs:

    claude --version

    Check status inside Claude Code:

    /status

    Verify Anthropic API key method:

    Only verify if API key exists (don't print value):

    test -n "$ANTHROPIC_API_KEY" && echo "ANTHROPIC_API_KEY is set" || echo "ANTHROPIC_API_KEY is not set"

    API call test uses very small requests. Normal criteria are: HTTP response arrives, not auth error, not rate limit error, and response body contains model output.

    API normal judgment criteria:

    09Verify Runs Again After Reboot

    Auto-run after reboot must be verified before actual use. However, this section doesn't set up new auto-run. We only verify "whether current installation survives reboot."

    Save state before reboot:

    Save current state to file before rebooting:

    mkdir -p ~/ai-agents/checks/after-first-run

    Save Docker state:

    docker ps -a > ~/ai-agents/checks/after-first-run/docker-ps-a-before-reboot.txt

    Save process state:

    ps aux | grep -Ei 'nanoclaw|hermes|openclaw|gateway' | grep -v grep > ~/ai-agents/checks/after-first-run/process-before-reboot.txt

    Save port state:

    lsof -nP -iTCP -sTCP:LISTEN | grep -Ei '18789|19998|19999|nanoclaw|hermes|openclaw' > ~/ai-agents/checks/after-first-run/ports-before-reboot.txt 2>/dev/null

    Reboot Mac:

    Before rebooting, verify no installation is in progress, important edit files are saved, and messaging test duplicate sends are stopped:

    sudo shutdown -r now

    Beginners can also use Apple menu → Restart if uncertain.

    Verify status after reboot:

    After reboot, open terminal and check status again:

    docker ps -a > ~/ai-agents/checks/after-first-run/docker-ps-a-after-reboot.txt
    ps aux | grep -Ei 'nanoclaw|hermes|openclaw|gateway' | grep -v grep > ~/ai-agents/checks/after-first-run/process-after-reboot.txt

    Compare files:

    diff -u ~/ai-agents/checks/after-first-run/docker-ps-a-before-reboot.txt ~/ai-agents/checks/after-first-run/docker-ps-a-after-reboot.txt

    Differences don't automatically mean failure. What matters is whether necessary gateway restarted, necessary containers are Up again, can receive messages, can send messages, auth didn't drop after reboot, and logs don't show repeated restart failures.

    Verify Docker auto-restart:

    docker inspect --format '{{.Name}} {{.HostConfig.RestartPolicy.Name}}' $(docker ps -aq)

    If showing no, Docker might not auto-revive when it restarts. This section doesn't change settings right away. Auto-restart configuration is covered in section 10.

    10After First Run Completion Checklist

    When all items below pass, section 8 is complete:

    Process

    Logs

    Messages

    API and Reboot

    11What Beginners Must Not Do

    Especially don't run these commands immediately:

    docker rm -f $(docker ps -aq)
    rm -rf ~/.hermes
    rm -rf ~/.openclaw
    rm -rf ~/ai-agents/projects

    When deletion is necessary, back up or rename first:

    mv problem-folder problem-folder-broken-$(date +%Y%m%d-%H%M%S)

    12Core Summary of This Section

    After first run, what to verify is not "was installation successful" but "is it ready for operation."

    The most important verification order is:

    1. Is process alive?
    2. Is gateway running?
    3. Are logs accumulating?
    4. Can receive messages?
    5. Can send messages?
    6. Are API calls normal?
    7. Does it resurrect after reboot?
    Actual AI agent use starts not when first reply arrives, but after you verify that message receive, send, logs, and API calls all work normally even after reboot.

    After passing section 8, next step is not auto-run setup. You must first understand subscription, usage limits, and uninterrupted operation management in section 9. Only after agent operates stably and you decide how to stop on limit overflow should you set up auto-run in section 10.

    9. GPT · Claude Code · Gemini Role-Separated AI Development Operating Guide

    01The Core Purpose of This Unit

    This unit is not simply about how to alternate between multiple AI tools.

    The purpose is as follows:

    GPT / Codex
    Code strategy analysis, logic validation, Claude task result review, modification instruction writing
    Claude Code
    Codebase analysis, actual code writing, file modification, test execution, refactoring application
    Gemini
    UI/UX design review, screen composition ideas, document structure organization, design description writing, visual improvement suggestions

    There are 7 important principles:

    1. Do not have Claude write code directly
    2. Have Claude analyze code structure and problems first
    3. GPT / Codex reviews Claude's analysis
    4. GPT / Codex creates better modification instructions
    5. Claude handles final code writing and file modification
    6. Gemini is used for design and visual structure assistance
    7. Do not speculate about unverified performance, limits, and internal operations

    02Basic Role Division

    GPT / Codex
    Code strategy analysis, logic error review, Claude-written plan validation, re-instruction writing for Claude, test strategy design, refactoring direction review
    Claude Code
    Direct codebase exploration, actual file modification, bug fixing, test execution, refactoring application, change summary
    Gemini
    UI/UX design ideas, screen composition review, user flow improvement, document design, markdown structure organization, visual representation improvement

    Key constraint: Gemini is not used as the final decision-maker for important code logic judgment. Complex code strategy and logic validation are handled by GPT / Codex. Actual code writing and file changes are handled by Claude Code.

    03Standard Work Flow

    In practice, use the following flow as the baseline:

    1. Claude Code reads the codebase and analyzes the problem
    2. Claude Code does not modify immediately and only writes an analysis report
    3. GPT / Codex reviews Claude's analysis
    4. GPT / Codex checks for logic errors, omissions, and risk factors
    5. GPT / Codex writes the final modification instructions for Claude
    6. Claude Code modifies the actual code based on those instructions
    7. Claude Code runs tests
    8. GPT / Codex reviews the change results again
    9. Gemini assists only with UI/UX or document design as needed

    The essence of this flow is this:

    Claude is the hands. GPT / Codex is the strategist. Gemini is the designer.

    04Agent Basic Operating Prompt

    Insert the following sentence into the agent's basic operating rules:

    You are an AI development router that uses GPT / Codex, Claude Code, and Gemini together. Your goal is to assign the user's work to the safest and most efficient provider. Roles are divided as follows. GPT / Codex: - Code strategy analysis - Logic validation - Modification direction design - Claude task result review - Re-instruction writing for Claude Claude Code: - Codebase exploration - Actual code writing - File modification - Test execution - Refactoring application - Change summary reporting Gemini: - UI/UX design review - Screen structure suggestions - Document design - Visual representation improvement - Light draft writing When receiving a task, do not execute immediately. First decide: 1. Is this a code strategy task 2. Is actual file modification needed 3. Is design judgment needed 4. Is logic validation needed 5. Which provider to use first 6. Who is the final execution provider Basic principles: - Analyze before code modification - Do not assign analysis and execution to the same provider immediately - GPT / Codex reviews Claude's analysis content - Claude executes GPT / Codex's re-instruction - Gemini is used primarily for design and visual structure - Mark unconfirmed usage and limits as UNKNOWN - Use API fallback that may incur additional costs only after user approval - Do not reuse accounts or providers for the purpose of limit circumvention - State the reason for provider selection in one line before executing important tasks

    05Standard Commands for Code Work

    When the user assigns code work, say it like this:

    Do not modify this immediately. Handle this in 3 steps. Task: [Enter task content here] Procedure: Step 1: Claude Code - Read the codebase and analyze the root cause of the problem. - Do not modify. - Organize related files, root cause candidates, and risk factors. Step 2: GPT / Codex - Review Claude's analysis. - Find logic errors and missing possibilities. - Create a safer modification strategy. - Write the final modification instructions for Claude. Step 3: Claude Code - Modify actual files based on GPT / Codex's instructions. - Run tests after modification. - Report changed files and test results. Rules: - Always show files to be modified before modification. - Proceed with large changes only after my confirmation. - Do not speculate on unconfirmed information; mark as UNKNOWN.

    06Claude First Analysis Commands

    Have Claude Code analyze only the codebase first. Goal: [Problem or feature description] What Claude should do: 1. Find related files 2. Explain the current code flow 3. Organize root cause candidates 4. Organize modifiable points 5. Mark dangerous change points 6. Organize items to be tested Prohibitions: - Do not modify files yet - Do not confirm root cause through speculation - Do not suggest large-scale refactoring first - Mark unconfirmed information as UNKNOWN Output format: [Claude First Analysis] Related files: Root cause candidates: Modification candidates: Risk factors: Items requiring testing: Questions that require GPT / Codex review:

    07GPT / Codex Review Commands

    Have GPT / Codex review the following Claude Code analysis. Content to review: [Paste Claude analysis] What GPT / Codex should do: 1. Find logic errors in Claude's analysis 2. Find missing root cause candidates 3. Review whether the modification direction is excessive 4. Judge whether resolution is possible with smaller changes 5. Supplement testing strategy 6. Write final modification instructions for Claude Output format: [GPT / Codex Review] Claude's analysis evaluation: Missing possibilities: Logic risks: Recommended modification strategy: Modification scope: Testing strategy: [Final Instructions for Claude]

    08Claude Final Code Writing Commands

    Based on the following GPT / Codex final instructions, have Claude Code modify the actual code. Final instructions: [Paste GPT / Codex instructions] Claude Code rules: 1. Do not modify beyond the scope of instructions. 2. Show the list of files to be changed before modification. 3. Briefly explain change reason for each file. 4. Run tests after actual modification. 5. Mark as UNKNOWN or BLOCKED if unable to run tests, with reason. 6. Summarize modification results focusing on diff. Output format: [Pre-Modification Plan] Files to change: Reason for change: Risk: [Modification Results] Files changed: Core changes: Test results: Remaining problems: Additional verification needed:

    09Gemini Design Review Commands

    Gemini is used specialized for design and visual structure.

    Have Gemini review the design of the following screen or document. Target: [Screen description / Document / UI code / Markdown] What Gemini should do: 1. Evaluate whether it is easy to understand when first seen by users 2. Review whether information placement is natural 3. Suggest improvements for button, input field, card, table, spacing structure 4. Find inconvenient points on mobile and desktop 5. Change wording to be clearer 6. Suggest design improvements focused on description rather than code Prohibitions: - Do not judge core business logic - Do not judge security logic - Do not judge complex state management structure - Do not write final code modification instructions Output format: [Gemini Design Review] Good points: Inconvenient points: Improvement suggestions: Priority: UI modification requests for Claude:

    10Code + Design Mixed Work Flow

    When creating UI features, use the following order:

    1Claude Code Analyze current UI code structure, understand related components and state flow, do not modify yet
    2GPT / Codex Organize feature requirements into code strategy, review state management · API connection · exception handling, write implementation instructions for Claude
    3Gemini Review screen composition, button placement, user flow, write improvements for wording and visual structure
    4Claude Code Implement actual code combining GPT / Codex instructions and Gemini design requests, modify files, run tests
    5GPT / Codex Review final diff, confirm logic errors and missing exception handling

    Copy-paste command:

    Handle this UI feature in the following order. Task: [UI feature description] Step 1 Claude: - Analyze current UI code and related files. - Do not modify yet. Step 2 GPT / Codex: - Review Claude's analysis. - Create state management, API, exception handling strategy. - Write implementation instructions for Claude. Step 3 Gemini: - Review screen composition and user flow. - Write design improvement suggestions. Step 4 Claude: - Modify actual code based on GPT / Codex's implementation instructions and Gemini's design improvements. - Test after modification. Step 5 GPT / Codex: - Logically review the final change content.

    11Provider Selection Criteria

    When to use Claude Code first
    When you need to read the codebase structure, when you need to understand relationships between multiple files, when actual file modification is needed, when test execution is needed, when refactoring application is needed
    When to use GPT / Codex first
    When implementation strategy is unclear, when Claude's analysis needs review, when logic gaps are a concern, when test strategy is needed, when design judgment before large changes is needed
    When to use Gemini first
    When UI/UX screen composition is the core, when landing page wording is needed, when document structure needs to be organized nicely, when card · table · button · section placement is important, when design draft is needed

    12Quota Saving Mode

    From now on, operate in quota saving mode. Role limitations: GPT / Codex: - Use only for code strategy review and logic validation - Reduce lengthy explanations and provide only core judgment Claude Code: - Use only when actual code modification is needed - Do not use extensively for tasks requiring only analysis - Always narrow down scope before modification Gemini: - Use only for design, document structure, and short drafts - Do not use for complex code judgment Common rules: - Mark unknown provider usage as UNKNOWN. - Do not execute large-scale tasks automatically. - Ask first if additional costs may occur. - Record all provider switch reasons in one line.

    13Provider Judgment Command Before Task

    Before handling this task, first divide provider roles. Task: [Task content] Judgment criteria: - Codebase analysis → Claude Code - Code strategy and logic validation → GPT / Codex - Actual file modification → Claude Code - UI/UX and design review → Gemini - Final logic review → GPT / Codex Output format: Task type: 1st provider: Review provider: Execution provider: Design provider: Selection reason: Quota status: Execution order:

    14Real Example: Login Error Fix

    User command:

    My project has a problem where the session is not maintained after login. Do not modify immediately. Handle this using the following flow. 1. Claude Code analyzes related files. 2. GPT / Codex reviews Claude's analysis. 3. GPT / Codex writes final modification instructions. 4. Claude Code modifies the actual code. 5. Claude Code runs tests. 6. GPT / Codex reviews the final changes. Caution: - Show files to be modified before modification. - Always verify risks related to authentication, cookies, sessions, and environment variables.

    Example of good response:

    Task type: Authentication bug fix 1st provider: Claude Code Review provider: GPT / Codex Execution provider: Claude Code Design provider: Not used Selection reason: This task requires codebase analysis and actual file modification, so Claude Code handles both analysis and execution. GPT / Codex reviews the possibility of missing session logic, making this approach safer. Execution order: 1. Analyze authentication-related files with Claude Code 2. Review analysis with GPT / Codex 3. Generate modification instructions for Claude 4. Modify with Claude Code 5. Run tests 6. Final review with GPT / Codex

    15Real Example: Dashboard UI Improvement

    User command:

    I want to improve the UI of my trading dashboard. Handle this using the following flow. 1. Claude Code analyzes the current UI component structure. 2. Gemini reviews screen composition and user flow. 3. GPT / Codex reviews implementation strategy and state management risks. 4. Claude Code modifies the actual code. 5. GPT / Codex reviews the final changes. Design criteria: - Position status should be visible at a glance - Risk alerts should be shown first - Core information should not be squeezed on mobile - Structure and priority should be improved before colors

    Example of good response:

    Task type: UI/UX improvement + code modification 1st provider: Claude Code Design provider: Gemini Strategy review provider: GPT / Codex Execution provider: Claude Code Selection reason: Claude Code reads the current UI code structure, Gemini reviews screen layout and information priority, GPT / Codex validates state management and implementation risks, making this flow appropriate.

    16Real Example: Refactoring Task

    Do not modify this refactoring task immediately. Proceed in the following order. Task: [Refactoring target description] Step 1 Claude Code: - Analyze current structure - Confirm duplicate code - Confirm dependencies - Propose modification scope - Do not modify yet Step 2 GPT / Codex: - Review Claude's analysis - Judge whether refactoring is excessive - Break down into small change units - Write testing strategy - Write final instructions for Claude Step 3 Claude Code: - Apply only 1st refactoring - Run tests - Report changes Step 4 GPT / Codex: - Review change results - Judge whether to proceed with next refactoring step

    17Final Review Checklist

    After completing the task, have GPT / Codex do a final review using the following criteria. Review items: 1. Did it satisfy the original requirements 2. Were there unnecessary file modifications 3. Did it touch risky logic like authentication, payment, data deletion, order execution 4. Was testing executed 5. If testing failed, was the failure reason explained 6. Was exception handling not omitted 7. If there are UI changes, were Gemini design reviews reflected 8. Is additional modification needed Output format: [Final Review] Requirements satisfaction: Change scope: Risk factors: Test results: Remaining problems: Additional recommended tasks:

    18Operating Rules for Trading Assistant Agent

    You are the development router for a trading assistant agent. Provider roles: GPT / Codex: - Strategy logic review - Risk calculation logic validation - Order condition logic review - Backtest interpretation review - Claude modification validation Claude Code: - Actual code writing - Strategy code modification - Backtest script modification - Test execution - Log checking Gemini: - Dashboard UI design - Risk card composition - Alert screen composition - Report layout - Trading journal template design Mandatory safety rules: - Do not automatically execute buy and sell orders. - Do not give withdrawal permissions to exchange API keys. - Always go through GPT / Codex review before modifying live trading logic. - Do not confirm order quantity, leverage, stop-loss, take-profit calculation logic with Claude alone. - Do not use Gemini for trading judgment or order logic validation.

    19Daily Operating Routine

    Morning start command:

    Before starting today's work, check the status of GPT / Codex, Claude Code, and Gemini. Items to check: - Login status - Execution availability - Recent errors - Usage quota - Additional cost possibility - Recommended role for today Mark items unable to be checked as UNKNOWN. At the end, summarize today's basic routing. Format: GPT / Codex: - Status: - Usage: - Role for today: - Cautions: Claude Code: - Status: - Usage: - Role for today: - Cautions: Gemini: - Status: - Usage: - Role for today: - Cautions: Today's basic flow: 1. 2. 3.

    Command before task:

    Do not execute this task immediately. First divide providers. - Analysis: - Strategy review: - Actual code modification: - Design review: - Final review: Explain the reason for each provider selection in one line, then proceed.

    End of day command:

    Summarize today's work by provider. Format: - Tasks reviewed by GPT / Codex - Tasks modified by Claude Code - Tasks designed by Gemini - Tasks involving provider switching - Tasks postponed due to quota - Operating rules to improve tomorrow

    20Final Fixed Prompt

    Use this sentence as the agent's fixed operating prompt.

    You are an AI development router that uses GPT / Codex, Claude Code, and Gemini together. The basic roles are as follows. GPT / Codex: - Code strategy analysis - Logic validation - Claude analysis review - Re-instruction writing for Claude - Final change review Claude Code: - Codebase analysis - Actual code writing - File modification - Test execution - Refactoring application Gemini: - UI/UX design review - Screen composition suggestions - Document design - Visual improvement proposals Task handling principles: 1. Do not have Claude modify code alone directly. 2. Claude first analyzes the codebase. 3. GPT / Codex reviews Claude's analysis. 4. GPT / Codex creates the final modification instructions for Claude. 5. Claude modifies the actual code. 6. GPT / Codex reviews the final changes. 7. For tasks involving design, Gemini writes UI/UX improvement suggestions. 8. Do not use Gemini as the final validator for complex code logic or trading judgment. 9. If unknown about usage or quota status, mark as UNKNOWN. 10. Use fallback that may incur additional costs only after user approval. 11. Do not reuse providers or accounts for the purpose of quota circumvention. 12. State the reason for provider selection before executing important tasks. Basic response format: Task type: 1st analysis provider: Strategy review provider: Execution provider: Design provider: Final review provider: Selection reason: Quota status: Execution order:

    21Core Summary of This Unit

    First principle
    Do not entrust code directly to Claude
    Second principle
    Claude reads first, GPT / Codex judges, Claude executes again
    Third principle
    Gemini handles design and visual structure

    Beginners need only remember these 3 sentences.

    1
    Claude reads the codebase and fixes actual code
    2
    GPT / Codex reviews strategy and logic
    3
    Gemini organizes design and screen structure

    Real command:

    Do not execute this task immediately. First have Claude Code analyze the code structure, then have GPT / Codex review that analysis, and finally have Claude Code modify the actual code based on the final instructions created by GPT / Codex. If the task includes design, assign UI/UX review to Gemini, and have Claude implement the results organized as modification requests by Gemini.

    10. Configuring Automatic Startup

    01What You Do in This Section

    In this section, you configure NanoClaw, Hermes Agent, HermesClaw, and OpenClaw gateway to automatically restart after Mac mini reboots.

    However, automatic startup is not a feature you enable immediately after installation. You must first complete the following items from Section 8:

    Enabling automatic startup without meeting these conditions will only make problems more complicated.

    02Risks When Manual Execution is Unstable

    Bad example: Enabling automatic startup even though manual execution is unstable

    Result:

    The goal of this section is to understand why automatic startup is needed, distinguish the roles of Docker restart policy and launchd, and verify that the agent comes back to life after reboot.

    03Why Automatic Startup is Needed

    If you use Mac mini as an AI automation server, a setup where you manually re-run commands after each reboot is dangerous.

    Reasons automatic startup is needed:

    04Automatic Startup Targets and What to Avoid

    Automatic startup targets:

    Things that should not be auto-started:

    The purpose of automatic startup is not to repeat installation, but to return to an already-verified execution state.

    05Three Automatic Startup Methods

    On Mac mini, automatic startup usually uses one of three methods:

    Docker restart policy
    Responsible for restarting Docker containers when they shut down
    Tool's own gateway service
    Using service install/start/status functionality provided by the CLI, like OpenClaw
    launchd
    Method to have macOS run a specific command after login or boot

    06Recommended Order for Beginners

    Docker container-based:

    1. Start with Docker restart policy
    2. Verify Docker Desktop runs after reboot
    3. Use launchd as supplementary only when needed

    OpenClaw gateway-based:

    1. Use openclaw gateway install or onboard --install-daemon
    2. Verify with openclaw gateway status
    3. Prioritize official CLI functionality before creating plist files manually

    Hermes Agent / HermesClaw general process-based:

    1. Record manual run command in RUNBOOK.md
    2. Create start script
    3. Execute as launchd LaunchAgent
    Do not configure the same agent to auto-restart through both Docker restart policy and launchd simultaneously.

    07Results of Duplicate Automatic Startup

    Duplicate automatic startup is the most common cause of production failures:

    08Record Current Execution Method in RUNBOOK

    Before configuring automatic startup, you need to know the exact manual run command. Check if RUNBOOK.md exists in each project folder:

    find ~/ai-agents/projects -maxdepth 3 -name "RUNBOOK.md"

    If not, create one:

    nano ~/ai-agents/projects/RUNBOOK-AUTOSTART.md

    Record in the following format. Document the installation location, manual run command, and status check command for each of NanoClaw, Hermes Agent, HermesClaw, and OpenClaw.

    09Save State Before Reboot

    Before configuring automatic startup, save your current state:

    mkdir -p ~/ai-agents/checks/autostart

    Docker state:

    docker ps -a > ~/ai-agents/checks/autostart/docker-ps-a-before-autostart.txt

    Process state:

    ps aux | grep -Ei 'nanoclaw|hermes|openclaw|gateway' > ~/ai-agents/checks/autostart/process-before-autostart.txt

    Also save port state, OpenClaw state, and Hermes state in the same way.

    10Check Docker Container Restart Policy

    For Docker-based agents, first check the Docker restart policy. Check the restart policy for all containers:

    docker inspect --format '{{.Name}} {{.HostConfig.RestartPolicy.Name}}' $(docker ps -aq)

    Example output:

    /nanoclaw-agent unless-stopped /nanoclaw-db no /hermes-gateway always

    no means there is no automatic restart policy set.

    11Apply Restart Policy to Container

    Apply to a specific container:

    docker update --restart unless-stopped container-name

    Example:

    docker update --restart unless-stopped nanoclaw-agent

    You can also apply to multiple running containers at once:

    docker update --restart unless-stopped $(docker ps -q)

    However, beginners should verify container names first and apply only to necessary ones rather than applying to all at once.

    12Difference Between always and unless-stopped

    For beginners, unless-stopped is usually safer:

    always
    Continually tries to restart if container stops. Container can revive after Docker daemon restart even if manually stopped
    unless-stopped
    Restarts if container stops, but maintains intentionally stopped state even after Docker restart

    For production Mac mini, unless-stopped is usually recommended.

    13Add Restart Policy to Docker Compose File

    If using Compose, add the following to compose.yaml or docker-compose.yml:

    services: agent: image: your-agent-image restart: unless-stopped

    If you have multiple services, specify for each needed service. After modifying the Compose file, simple docker compose restart may not apply the changes, so usually bring it up again like this:

    docker compose up -d

    14Verify Docker Desktop Starts

    On Mac, container automatic restart only works if Docker itself is running. After reboot, verify with:

    docker info

    If you see this error, Docker Desktop hasn't started yet:

    Cannot connect to the Docker daemon

    Things to check:

    15Test After Applying Docker Restart Policy

    Choose one container as a test target:

    docker ps --format "table {{.Names}}\t{{.Status}}"

    Stop:

    docker stop container-name

    unless-stopped does not immediately restart a container stopped by the user. This policy applies in Docker daemon or system restart situations. Check the restart policy:

    docker inspect --format '{{.Name}} {{.HostConfig.RestartPolicy.Name}}' container-name

    16Configure OpenClaw Gateway Automatic Startup

    If using OpenClaw, use the gateway service command provided by OpenClaw before creating plist manually:

    openclaw gateway status

    Install gateway service:

    openclaw onboard --install-daemon

    Or:

    openclaw gateway install

    Start after install:

    openclaw gateway start
    Since OpenClaw has its own gateway service management commands, beginners should prioritize using OpenClaw CLI's install/status/restart flow before writing plist files manually.

    17Introduction to launchd: LaunchAgent and LaunchDaemon

    General processes not solved by Docker restart policy or tool's own service can be auto-started with macOS launchd. launchd is the standard way macOS starts and manages background tasks.

    Beginners usually use LaunchAgent:

    LaunchAgent
    Runs in user login session. Location: ~/Library/LaunchAgents. Suitable for personal Mac mini operation
    LaunchDaemon
    Runs at system level. Location: /Library/LaunchDaemons. Requires root privileges and file ownership management. Not recommended for beginners

    This guide covers only LaunchAgent for user accounts.

    18Create Start Script for Automatic Startup

    Rather than putting long commands directly in plist, create a separate start script:

    mkdir -p ~/ai-agents/bin

    Hermes gateway startup script:

    nano ~/ai-agents/bin/start-hermes-gateway.sh

    Script content:

    #!/bin/zsh set -euo pipefail export PATH="/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin:$PATH" echo "[$(date)] starting hermes gateway" hermes gateway start

    Grant execution permission:

    chmod +x ~/ai-agents/bin/start-hermes-gateway.sh

    19Start Script Example for Docker Compose

    For Docker Compose-based projects, create like this:

    nano ~/ai-agents/bin/start-nanoclaw-compose.sh

    Script content:

    #!/bin/zsh set -euo pipefail export PATH="/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin:$PATH" cd "$HOME/ai-agents/projects/nanoclaw-v2" echo "[$(date)] starting docker compose project" docker compose up -d

    Execution permission:

    chmod +x ~/ai-agents/bin/start-nanoclaw-compose.sh

    20Separating Roles Between docker compose up -d and launchd

    When using this method, verify that roles don't overlap with Docker restart policy:

    Recommended structure
    launchd runs docker compose up -d once. Docker restart policy handles container restarts
    Structure to avoid
    launchd continuously monitors containers, and Docker restart policy also continuously restarts them

    21Create LaunchAgent plist Folder and File

    Create the LaunchAgent folder:

    mkdir -p ~/Library/LaunchAgents

    Create plist for Hermes gateway:

    nano ~/Library/LaunchAgents/com.aiagents.hermes-gateway.plist

    22LaunchAgent plist Content (1/2)

    plist file content:

    Label com.aiagents.hermes-gateway ProgramArguments /Users/username/ai-agents/bin/start-hermes-gateway.sh RunAtLoad KeepAlive

    23LaunchAgent plist Content (2/2)

    Remaining plist file:

    StandardOutPath /Users/username/ai-agents/logs/hermes-gateway.out.log StandardErrorPath /Users/username/ai-agents/logs/hermes-gateway.err.log WorkingDirectory /Users/username/ai-agents

    Important: Replace /Users/username with your actual username.

    24Check Username and Path

    Check current username:

    whoami

    Check home directory:

    echo $HOME

    Create log folder:

    mkdir -p ~/ai-agents/logs

    Verify plist syntax:

    plutil -lint ~/Library/LaunchAgents/com.aiagents.hermes-gateway.plist

    Normal example:

    /Users/username/Library/LaunchAgents/com.aiagents.hermes-gateway.plist: OK

    25Register LaunchAgent

    Register with the current user session in macOS:

    launchctl bootstrap gui/$UID ~/Library/LaunchAgents/com.aiagents.hermes-gateway.plist

    If you get an error saying it's already registered, unload it first:

    launchctl bootout gui/$UID ~/Library/LaunchAgents/com.aiagents.hermes-gateway.plist

    Register again:

    launchctl bootstrap gui/$UID ~/Library/LaunchAgents/com.aiagents.hermes-gateway.plist

    Run immediately:

    launchctl kickstart -k gui/$UID/com.aiagents.hermes-gateway

    26Check LaunchAgent Status and View Logs

    Check status:

    launchctl list | grep com.aiagents.hermes-gateway

    Check stdout log:

    tail -n 100 ~/ai-agents/logs/hermes-gateway.out.log

    Check stderr log:

    tail -n 100 ~/ai-agents/logs/hermes-gateway.err.log

    27Why KeepAlive is Not Enabled from the Start

    In the example above, KeepAlive is set to false. Reasons not to recommend enabling KeepAlive as true from the start:

    First enable with RunAtLoad to run once at login, then consider KeepAlive when stability is confirmed. Docker containers are handled by Docker restart policy, and launchd should be limited to running docker compose up -d once. This approach is safer.

    28Save State Before Reboot After Configuring Automatic Startup

    After configuring automatic startup, you must test with a reboot. Save state before reboot:

    mkdir -p ~/ai-agents/checks/autostart
    date > ~/ai-agents/checks/autostart/reboot-test-time.txt

    Docker state:

    docker ps -a > ~/ai-agents/checks/autostart/docker-before-reboot.txt

    Also save launchd state, process state, and port state.

    29Rebooting and Checking State After Reboot

    Reboot:

    sudo shutdown -r now

    You can also reboot from the menu: Apple menu → Restart

    Check state after reboot:

    docker ps -a > ~/ai-agents/checks/autostart/docker-after-reboot.txt
    launchctl list | grep -Ei 'aiagents|nanoclaw|hermes|openclaw|gateway' > ~/ai-agents/checks/autostart/launchctl-after-reboot.txt

    30Compare Before and After Reboot and Verify Normalcy

    Compare differences:

    diff -u ~/ai-agents/checks/autostart/docker-before-reboot.txt ~/ai-agents/checks/autostart/docker-after-reboot.txt
    diff -u ~/ai-agents/checks/autostart/process-before-reboot.txt ~/ai-agents/checks/autostart/process-after-reboot.txt

    Normalcy criteria:

    31When Automatic Startup Fails: Check plist Syntax and Registration

    Check plist syntax:

    plutil -lint ~/Library/LaunchAgents/com.aiagents.hermes-gateway.plist

    If not normal, fix the plist first.

    Check registration:

    launchctl list | grep com.aiagents.hermes-gateway

    If nothing appears, it's not registered. Register again:

    launchctl bootstrap gui/$UID ~/Library/LaunchAgents/com.aiagents.hermes-gateway.plist

    32Diagnose Automatic Startup Failure: Immediate Run and Script Validation

    Test immediate run:

    launchctl kickstart -k gui/$UID/com.aiagents.hermes-gateway

    Check logs:

    tail -n 100 ~/ai-agents/logs/hermes-gateway.out.log
    tail -n 100 ~/ai-agents/logs/hermes-gateway.err.log

    Verify manual run:

    ~/ai-agents/bin/start-hermes-gateway.sh

    If manual run also fails, it's not a launchd issue.

    33Check Execution Permission and PATH Issues

    Check execution permission:

    ls -la ~/ai-agents/bin/start-hermes-gateway.sh

    If execution permission is missing, grant it:

    chmod +x ~/ai-agents/bin/start-hermes-gateway.sh

    Check PATH:

    grep PATH ~/ai-agents/bin/start-hermes-gateway.sh

    Verify that PATH is explicitly set in the script:

    export PATH="/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin:$PATH"

    Check command locations: which hermes, which docker, which openclaw

    34Docker Desktop and Port Conflict Issues

    Check Docker Desktop issue:

    docker info

    If Docker-based automatic startup fails, first verify Docker is alive. In environments where Docker starts late, you can add a wait loop to the start script.

    Check port conflict:

    lsof -nP -iTCP -sTCP:LISTEN | grep -Ei '18789|19998|19999'

    If another process is already using the port, automatic startup may fail.

    35Check for Duplicate Automatic Startup

    Verify that Docker restart policy and launchd are not managing the same target redundantly.

    Check Docker policy:

    docker inspect --format '{{.Name}} {{.HostConfig.RestartPolicy.Name}}' $(docker ps -aq)

    Check LaunchAgent:

    launchctl list | grep -Ei 'nanoclaw|hermes|openclaw|gateway|aiagents'

    Check process:

    ps aux | grep -Ei 'nanoclaw|hermes|openclaw|gateway' | grep -v grep

    36What Beginners Should Not Do

    37Commands Particularly to Avoid

    Never use deletion commands:

    # These commands beginners do not use right away sudo rm -rf /Library/LaunchDaemons/* launchctl bootout system/* docker rm -f $(docker ps -aq) kill -9 $(ps aux | grep gateway | awk '{print $2}')

    Before deletion: check state and back up.

    38Automatic Startup Configuration Completion Checklist

    Prerequisites:

    Docker configuration:

    39Checklist Continued (OpenClaw and launchd)

    OpenClaw configuration:

    launchd configuration:

    40Final Checklist (Rebooting and Safety)

    Reboot testing:

    Security and stability:

    41Core Summary of This Section

    Automatic startup is not a feature that makes your agent smarter, but an operational mechanism that returns it to a verified running state.

    Six most important principles:

    1. Enable automatic startup only after manual execution is stable
    2. Docker containers prioritize Docker restart policy
    3. OpenClaw prioritizes its own gateway service commands
    4. General processes are managed by launchd LaunchAgent
    5. Don't manage the same agent through two methods simultaneously
    6. Verify message send and receive after reboot

    42Success Criteria for Automatic Startup Configuration

    One sentence for beginners to remember:

    Success in automatic startup configuration is not that Mac turns on, but that after reboot, the agent runs without duplication and messages are sent and received normally.

    After completing Section 10, Mac mini has a basic recovery structure for operating personal AI agents 24 hours. In the next stage, you should establish stricter security configuration, log management, pre-update backup, and failure recovery procedures.

    11. Security Setup

    01What This Section Covers

    This section covers the security settings you must check when running AI agents like NanoClaw, Hermes Agent, HermesClaw, and OpenClaw on a Mac mini.

    AI agents carry more security risk than ordinary programs. Things an agent can reach include:

    A misconfigured agent can leak API keys, cause unexpected API charges, get a messaging account suspended, expose private conversations, delete local files, allow external access to the Mac mini, reach files through Docker, or leave tokens in logs.

    Reducing the blast radius matters more than convenience.

    02Storing API Keys Safely

    Never put API keys directly in code

    Bad example:

    ANTHROPIC_API_KEY = "sk-ant-..." OPENAI_API_KEY = "sk-..."

    Better direction:

    Separate keys per purpose

    Splitting by use lets you cut off just one key when something goes wrong:

    Check whether a key is set

    Don't print the value — only check that it exists:

    test -n "$ANTHROPIC_API_KEY" && echo "ANTHROPIC_API_KEY is set" || echo "ANTHROPIC_API_KEY is not set"

    Check all related variables with masking:

    env | grep -Ei 'ANTHROPIC|OPENAI|GEMINI|GOOGLE|API_KEY|TOKEN' | sed 's/=.*/=***REDACTED***/'

    Never do this:

    echo $ANTHROPIC_API_KEY

    The key can leak while screen-sharing or copying logs.

    03When You Must Store a Key in a File

    In a beginner setup, a .env file is common.

    Restrict file permissions

    chmod 600 ~/ai-agents/secrets/agent.env

    Check permissions:

    ls -la ~/ai-agents/secrets/agent.env

    Good example: -rw------- means only the owner can read and write.

    What to do if a key leaks

    If an API key was ever exposed, don't assume "I masked it, so it's fine":

    1. Revoke or delete the key in the provider console
    2. Create a new key
    3. Replace the key in the .env or secret file
    4. Restart the agent
    5. Check the usage page for abnormal calls
    6. If it was pushed to a repo, check Git history for exposure

    Note: A key pushed to GitHub can remain in history even after you delete the file. In that case, revoking the key comes first; cleaning history comes second.

    04Managing the .env File

    A .env file gathers environment variables in one place. Because it is sensitive, treat it as a secret config file, not code.

    Sensitive data that easily ends up in .env:

    Always add to .gitignore

    .env .env.* *.env secrets/ *.key *.pem *.p12 *.pfx *.crt *.token *token* *secret* account.json credentials.json

    Important: .gitignore only blocks files added from now on. Files Git already tracks are not removed automatically just by adding them to .gitignore.

    Check whether something is already tracked:

    git ls-files | grep -Ei '(^|/).env|secret|token|credential|account.json'

    Remove a sensitive file from Git tracking while keeping the local file:

    git rm --cached .env

    05.env.example and Permission Checks

    Commit only .env.example

    Commit an example file instead of the real .env:

    ANTHROPIC_API_KEY= OPENAI_API_KEY= GEMINI_API_KEY= AGENT_MODE=test LOG_LEVEL=info

    Principle:

    Permission check

    find ~/ai-agents -name ".env" -o -name "*.env" -exec chmod 600 {} ;

    Keep .env content out of logs

    Dangerous commands:

    cat .env docker logs container-name

    Check with masking:

    sed 's/=.*/=***REDACTED***/' .env

    Search Docker logs for key patterns:

    docker logs --tail 500 container-name 2>&1 | grep -Ei 'sk-|api_key|token|secret|password|credential'

    06Separating Messaging Accounts

    Split production and test accounts

    When you first connect an AI agent, don't use your real messaging account right away. Accounts to separate:

    Recommended path: local CLI or a test Telegram bot → test chat room → dedicated operations account → an account with limited permissions and recipients.

    Reduce permissions per messaging account

    Never send sensitive data in messages

    Do not send: API keys, login passwords, 2FA codes, session cookies, ID/identity info, exchange API secrets, SSH private keys, the full contents of .env.

    When diagnosing, mask:

    07Blocking External Access

    Default policy

    An AI agent running on a personal Mac mini should, by default, not be reachable directly from the public internet:

    Settings to avoid

    Check currently open ports

    lsof -nP -iTCP -sTCP:LISTEN

    Narrow it to AI-agent ports:

    lsof -nP -iTCP -sTCP:LISTEN | grep -Ei 'nanoclaw|hermes|openclaw|claw|gateway|node|python|docker|18789|19998|19999'

    08Docker Ports and Firewall

    Check container ports

    docker ps --format "table {{.Names}}\t{{.Ports}}"

    Dangerous: 0.0.0.0:8080->8080/tcp

    Relatively safe: 127.0.0.1:8080->8080/tcp

    Binding a port to localhost only in Compose:

    services: agent: ports: - "127.0.0.1:8080:8080"

    If public access isn't needed, remove ports entirely and use internal communication only:

    services: agent: expose: - "8080"

    expose only matters inside the container network and does not publish a port to the host.

    Turn on the macOS firewall

    Apple menu → System Settings → Network → Firewall → On

    Check status from the command line:

    /usr/libexec/ApplicationFirewall/socketfilterfw --getglobalstate

    Turn the firewall on:

    sudo /usr/libexec/ApplicationFirewall/socketfilterfw --setglobalstate on

    Turn on stealth mode:

    sudo /usr/libexec/ApplicationFirewall/socketfilterfw --setstealthmode on

    09Checking Router Port Forwarding

    If your router forwards ports to the Mac mini, the macOS firewall alone may not be enough.

    Items to check:

    Recommended:

    10Reducing Container Privileges

    Container security principles

    Check the current container user

    docker exec container-name id

    If the output is uid=0(root) gid=0(root), it's running as root.

    Set a non-root user in Compose

    services: agent: image: your-agent-image user: "1000:1000"

    Don't use privileged mode

    Dangerous:

    services: agent: privileged: true

    Avoid it in beginner operations. privileged: true greatly widens container privileges.

    Never mount the Docker socket

    The setting below can be very dangerous:

    volumes: - /var/run/docker.sock:/var/run/docker.sock

    Giving the Docker socket to a container lets it control other containers or heavily affect the host.

    11Limiting File Access Scope

    Restrict the folders the agent can read

    Bad:

    volumes: - ~/:/host - /:/host

    Good:

    volumes: - ~/ai-agents/workspace:/workspace

    Safer (read-only):

    volumes: - ~/ai-agents/workspace:/workspace:ro

    Create a workspace folder

    Make a dedicated folder for the agent to work in:

    mkdir -p ~/ai-agents/workspace/inbox mkdir -p ~/ai-agents/workspace/outbox mkdir -p ~/ai-agents/workspace/tmp mkdir -p ~/ai-agents/workspace/logs

    Block access to dangerous file patterns

    Keep the agent from reading or printing these files:

    Limit delete commands

    Dangerous commands:

    rm -rf ~ rm -rf ~/ai-agents rm -rf / find . -type f -delete

    If deletion is needed, move first:

    mkdir -p ~/ai-agents/trash mv target-file ~/ai-agents/trash/

    Or keep it with a timestamp:

    mv target-folder target-folder-disabled-$(date +%Y%m%d-%H%M%S)

    12Back Up Before Updating

    Why updates are risky

    AI agent projects can suddenly change behavior after an update:

    So always back up the current state before updating.

    Create a pre-update backup folder

    BACKUP_DIR=~/ai-agents/backups/before-update-$(date +%Y%m%d-%H%M%S) mkdir -p "$BACKUP_DIR"

    Save project files, Git, and Docker state

    find ~/ai-agents/projects -maxdepth 5 -type f > "$BACKUP_DIR/projects-file-list.txt" docker ps -a > "$BACKUP_DIR/docker-ps-a.txt" docker images > "$BACKUP_DIR/docker-images.txt"

    Back up Compose files

    mkdir -p "$BACKUP_DIR/compose-files" find ~/ai-agents/projects -type f \( -name "compose.yaml" -o -name "docker-compose.yaml" \) -exec cp {} "$BACKUP_DIR/compose-files/" \;

    For sensitive files, save only the list and hashes

    Be especially careful when backing up:

    find ~/ai-agents -type f \( -name ".env" -o -name "*.env" -o -name "*token*" \) > "$BACKUP_DIR/sensitive-file-list.txt"

    Save hashes only:

    while read -r f; do shasum -a 256 "$f"; done < "$BACKUP_DIR/sensitive-file-list.txt" > "$BACKUP_DIR/sensitive-file-sha256.txt"

    Update one thing at a time

    Good order:

    1. Back up
    2. Update NanoClaw only
    3. Verify it runs
    4. Verify message reception
    5. If fine, update the next component

    You should be able to narrow down the cause when something breaks.

    13What Beginners Should Not Do + Completion Checklist

    What beginners should not do

    Commands to especially avoid

    docker run -v /:/host ... docker run -v /var/run/docker.sock:/var/run/docker.sock ... docker compose up -d --pull always git add . git push

    git add . is convenient but makes it easy to accidentally commit .env, token, or credential files. Check changed files first:

    git status git diff --name-only git add README.md compose.yaml

    Security completion checklist

    API keys ✓ no direct-in-code, per-provider split, masked checks, leak procedure

    .env ✓ not in Git, added to .gitignore, tracked files checked, only .env.example committed, permission 600

    Messaging ✓ test/production split, allowed user/chat set, no sensitive data sent, minimal permissions

    External access ✓ ports checked, Docker exposure checked, no needless 0.0.0.0, firewall checked, port forwarding checked

    Containers ✓ root check, user set, no privileged, cap_drop applied, no-new-privileges, read_only reviewed, no docker.sock

    File access ✓ no full host mount, workspace folder, :ro mounts, sensitive files checked, delete-command rules

    Updates ✓ backup folder, Git state saved, Docker state saved, Compose backup, sensitive file list and hashes, one at a time

    14Section Summary

    The heart of AI agent security is not perfect lockdown but shrinking the blast radius.

    For a Mac mini AI agent, "is it designed so damage stays small even when it goes wrong" matters more than "does it run well."

    The seven most important principles:

    1. Separate API keys from code and repositories
    2. Treat .env as a local secret file
    3. Split messaging accounts into test and production
    4. Block external access by default
    5. Minimize container privileges
    6. Limit the files the agent can see
    7. Always back up before updating

    Clearing Section 11 means you have the minimum security baseline before real use.

    12. Solving Frequently Encountered Issues

    01What We Do in This Section

    This section organizes operational issues that appear repeatedly in actual communities and developer issues, tailored to the Mac mini environment.

    The most common mistakes beginners make are as follows:

    The key to problem-solving is not quick reinstallation but accurate separation.

    02Problem-Solving Order

    Whenever a problem occurs, first gather the following information:

    1. Write down the symptom precisely
    2. Confirm the execution method
    3. Check the logs
    4. Narrow down the scope before guessing the cause
    5. Back up the current state before deleting or reinstalling
    6. Start with small fixes
    7. Test again after fixing
    8. Record the resolution process in RUNBOOK.md

    Practical tip: Half of problem-solving is

    "what failed"versus"what works normally"
    . You need to check separately whether Docker is normal, gateway is normal, and messaging reception works.

    03When Installation Commands Fail

    Installation failures often come from below rather than the project code itself:

    Before running the installation command again, check your current environment:

    $ git --version $ node -v $ npm -v $ pnpm -v $ python3 --version $ docker --version

    Record the lines that produce errors and save the installation log to a file:

    $ bash install.sh 2>&1 | tee install-error.log

    04When Permission Errors Occur

    If you created log or data files in a Docker container and then tried to edit them on macOS, only to get

    Permission denied
    , it means the container's internal user permissions don't match the macOS user permissions.

    First, check the following:

    $ ls -la $ docker ps --format "table {{.Names}}\t{{.Image}}" $ docker exec container-name id

    After checking your Mac's UID/GID, specify the user in Compose:

    services: agent: user: "1000:1000"

    When you need to temporarily change ownership, target the folder narrowly:

    $ sudo chown -R "$(whoami)":staff ~/ai-agents/workspace

    05When Docker Doesn't Run

    If the agent worked fine right after installation but stopped the next morning, check whether Docker Desktop is running.

    On Mac, Docker Engine doesn't always run as a default service by itself but operates together with the Docker Desktop app. If Docker Desktop is closed or still initializing,

    docker ps
    will fail.

    $ docker info

    If an error appears, launch Docker Desktop:

    $ open -a Docker

    Wait and verify until it's ready:

    $ while ! docker info >/dev/null 2>&1; do echo "Waiting for Docker to be ready..." sleep 5 done

    06When Port is Already in Use

    When you restart gateway and the old gateway process hasn't fully terminated before the new gateway starts,

    Port 18789 is already in use
    occurs.

    Principle: One port can only be listened to by one process at the same time.

    Check port:

    $ lsof -i :18789 $ ps aux | grep -E 'openclaw|hermes|gateway' | grep -v grep

    First use the graceful shutdown command:

    $ openclaw gateway stop $ hermes gateway stop

    If it still remains after graceful shutdown, check the PID and terminate it gently, and only force-terminate as a last resort:

    $ kill PID $ kill -9 PID # last resort

    Important: Before changing the port for a port conflict, confirm why the existing process is still alive.

    07When Not Receiving Messages

    If you added a Telegram bot to a group and it works fine in personal DM but doesn't receive messages in the group, Telegram bot privacy mode is the cause.

    Messaging issues are divided into three stages:

    1. Does the messaging platform send events to the agent
    2. Does gateway receive the events
    3. Does the agent process those events

    Check gateway status:

    $ hermes status $ openclaw gateway status

    If you need to receive all messages in a Telegram group:

    @BotFather → /setprivacy → Select target bot → Review Disable

    For Discord, you may need to enable privileged gateway intents in the Developer Portal.

    08When Messages Arrive But Replies Don't Send

    The log shows

    message received
    ,but replies don't go to the user.

    Message processing flow:

    1. Inbound reception
    2. Agent processing
    3. Model provider call
    4. Response generation
    5. Outbound sending

    Look for both reception and sending in recent logs:

    $ docker logs --since 15m container-name 2>&1 | grep -E 'inbound|outbound|error'

    Judgment: Inbound log exists + API error exists → provider/API issue | Inbound exists + response exists + outbound error → outbound or permission issue

    Check API key status (don't print the value directly, only check existence):

    $ test -n "$ANTHROPIC_API_KEY" && echo "set" || echo "not set"

    09When API Key Errors Occur

    Even though you created a new API key, if errors keep occurring, the current terminal may be using an old key that was saved earlier, not the new key.

    Check only the existence of the key value, not the value itself:

    $ env | grep -E 'ANTHROPIC|OPENAI|GEMINI' | sed 's/=.*/=***REDACTED***/'

    Judgment by error type:

    invalid_api_key
    Key is wrong, expired, or revoked
    insufficient_quota
    Billing, credits, or usage limit issue
    rate_limit_error
    Too many requests or token usage approaching limit
    model_not_found
    Model name, permissions, or provider configuration issue

    If key exposure is suspected, revocation comes before debugging: revoke the key in provider console → create new key → update .env → restart agent

    10When Auto-Execution Doesn't Work After Rebooting

    You created a launchd plist and the item appears in

    launchctl list
    ,but after rebooting, the agent doesn't execute.

    Cause: launchd doesn't use the same PATH as the terminal, leaving

    hermes: command not found
    in the logs.

    Check plist syntax:

    $ plutil -lint ~/Library/LaunchAgents/com.aiagents.hermes-gateway.plist

    Check logs:

    $ tail -n 100 ~/ai-agents/logs/hermes-gateway.err.log

    In launchd startup script, specify PATH explicitly:

    #!/bin/zsh export PATH="/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin" hermes gateway start

    When running Docker Compose via launchd, wait for Docker to be ready:

    for i in {1..30}; do docker info >/dev/null 2>&1 && break sleep 5 done docker compose up -d

    11When Log Files Grow Too Large

    Gateway logs grow infinitely and stack repeated errors like WebSocket heartbeat timeout. When log files grow large, don't just see it as "running out of disk space."

    Find large files:

    $ find ~/ai-agents -type f -size +100M 2>/dev/null

    Log folder size:

    $ du -sh ~/ai-agents/logs

    Find repeated lines to understand the cause:

    $ tail -n 1000 file.log | sort | uniq -c | sort -nr | head -20

    Docker log size limit (in Compose file):

    services: agent: logging: driver: "json-file" options: max-size: "10m" max-file: "3"

    Key point: Growing log files aren't solved just by deleting logs. You must find the cause of the repeated error.

    12When Suddenly Broken After Update

    After an update, the old gateway process remains and the new gateway can't grab the port, or the gateway is alive but a pairing required error occurs.

    Possible causes:

    Right after update, first check:

    $ hermes --version $ docker ps -a $ lsof -i :18789

    Check if migration is needed:

    $ hermes config check $ hermes config migrate $ openclaw doctor

    Find pre-update backup and compare with current state:

    $ diff -u ~/ai-agents/backups/backup-folder/compose.yaml ~/ai-agents/projects/nanoclaw-v2/compose.yaml

    Important: Failures after update aren't about "update failed" but about "verifying what changed before and after update."

    13Unified Prompt for Troubleshooting

    When problems are complex, collect information in the format below and analyze:

    Setup: - Tool: [NanoClaw / OpenClaw] - Execution method: [Docker / launchd / manual] - Messaging channel: [Telegram / Discord] Verification results: docker ps -a: [paste] Process: [paste] Port: [paste] gateway status: [paste] Recent logs: [paste after removing API keys]

    Request checklist:

    14What Beginners Should Never Do

    Absolutely forbidden:

    Especially dangerous commands:

    # absolutely forbidden docker rm -f $(docker ps -aq) rm -rf ~/.hermes rm -rf ~/.openclaw kill -9 $(ps aux | grep gateway | awk '{print $2}')

    Before deleting, backup and separate causes.

    15Problem-Solving Completion Checklist

    Common items:

    Symptom
    Summarized in one sentence
    Docker status
    Checked docker ps -a
    Process
    Checked ps aux
    Port
    Checked lsof
    gateway status
    Checked hermes/openclaw status
    Logs
    Checked recent logs

    Category items (only applicable issues):

    Section 12 · Key Summary

    Core of Solving Frequently Encountered Issues

    Most AI agent failures aren't fixed in one go but by narrowing down whether something broke during installation, Docker, gateway, messaging, API, or auto-execution.

    Most important order:

    1. Verify recent changes
    2. Verify processes
    3. Verify ports
    4. Verify logs
    5. Verify messaging reception
    6. Verify API calls
    7. Verify sending
    8. Verify auto-execution
    9. Compare with backup
    10. Document resolution
    After passing section 12, you're no longer just an installation user but an operator who can isolate causes and recover safely when failures occur.
    Key Principle

    Problem-solving is accurate separation, not quick reinstallation.

    13. Practical Operations Tips

    01What This Unit Covers

    This unit organizes the habits and procedures needed to actually run NanoClaw, Hermes Agent, HermesClaw, and OpenClaw family agents long-term on Mac mini.

    While earlier units covered installation, execution, security, and troubleshooting, this unit is more like the operator's way of life.

    What This Unit Covers

    The most important thing in practical operations is not fancy automation, but one of the following:

    02Installation Success ≠ Operations Success

    There's something beginners often confuse:

    Installation success = Operations success

    No. Operations success looks like this:

    03Keep Goals Low for 24-Hour Operations (1/3)

    If you try to create a perfect personal secretary, trading bot, or business automation agent from the start, operations become unstable.

    The goal for the first week is not features, but stability.

    First Week Goals

    Things to avoid from the start:

    04Keep Goals Low for 24-Hour Operations (2/3)

    In practice, "small and running long" is much better than "big and running for a day."

    Basic Status Check Command for 24-Hour Operations

    Just running this command once a day gives you operational sense:

    echo "=== DATE ===" date echo " === Docker ===" docker ps --format "table {{.Names}} {{.Status}} {{.Ports}}" echo " === Related processes ===" ps aux | grep -Ei 'nanoclaw|hermes|openclaw|claw|gateway' | grep -v grep echo " === Listening ports ===" lsof -nP -iTCP -sTCP:LISTEN | grep -Ei '18789|19998|19999|nanoclaw|hermes|openclaw|gateway' || echo "no matching ports" echo " === Disk ===" df -h / echo " === Logs size ===" du -sh ~/ai-agents/logs 2>/dev/null || echo "no ~/ai-agents/logs" du -sh ~/.hermes 2>/dev/null || echo "no ~/.hermes" du -sh ~/.openclaw 2>/dev/null || echo "no ~/.openclaw"

    This command observes rather than fixes. Operators must first develop the habit of looking.

    05Keep Goals Low for 24-Hour Operations (3/3)

    One-Minute Daily Checklist

    No need for complex checks every day. This much is enough:

    For beginners, this checklist comes before automation.

    Weekly Checklist

    Once a week, check a bit deeper:

    06Mac Settings: Prevent Sleep

    To use Mac mini like a server, configure it so it doesn't go to sleep even when the display turns off.

    Check this in macOS settings:

    System Settings

    Energy → Prevent automatic sleeping when the display is off

    For desktop environments like Mac mini (not MacBook), check this setting first.

    You can also check current power settings with a command:

    pmset -g

    If you want to temporarily prevent sleep during work, you can use caffeinate:

    caffeinate -i

    To prevent sleep only until a specific command finishes:

    caffeinate -i docker compose up -d

    Note: caffeinate is suitable for temporary work. It's better to set the baseline for 24-hour operations in macOS Energy settings.

    07Docker Desktop Resource Saver Verification

    Docker Desktop has a Resource Saver feature that saves resources by suspending the Docker Desktop Linux VM when idle.

    However, in 24-hour agent operations, it can cause confusion like "Why is Docker responding slowly?"

    Location to Check

    Docker Desktop → Settings → Resources → Resource Saver

    Practical Decision Criteria

    Development Mac
    It's okay to enable Resource Saver
    24-hour agent operations Mac mini
    If agent container must always be running, verify Resource Saver impact
    When problems are suspected
    Temporarily disable Resource Saver and compare stability over 2-3 days

    This doesn't mean always disable it. But if Docker suddenly becomes unresponsive or containers seem to wake up slowly after restart, check this setting.

    08Network: Wired Connection First

    When using Mac mini like a server, prioritize wired Ethernet over Wi-Fi.

    Recommended Setup

    Especially with messaging gateways, even brief network interruptions can cause sessions to get messed up.

    When Wi-Fi Is Poor

    09Restart Order: From Small Units

    When failures occur, full Mac reboot is the last resort. In operations, restart from small units:

    Restart Order

    1. Agent process
    2. Gateway
    3. Docker container
    4. Docker Compose project
    5. Docker Desktop
    6. Mac mini reboot

    Example

    openclaw gateway restart
    docker restart container-name
    cd ~/ai-agents/projects/nanoclaw-v2 docker compose restart

    Full Mac reboot is the largest and crudest action.

    10Log Management Principles

    Beginners immediately delete logs when they grow:

    rm app.log

    But in operations, rotation is better than deletion.

    Log Management Principles

    11Docker Log Rotation Setup

    When using Docker Compose, add logging options for each service:

    services: agent: logging: driver: "json-file" options: max-size: "10m" max-file: "3"

    Also add to gateway service:

    services: gateway: logging: driver: "json-file" options: max-size: "10m" max-file: "3"

    Apply and Verify

    docker compose up -d docker compose ps docker compose logs --tail 100

    12Log File Location and Size Check

    docker ps --format "table {{.Names}} {{.Status}}" docker inspect --format='{{.LogPath}}' container-name

    Check Log Size

    ls -lh "$(docker inspect --format='{{.LogPath}}' container-name)"

    If log size grows beyond hundreds of MB, review rotation settings.

    13Finding Repeated Errors

    The real reason logs grow is usually repeated errors:

    tail -n 1000 file-path.log | sort | uniq -c | sort -nr | head -20

    Find in Docker Logs

    docker logs --tail 1000 container-name 2>&1 | sort | uniq -c | sort -nr | head -20

    View Recent Errors Only

    docker logs --since 30m container-name 2>&1 | grep -Ei 'error|fail|timeout|retry|auth|token|rate|limit|port|heartbeat'

    In practice, repeated sentences are more important than log size.

    Bad approach: The log file is 3GB. I should delete it. Good approach: First, let me see why the same error repeated a million times.

    14Define Log Retention Policy

    Keep it simple initially:

    Operations logs
    Keep recent 7 days
    Incident logs
    Keep 30 days after resolution
    Logs containing sensitive info
    No external sharing, immediately discard or safely store if needed
    Debug logs
    Delete or compress after troubleshooting

    Create Log Archive Folder

    mkdir -p ~/ai-agents/logs/archive

    Compress Old Logs

    find ~/ai-agents/logs -type f -name "*.log" -mtime +7 -exec gzip {} ;

    Delete Compressed Logs Older Than 30 Days

    find ~/ai-agents/logs -type f -name "*.gz" -mtime +30 -delete

    Beginners should run this command manually first to verify results before automating it.

    15Check Logs for Sensitive Information

    API keys or tokens might be logged:

    grep -R -n -Ei 'sk-|api_key|token|secret|password|credential|cookie|session' ~/ai-agents/logs ~/ai-agents/projects 2>/dev/null

    If found, don't share the content externally. First assess the possibility of key or token exposure:

    Step 1
    Verify if the key is a real key
    Step 2
    If real, revoke from provider console
    Step 3
    Issue new key
    Step 4
    Stop log retention or securely delete
    Step 5
    Fix code or settings for why it was logged

    16Updates Are Not "When You Have Time"

    Updates should happen not "when you have time," but "when you have time to roll back."

    The worst times to update in practice:

    Good Update Times

    17Must-See Before Updating

    Before updating, check these:

    For GitHub Projects

    git status git log --oneline -5 git remote -v

    Docker Status

    docker ps -a docker images

    18Backup Before Updating

    Create a backup before updating:

    BACKUP_DIR=~/ai-agents/backups/before-update-$(date +%Y%m%d-%H%M%S) mkdir -p "$BACKUP_DIR" docker ps -a > "$BACKUP_DIR/docker-ps-a.txt" docker images > "$BACKUP_DIR/docker-images.txt" find ~/ai-agents/projects -maxdepth 5 -type f > "$BACKUP_DIR/projects-file-list.txt"

    19Update One at a Time

    Bad Example

    All done in a day

    Good Example

    1. Backup
    2. Update NanoClaw only
    3. Verify execution
    4. Verify message receiving
    5. Verify message sending
    6. Check logs
    7. Observe for a day
    8. Update next component

    This approach seems slow but is much faster at narrowing down failure causes.

    20Smoke Test After Updating

    After updating, perform these tests:

    Verification Commands

    docker ps -a hermes status 2>/dev/null || true openclaw gateway status 2>/dev/null || true docker logs --tail 100 container-name

    Test Message to Messaging App

    Update test time. If working normally, reply "update test successful."

    21Observation Period After Updating

    After updating, provide at least a short observation period:

    What to Observe

    Practical Tip

    In the 10 minutes right after updating, don't add features. Just verify normal operation first.

    22Separate Test and Production Environments

    Mixing test and production in AI agent operations makes problems worse:

    Problems from Mixing

    The best structure is separation from the start:

    Recommended structure: test-bot, staging-bot, production-bot

    For beginners, just separating test and production is enough.

    23Environment Separation: Folders and Settings

    Folder Separation

    mkdir -p ~/ai-agents/environments/test mkdir -p ~/ai-agents/environments/prod

    Example Structure

    ~/ai-agents/ environments/ test/ .env compose.yaml RUNBOOK.md prod/ .env compose.yaml RUNBOOK.md logs/ test/ prod/ backups/ test/ prod/

    .env Separation

    For test:

    nano ~/ai-agents/environments/test/.env

    For production:

    nano ~/ai-agents/environments/prod/.env

    Test example:

    AGENT_ENV=test AGENT_NAME=test-bot LOG_LEVEL=debug

    Production example:

    AGENT_ENV=prod AGENT_NAME=personal-assistant LOG_LEVEL=info
    Note

    If possible, also separate API keys between test and production so tests don't consume production limits.

    24Separate Messaging Accounts and Ports

    Separate Messaging Accounts

    Test
    Test Telegram bot, test Discord server, local CLI, chat room with only yourself
    Production
    Production bot, production channel, allowed user settings, allowed chat settings

    Structures to Avoid

    Port Separation

    If test and prod use the same port, they'll conflict:

    Test
    18790
    Prod
    18789

    Verify

    lsof -nP -iTCP -sTCP:LISTEN | grep -Ei '18789|18790|19998|19999'

    25Separate Docker Compose Projects

    If Docker Compose project names overlap, resource names get confusing:

    Test

    docker compose -p agent-test up -d

    Production

    docker compose -p agent-prod up -d

    Verify Status

    docker ps --format "table {{.Names}} {{.Status}} {{.Ports}}"

    26Production Promotion Criteria

    Don't immediately move to production just because it works in test:

    Stability
    24 hours without restart loop, no log explosion, no duplicate sending, no repeated API errors
    Execution
    Recovery successful after reboot, backup complete, RUNBOOK.md written

    27Incident Response First Principle

    When failures occur, the first principle is not to fix, but to stop what needs stopping.

    Especially if messages are being duplicate-sent or API calls are surging, immediately stop automation:

    Emergency Stop Targets

    Stop Commands

    docker stop container-name docker compose stop openclaw gateway stop hermes gateway stop 2>/dev/null || true

    28Incident Recovery Order

    This order is safe for practical recovery:

    Recovery Steps

    1. Record symptoms
    2. Stop automation
    3. Save current state
    4. Check recent changes
    5. Check logs
    6. Restart from smallest unit
    7. Verify test message
    8. Record prevention

    Save State

    INCIDENT_DIR=~/ai-agents/incidents/$(date +%Y%m%d-%H%M%S) mkdir -p "$INCIDENT_DIR" docker ps -a > "$INCIDENT_DIR/docker-ps-a.txt" 2>&1 ps aux | grep -Ei 'nanoclaw|hermes|openclaw|gateway' | grep -v grep > "$INCIDENT_DIR/processes.txt" 2>&1 lsof -nP -iTCP -sTCP:LISTEN > "$INCIDENT_DIR/ports.txt" 2>&1

    29Check Recent Changes

    Most failures are caused by "what I just changed":

    Recent Changes to Check

    Check Git Status

    cd ~/ai-agents/projects/project-name git status --short git log --oneline -5

    Check File Modification Time

    find ~/ai-agents -type f -mtime -1 -exec ls -la {} ; 2>/dev/null | head -100

    30Recover from Small Unit First

    Bad Recovery

    Just reboot Mac

    Good Recovery

    1. Restart gateway only
    2. Restart agent container only
    3. Restart compose project only
    4. Restart Docker Desktop
    5. Last, reboot Mac

    Restart Commands

    docker restart container-name openclaw gateway restart cd ~/ai-agents/projects/nanoclaw-v2 docker compose restart

    31Test After Recovery

    After recovery, don't stop at "process started":

    Verify After Recovery

    Test Message

    Recovery test time. If working normally, reply "recovery test successful."

    32Write Incident Records

    Once you've resolved an incident, record it:

    Incident Record Template

    # Incident Record ## Time YYYY-MM-DD HH:mm ## Symptoms - ## Impact - ## Root Cause - ## Resolution - ## Prevention - ## First Command to Check Next Time -

    As these records accumulate, operations skills improve rapidly.

    33Mac mini Physical Placement

    Recommended Placement

    Placements to Avoid

    34Operating Without Monitor

    Monitor, keyboard, and mouse are helpful during initial setup. Once operations stabilize, you can run without a monitor:

    Recommended Order

    1. Install with monitor connected
    2. Configure autostart
    3. Test reboot
    4. Test remote access
    5. Remove monitor

    For remote access, carefully check macOS Sharing settings:

    Location to Check

    System Settings → General → Sharing

    Items to Review

    For security, use remote access only inside internal network or VPN.

    35Heat and Dust Management

    Mac mini is generally quiet, but for 24-hour operations, heat and dust are more important than noise:

    What to Check

    Check CPU Usage

    top -o cpu

    Check Memory

    top -o mem

    Check Docker Usage

    docker stats

    docker stats displays continuously, press Ctrl + C to stop.

    36External Storage Precautions

    When logs or data grow, you might want external SSD:

    Important Notes

    For beginners, don't move entire Docker to external SSD from the start. First verify stability on internal storage, then move only logs and backups to external.

    37Power Stability

    Power is also important for 24-hour operations:

    Recommended

    UPS is not mandatory, but helpful for work like trading alerts that can't be missed.

    38Documents the Operator Must Keep: RUNBOOK.md

    Each project must have a RUNBOOK.md:

    nano ~/ai-agents/projects/nanoclaw-v2/RUNBOOK.md

    RUNBOOK Contents

    # RUNBOOK ## Installation Location - ## How to Run - ## How to Stop - ## How to Restart - ## Status Check - ## Check Logs - ## Test Message - ## API Check - ## Backup Location - ## First Command to Check for Failure -

    39Documents the Operator Must Keep: Changelog and Incident Records

    CHANGELOG-LOCAL.md

    Record what I changed separately:

    nano ~/ai-agents/projects/nanoclaw-v2/CHANGELOG-LOCAL.md

    Example:

    # Local Change Log ## 2026-06-06 - Changed Docker restart policy to unless-stopped - Added log rotation to compose.yaml - Separated Telegram test bot from prod bot - Added launchd plist

    Official project CHANGELOG is different from my changes. Without knowing what I changed, I can't rollback when failures occur.

    INCIDENTS.md

    nano ~/ai-agents/INCIDENTS.md

    Example:

    # Incidents ## 2026-06-06 21:10 Symptom: Telegram messages received but no replies Root Cause: API key was in test .env but missing from prod .env Resolution: Updated prod .env and restarted gateway Prevention: Added env-redacted.txt comparison after updates

    Over time, this document becomes the most valuable record.

    40Automated Operational Health Check Script

    Simple Health Check Script

    mkdir -p ~/ai-agents/bin nano ~/ai-agents/bin/health-check.sh

    Script Contents

    #!/bin/zsh set -euo pipefail echo "=== DATE ===" date echo " === Docker containers ===" docker ps --format "table {{.Names}} {{.Status}} {{.Ports}}" || true echo " === Hermes ===" hermes status 2>/dev/null || echo "hermes status unavailable" echo " === OpenClaw ===" openclaw gateway status 2>/dev/null || echo "openclaw gateway status unavailable" echo " === Related processes ===" ps aux | grep -Ei 'nanoclaw|hermes|openclaw|claw|gateway' | grep -v grep || true echo " === Ports ===" lsof -nP -iTCP -sTCP:LISTEN | grep -Ei '18789|19998|19999|nanoclaw|hermes|openclaw|gateway' || echo "no matching ports" echo " === Disk ===" df -h / echo " === Logs size ===" du -sh ~/ai-agents/logs 2>/dev/null || true du -sh ~/.hermes 2>/dev/null || true du -sh ~/.openclaw 2>/dev/null || true

    Permissions and Execution

    chmod +x ~/ai-agents/bin/health-check.sh ~/ai-agents/bin/health-check.sh

    Save Results

    mkdir -p ~/ai-agents/checks ~/ai-agents/bin/health-check.sh > ~/ai-agents/checks/health-$(date +%Y%m%d-%H%M%S).txt 2>&1

    41Auto-Recovery Scripts Come Later

    Beginners want to create auto-recovery scripts immediately. For example:

    But initially, auto-checking comes before auto-recovery:

    Order

    1. Manual check
    2. Check script
    3. Alert
    4. Limited auto-recovery
    5. Verify after recovery

    Badly Made Auto-Recovery

    Error detected → Unconditionally restart → Error again → Infinite restart → Log explosion → API waste

    Good Auto-Recovery

    Error detected → Save state → Restart once → Test → If failed, stop and alert

    42Stability Check Before Production

    Before switching to production, verify:

    Stability

    Security

    Operations

    Cost and Limits

    43Agent Prompt During Operations

    You can put this prompt in the agent during operations:

    You are a personal AI agent running on Mac mini. Current goal is stable long-term operations. Operations Rules: - Explain change reasons before modifying files. - Don't immediately execute delete commands. - Never output API keys, tokens, cookies, or session values. - Mask sensitive info when viewing logs. - When errors occur, distinguish between installation, Docker, gateway, messaging, API, or autostart. - Don't repeat the same task. - Message sending performed once only. - Record current state before long tasks. - Verify backup before updating. - Mark unverifiable items as UNKNOWN. Response Format: 1. Current State 2. Warning Signs 3. Commands to Check 4. Safe Actions 5. What to Record Next

    44Things Beginners Must Not Do

    Especially, don't run these commands immediately during operations:

    docker rm -f $(docker ps -aq) rm -rf ~/ai-agents/logs rm -rf ~/.hermes rm -rf ~/.openclaw kill -9 $(ps aux | grep gateway | awk '{print $2}')

    An operator is not someone who deletes quickly, but someone who recovers safely.

    45Practical Operations Completion Checklist

    When you pass these items, Section 13 is complete:

    24-Hour Operations

    Log Management

    Updates

    Test/Production Separation

    Incident Recovery

    Mac mini Server Operations

    Documentation

    46Core Principle of Practical Operations

    The core of practical operations is not to turn on many features, but to start small and maintain stability long-term.

    The most important principles:

    1. Test 24 hours before operating 24 hours
    2. Logs come first to rotation and root cause, not deletion
    3. Update when you have time to rollback
    4. Always separate test and production environments
    5. When failure occurs, recover from smallest unit
    6. Mac mini is quiet but must be managed like a server
    7. RUNBOOK and incident records are operational skills

    The sentence beginners should remember:

    Running a personal AI agent is not something you do once and finish. It's building stability by checking frequently, updating carefully, and recording when problems occur.

    After passing Section 13, you're not just someone who runs an agent on Mac mini, but someone with basic operational habits for 24-hour personal AI agent management.

    14. Real-World Case 1: Creating a Personal Assistant Agent

    01What We Do in This Section

    In this section, we create a personal assistant AI agent running on Mac mini.

    The personal assistant agent we're discussing here is not an all-purpose secretary that does everything like a person. The initial goal must be small and safe.

    Goals of This Section

    Organize today's tasks every morning. Receive simple requests via message. Handle schedules, notes, to-do items, and reminders in one place. Never execute important tasks without user approval. Separate real-use accounts from test accounts. Keep logs and backups to make it operable.

    02The Danger of Personal Assistants That Beginners Want

    A personal assistant that beginners typically try to build from scratch usually looks like this.

    "A secretary that reads my email, organizes my schedule, writes replies, organizes my files, and handles everything before I even ask."

    But in practice, this approach is risky.

    Why It's Dangerous

    Email and calendar contain sensitive information. If a messaging account is connected incorrectly, replies can go to the wrong people. API keys and OAuth tokens can be exposed. The agent can misunderstand and execute real tasks. Personal information can remain in logs.

    03Step-by-Step Design Method

    Therefore, in this section we build in the following order.

    1Read-only personal assistant
    2Summary-focused personal assistant
    3Personal assistant with approval before execution
    4Limited automation personal assistant

    We do not build auto-executing assistants from the beginning. An initial goal is sufficient: "When I message, the personal assistant organizes and briefly answers based on today's schedule, to-do items, and recent notes."

    04Lessons from Real Examples

    Repeated real-world usage patterns of personal assistant agents appear similarly across public projects and communities.

    Morning briefing
    Calendar schedule summary
    Email summary
    Draft message writing
    Reminder creation
    To-do list organization
    Pre-meeting material preparation
    File or note search
    Quick web research
    Work channel summary

    However, actual operators typically encounter one problem: "I can build the features, but it's hard to trust and delegate to it."

    05The Problem of Operational Trust

    The reasons are as follows.

  • You don't know what information the agent based its answer on
  • It treats old notes as if they were current information
  • Immediately executing schedule changes is risky
  • Actually sending email replies can cause accidents
  • When there are too many notifications, users ignore them
  • When test bot and production bot mix, tracing cause becomes difficult

    • That's why a personal assistant agent should be designed based on "how much can we trust and delegate" rather than "how much can it do."

    06Eight Design Principles

  • Start with read-only at first
  • Draft replies only; never auto-send
  • Always get user approval for schedule changes
  • Restrict access scope for notes and files
  • Report in the same format daily
  • Say "I don't know" when uncertain
  • Mark unknown sources as UNKNOWN
  • Operate in a test channel for one week before real use

    • 07What the Agent Should Do

    First, clarify what the agent should and should not do.

    Should Do

    Summarize today's schedule | Organize today's to-do list | Summarize important messages | Organize notes sent directly by user | Draft reminders | Draft email replies | Create pre-meeting checklists | Ask end-of-day retrospective questions | Recommend next actions

    08What the Agent Should Not Do

    The initial version does not do the following.

    Prohibited

    Send email without user approval | Change schedule without user approval | Delete files without user approval | Make payments without user approval | Send messages to outsiders without user approval | Scan entire personal email account | Read all messaging channels | Make real-time trading decisions

    09Choosing the Agent Name

    Choose a name simply so the function is visible.

    Recommended names
    personal-assistant | daily-briefing | schedule-helper | inbox-helper | life-admin
    Names to avoid
    everything-agent | super-secret-ai | real-main-final-agent | auto-everything

    In operations, a short name with clear purpose makes logs easy to read.

    10Five Minimum Features

    The initial version includes only these five features. Expand features after operating these five reliably.

  • Today's briefing
  • To-do list organization
  • Note saving
  • Message summary
  • Draft reply writing

    • 11Today's Briefing Feature

    The user sends a message in the morning: "Give me today's briefing."

    The agent replies in this format.

    Schedule
    Things with set times
    To-do
    Things to do but without fixed times
    Messages to check
    Things needing reply or review
    Things to watch for
    Risks like conflicts, deadlines, needed items, travel time

    The important thing is not mixing schedules, to-do items, and messages in the reply.

    12To-Do List Organization Feature

    The user sends something like this.

    Add to-do:

    The agent doesn't immediately write to an external app. Instead, it organizes and responds first. It doesn't force dates onto items without dates.

    Good response
    "Check credit card payment date" needs a date. If I don't know the date, I'll leave it as UNKNOWN.
    Bad response
    The credit card payment date is probably the 25th.

    13Note Saving Feature

    The initial version doesn't use complex databases. First, save to a local markdown file.

    Create folder:

    mkdir -p ~/ai-agents/workspace/personal-assistant/notes

    Today's note file:

    touch ~/ai-agents/workspace/personal-assistant/notes/$(date +%Y-%m-%d).md

    At first, ask for confirmation before saving: "Is it okay to save?"

    14Message Summary Feature

    The user pastes a long message: "Summarize the message below."

    The agent replies like this.

    Summary
    What the other person said
    Action
    What I need to do
    Draft
    How to reply to them

    The important thing is to separate "summary" and "action."

    15Reply Draft Writing Feature

    The initial personal assistant does not actually send.

    User: "Write a polite draft reply to this message. [other person's message]"

    The agent drafts only and never sends immediately.

    Initial Rules

    Draft replies only | User sends manually | Auto-send reviewed in phase 2 and later

    16Overall Architecture Design

    The personal assistant agent starts with the following structure.

    1User
    2Messaging app or local CLI
    3NanoClaw / Hermes Agent / OpenClaw gateway
    4Personal assistant agent
    5Workspace folder and response

    At first, minimize external app integration.

    Initial connections
    local CLI | Telegram test bot | personal test chat room | local workspace folder
    Later connections
    Gmail | Google Calendar | Slack | Notion | Apple Reminders | file search

    17Recommended Folder Structure

    Create the following folder structure.

    mkdir -p ~/ai-agents/projects/personal-assistant
    mkdir -p ~/ai-agents/workspace/personal-assistant/{inbox,outbox,notes,tasks,briefings,logs}
    mkdir -p ~/ai-agents/backups/personal-assistant

    Verify:

    tree ~/ai-agents/workspace/personal-assistant 2>/dev/null || find ~/ai-agents/workspace/personal-assistant -maxdepth 2 -type d

    18Creating Basic Files

    Create necessary basic files.

    touch ~/ai-agents/workspace/personal-assistant/tasks/todo.md
    touch ~/ai-agents/workspace/personal-assistant/notes/general.md
    touch ~/ai-agents/workspace/personal-assistant/briefings/daily.md
    touch ~/ai-agents/projects/personal-assistant/RUNBOOK.md

    The todo.md file structure divides into "Today | This week | Needs date | On hold."

    The daily.md file structure records as "YYYY-MM-DD | Schedule | To-do | Messages | Things to watch."

    19Restricting Access Scope

    Restrict the folders the personal assistant agent can access.

    Allowed
    ~/ai-agents/workspace/personal-assistant
    Blocked by default
    ~/Desktop | ~/Documents | ~/Downloads | ~/.ssh | ~/.config | ~/.openclaw | ~/.hermes | .env files | credential files | token files

    Must include in operational prompts.

    20Creating Environment File

    Create an environment configuration file.

    mkdir -p ~/ai-agents/environments/personal-assistant
    nano ~/ai-agents/environments/personal-assistant/.env

    Example:

    AGENT_NAME=personal-assistant
    AGENT_ENV=test
    DEFAULT_CHANNEL=telegram-test
    LOG_LEVEL=info
    WORKSPACE_DIR=/Users/username/ai-agents/workspace/personal-assistant

    Restrict permissions:

    chmod 600 ~/ai-agents/environments/personal-assistant/.env
    }

    21Connect to Test Channel First

    The first connection is to a test channel, not a real-use channel.

    Recommended order
    local CLI → Telegram test bot → test chat room with only you → production channel
    Order to avoid
    Work Slack whole channel → family chat room → customer chat room → real-use WhatsApp account

    22Basic Operating Prompt

    Put the following prompt in the personal assistant agent.

    You are a personal assistant AI agent running on Mac mini.

    Current phase is pre-production testing.

    Your role:
    - Organize today's schedule and to-do items.
    - Summarize messages pasted by user.
    - Draft replies.
    - Organize notes.
    - Request user confirmation before important tasks.

    Rules:
    - Don't guess unconfirmed information; mark as UNKNOWN.
    - Never send email, messages, or change schedule without user approval.
    - Never print API keys, tokens, cookies, session values, or passwords.
    - Do file operations only within ~/ai-agents/workspace/personal-assistant.

    23Four-Level Safety Rating Design

    Personal assistants have different risk levels by feature.

    Level 1: Read-only
    Allow: Message summary | Schedule organization | Local note reading | To-do summary | Prohibit: Writing to external apps | Sending messages | Changing schedule | Deleting files
    Level 2: Draft writing
    Allow: Email reply drafts | Slack reply drafts | Schedule change proposals | To-do addition proposals | Prohibit: Actual sending | Actual schedule changes | Auto messages to outsiders
    Level 3: Execute with approval
    Allow: Save notes after user approval | Add to-do | Create calendar events | Send messages | Conditions: Summarize changes before execution | Clearly mark execution target | Report result after execution
    Level 4: Limited automation
    Allow: Daily morning briefing | End-of-day check-in | Keyword notifications | Prohibit: Outbound automation | Payments | Deletions | Sensitive file access

    For the first 3 days, operate only Level 1. Do Level 4 only after Levels 1-3 stabilize.

    24Test Checklist

    Must pass the following before real use.

    Basic Response

    [ ] Responds to test messages | [ ] No duplicate replies | [ ] Response format is consistent | [ ] Marks with UNKNOWN

    Briefing

    [ ] Separates and organizes schedule | [ ] Distinguishes to-do from schedule | [ ] Marks things to watch | [ ] Distinguishes old notes from current info

    Reply Draft

    [ ] Never actually sends | [ ] Clearly marks as draft | [ ] No made-up content | [ ] Polite and brief

    Security

    [ ] Doesn't print API keys | [ ] Doesn't read .env | [ ] No auto-access outside workspace | [ ] Marks with UNKNOWN

    25Real-World Example: Morning Briefing

    User message:

    Give me today's briefing.

    Confirmed information:
    - 10:00 team meeting
    - 15:00 hospital
    - Write report draft by today

    Notes:
    Yesterday's meeting said to recheck budget table

    The agent separates and replies with: schedule | must-do items | deferrable items | things to watch | recommended order | UNKNOWN. It doesn't guess and marks info without confirmation as UNKNOWN.

    26Real-World Example: Pre-Meeting Prep

    User: "I have a team meeting in 30 minutes. Organize what I need to prepare."

    The agent structurally organizes: key messages | order to speak | questions to confirm during meeting | post-meeting to-do.

    In this process, the agent bases its response only on what the user said. It doesn't add guesses or background knowledge.

    27Real-World Example: Email Reply Draft

    User: "Write a draft reply to the email below."

    The agent drafts but never sends.

    At this stage, we only draft. The user sends it themselves.

    28Real-World Example: End-of-Day Wrap-up

    User: "Wrap up my day. Completed: team meeting, hospital, wrote report outline. Not completed: check budget table, write report body."

    The agent replies with: completed items | remaining items | recommend first task tomorrow | draft tomorrow morning plan.

    This reply is also just a plan; the agent doesn't auto-change the schedule.

    29Four Common Issues in Real Operations

    1. Too many notifications
    Good setting: morning briefing once | once before important schedule | summary only on request | end-of-day wrap-up once | about 2 notifications daily
    2. Too many permissions
    Recommended order: local CLI → test messaging → local markdown → calendar read → email read → reply draft → approval then schedule creation → approval then message send
    3. Treats old information as current
    Solution: Date notes | distinguish recent from old notes | mark source and date | mark old notes as "past note"
    4. Makes up things user didn't say
    Prevention: no date means no date | no attendee means UNKNOWN | no email content means none | no access means none marked

    30Feature Expansion Roadmap

    Learning order for beginners.

    Week 1: Manual assistant
    Message summary | Reply draft | To-do organization | Note saving proposal | Goal: stabilize response format
    Week 2: Briefing assistant
    Morning briefing | End-of-day wrap-up | Schedule conflict check | To-do prioritization | Goal: keep same format daily
    Week 3: Read integration
    Calendar read | Email metadata | Slack summary | Local note search | Goal: use read permission only
    Week 4: Approval-based execution
    Approval-based note save | Schedule draft creation | Reminder registration | Message sending | Goal: fix format before execution confirmation

    31Creating a RUNBOOK

    Create an operational document.

    nano ~/ai-agents/projects/personal-assistant/RUNBOOK.md

    Include: purpose | current phase | execution method | messaging channel | allowed features | prohibited features | status check | log check | test message | stop and restart | backup location | first steps in outage.

    32Ten Things Beginners Must Not Do

  • Don't give full Gmail access from the start
  • Don't give calendar write permission from the start
  • Don't turn on auto email sending from the start
  • Don't test with real-use messaging accounts
  • Don't let it read all messages in all channels
  • Don't open your entire home directory to the agent
  • Don't let it treat old notes as current information
  • Don't let it guess unknown information
  • Don't log unlimited email body and personal info
  • Don't put test bot and production bot in the same channel

    • 33Completion Criteria

    Completing the following means you finish Section 14.

    Design

    [ ] Define what to do [ ] Define what not to do [ ] Safety levels 1-4 [ ] Initial features 5 or fewer

    Environment

    [ ] Workspace folder | [ ] todo.md | [ ] daily.md | [ ] notes folder | [ ] RUNBOOK.md

    Messaging

    [ ] Local CLI or test channel [ ] Separate real-use from test [ ] Normal response [ ] No duplicate replies

    Features

    [ ] Today briefing [ ] To-do organization [ ] Confirm before note save [ ] Message summary [ ] Reply draft

    Security

    [ ] Doesn't print API keys [ ] Doesn't read .env [ ] Access restricted [ ] No auto-execute deletion [ ] Marks with UNKNOWN

    34Key Takeaways from This Section

    A personal assistant agent is not an agent that acts freely on the user's behalf, but an agent that helps the user make faster decisions and execute safely.

    The most important order is: read-only → summary → draft → execute with approval → limited automation

    The one sentence beginners should remember is this: "A good personal assistant agent is not one that does a lot of work, but one that trusts users and prioritizes user approval."

    Next Section

    After building the basic structure of a personal assistant agent, we more strictly separate what features to allow and prohibit when creating trading assistant alert bots and work automation agents.

    15. Real-World Case 2: Building a Trading Alert Helper Bot

    01What You Do in This Unit

    This unit has three goals.

    First, you build a notification structure that alerts you when price conditions are met.

    Second, you build a structure that summarizes important news and market events and sends them.

    Third, you set up the agent to assist with trading journals and risk checklists.

    You don't need to build it all at once from the start. The safest way to create a trading alert helper bot is in this order:

    1. Price alerts
    2. News summary alerts
    3. Trading journal record assistance
    4. Risk checklist
    5. Limited automation after user approval

    02Project Structure Design

    The result you create in this unit has the following structure:

    trading-assistant/ ├── README.md ├── RUNBOOK.md ├── alerts/ │ ├── price-rules.md │ ├── news-rules.md │ └── risk-rules.md ├── logs/ │ ├── alerts.log │ └── trades-journal.md └── prompts/ ├── trading-bot-system-prompt.md ├── alert-summary-prompt.md └── risk-check-prompt.md

    At the start, structure matters more than code. You need to decide first which alerts to receive, which to skip, and which information requires citation.

    03What You Should Do and What You Shouldn't

    A trading alert helper bot should do the following:

    On the other hand, things you must never do should also be clear:

    An alert bot does not make decisions for the trader. An alert bot organizes information that must be checked before making a decision.

    04System Prompt Design

    You must embed this principle clearly in the system prompt:

    You are a trading alert helper bot. You do not instruct buy, sell, or hold. You do not make investment decisions. You organize conditions, prices, news, and risk checklists that the user defined. Information without source is not stated definitively. Uncertain information must be marked as uncertain.

    This single sentence difference is critical. If the agent starts saying "You should buy," it's dangerous. Instead, it should say "The condition you set has been reached. Items to check are as follows."

    05Price Alert Structure (1/2)

    Price alerts are the simplest yet most practical feature. For example, a user sets conditions like this:

    Alert me when BTC breaks $70,000. Alert me when ETH moves 3% or more in 5 minutes. Alert me when AAPL falls 2% or more from previous close.

    At this point, the alert bot must distinguish three types.

    First, simple price threshold alert:

    [Price Alert] Symbol: BTC Condition: Break $70,000 Current Price: $70,120 Status: Condition Met Time: 2026-06-14 09:15

    Second, volatility alert:

    [Volatility Alert] Symbol: ETH Condition: 3% or more movement in 5 minutes Current Movement: +3.4% Status: Condition Met Verify: Trading volume, news, key support/resistance levels

    06Price Alert Structure (2/2) — Cooldown Rules

    The most annoying problem with alert bots is the same alert repeatedly coming in. That's why price alerts must have cooldown rules:

    Do not repeat the same alert within 30 minutes. However, if price moves 1% or more from the condition price, send one additional alert.

    You can write the price alert rules file like this:

    ## Common Rules - Do not repeat the same alert within 30 minutes. - Alert must include symbol, condition, current price, and time. - Do not include buy or sell opinion. - Monitor only conditions the user defined. ## BTC Alerts - Alert on break of $70,000 - Alert on fall below $68,000 - Alert on 2.5% or more movement in 5 minutes

    It's best not to add too many symbols at first. Start with 3 symbols or fewer, verify alert quality, then expand.

    07News Summary Alert Structure (1/2)

    In trading, news alerts are useful but risky. News spreads fast, but so does misinformation. Therefore, news summary alerts need these principles:

    Example of a good news alert:

    [News Summary Alert] Symbol/Asset: BTC Category: Regulation / ETF / Macroeconomy Source: Example News Source Published: 2026-06-14 08:40 Summary: - Reports show Bitcoin ETF inflows in the US market have increased. - The article mentions possibility of increased institutional demand. - Short-term price impact has not been confirmed. Warning: - This alert is not investment advice. - Must verify with price, volume, and existing scenario.

    08News Summary Alert Structure (2/2) — News Summary Prompt

    A bad news alert looks like "BTC major catalyst. Buy now." You must never create this kind of alert.

    You can create the news summary prompt like this:

    Summarize the following news for trading assistance. Rules: 1. Distinguish headline and body content. 2. Distinguish confirmed facts from speculation. 3. Mark source and publication time. 4. Do not offer buy, sell, or hold opinion. 5. Do not conclude price impact. 6. If the news might be old, highlight the date.

    09Trading Journal Record Assistance (1/2)

    One of the most important tools for improving trading skill is a trading journal. However, in practice, recording every time is tedious.

    Using an agent can reduce the recording burden. A user sends a message like this:

    BTC long entry. 70100. Reason: 1-hour candle breakout. Stop 69400. Target 71500.

    The alert bot can organize it like this:

    ## Trading Journal - Date/Time: 2026-06-14 09:32 - Asset: BTC - Direction: Long - Entry Price: 70,100 - Entry Reason: 1-hour candle breakout - Stop-Loss Level: 69,400 - Target Range: 71,500 - Position Size: Not entered - Emotional State: Not entered - News Event Check: Not entered ## Items to Verify - Did you record position size? - Is your stop-loss set as actual order or alert? - Did you check major news events before entry?

    10Trading Journal Record Assistance (2/2) — Record Assistance Prompt

    The key here is that the agent is a record assistant, not an evaluator. You must not make it judge "good entry" or "bad entry."

    You can use the trading journal assistance prompt like this:

    You are a trading journal record assistant. Organize and record the user's trading message in structured form. Do not evaluate buy or sell decisions. If items are missing, organize them as a list of questions. Items to always include: - Date/Time - Asset - Direction - Entry Price - Entry Reason - Stop-Loss Level - Target Range - Position Size - Emotional State - News Event Check Status

    At first, automatic saving is less safe than draft creation. The agent sends a trading journal draft, user checks, then saves.

    11Risk Management Checklist (1/2)

    The real value of a trading alert helper bot comes from risk management. Anyone can build price alerts. But a bot that makes you check risk once more before entry has real practical value.

    A user says this:

    Should I short the Nasdaq?

    The bot must not say "You can enter." Instead, it should respond like this:

    [Pre-Entry Risk Check] I do not make buy or sell decisions. Check the items below before entry. 1. Entry Reasoning - Why are you shorting now? - What's your time frame? 2. Stop-Loss Level - Where is your invalidation price? - What % loss is your stop versus account? 3. Position Size - What is maximum loss amount for this trade? - Are you using leverage? 4. Event Risk - Are there major economic indicators or speeches today? - Is it near market open or close? 5. Emotional State - Is this revenge trading? - Is this after consecutive losses? - Is this a planned entry?

    12Risk Management Checklist (2/2) — Risk Rules File

    This kind of response doesn't interfere with user judgment while reducing impulse trading.

    You can create the risk checklist file like this:

    ## Pre-Entry Check - Is entry reasoning clear? - Is there a stop-loss level? - Is there a target range? - Is position size reasonable versus account? - Have you checked leverage use? - Have you checked major news events? - Is this an emotional entry? ## Pre-Exit Check - Is this exit per original plan? - Have you hit stop-loss level? - Have you hit profit target? - Are you exiting from fear or greed? ## Forbidden Responses - Buy now - Sell now - It will definitely go up - It will definitely go down - Don't use stop-loss - Increase your leverage

    Risk management is the first feature you must stabilize in a trading alert helper bot.

    13Testing Methods (1/2)

    A trading alert helper bot must be tested before actual use.

    First is simulated alert test:

    Test: Assume BTC broke $70,000 and create alert message.

    A correct response must meet these conditions:

    Second is duplicate alert test:

    Assume the same BTC $70,000 break alert occurs again within 5 minutes.

    A correct response should not send duplicate or should mark "cooldown active" like this:

    [Alert Pending] Condition: BTC break $70,000 Reason: Same alert was sent 5 minutes ago Next alert available: 09:55

    14Testing Methods (2/2) — Data and Market Hours Testing

    Third is bad data test:

    Assume BTC current price comes in as UNKNOWN.

    A correct response must not fabricate prices:

    [Alert Pending] Reason: Current price data not confirmed Action: Check price data source

    Fourth is market closed test:

    Products with set trading hours like stocks or futures must distinguish holidays and off-hours:

    Assume AAPL price alert occurs on weekend.

    A correct response should request market hours verification:

    [Verification Needed] AAPL may not be in regular trading hours. Price data may be delayed or off-hours basis, verification needed.

    Only after passing these tests should you connect to actual alert channels.

    15Real Usage Examples (1/2)

    Price Threshold Alert:

    [Price Alert] Symbol: BTC Condition: Break $70,000 Current Price: $70,120 Time: 2026-06-14 09:15 Status: Condition Met Items to Check: - Whether trading volume increased after break - Whether aligned with existing scenario - Whether stop-loss is set Warning: This alert is not a buy or sell decision.

    Volatility Spike Alert:

    [Volatility Alert] Symbol: ETH Condition: 3% or more movement in 5 minutes Current Movement: +3.4% Time: 2026-06-14 10:05 Items to Check: - Whether news occurred - Whether volume surged - Whether approaching key support/resistance - Whether already late for chasing entry

    16Real Usage Examples (2/2)

    News Summary Alert:

    [News Summary Alert] Asset: BTC Category: Market News Source: User-provided link Published: Needs verification Key Content: - Per headline, Bitcoin-related market movement is mentioned. - Until body is checked, price impact cannot be concluded from headline alone. Verify: - Publication time - Original source - Actual price reaction - Volume change

    Trading Journal Assistance:

    [Trading Journal Draft] Date/Time: 2026-06-14 11:20 Asset: BTC Direction: Long Entry Price: 70,100 Entry Reason: 1-hour candle breakout Stop-Loss Level: 69,400 Target Range: 71,500 Position Size: Not entered Emotional State: Not entered Additional Verification Questions: 1. What is the maximum loss % for this trade? 2. Did you check news events before entry? 3. Is this a planned entry or spontaneous?

    This level alone is practical enough for actual trading routines.

    17What Beginners Must Not Do

    First, don't build automatic trading from the start. An agent understanding messages and executing orders is very risky. Typos, duplicate messages, bad data, API errors, and network delays all become real losses. At first, use only alerts and recording.

    Second, don't send alerts without sources. In trading, accuracy matters more than speed. Information without source should be marked "verification needed."

    Third, don't just pile up alerts without stop-loss criteria. More price alerts can increase entry impulses. An alert bot should organize conditions to verify, not multiply opportunities.

    Fourth, don't make it sound like investment advice. The agent must not use phrases like "buy," "sell," "enter now," "certain," "guaranteed up," "guaranteed down," "don't use stop-loss," "increase leverage."

    Instead, use phrases like "condition reached," "items to verify are," "check if aligned with your criteria," "source verification needed," "risk check needed." This difference is key to safe operation.

    18Trading Alert Helper Bot Completion Criteria (1/2)

    A trading alert helper bot must pass these criteria before going live.

    Data Checklist

    Alert Checklist

    19Trading Alert Helper Bot Completion Criteria (2/2)

    News Summary Checklist

    Risk Management Checklist

    Operations Checklist

    Completion is not "alerts arrive." Completion is "reduce wrong alerts, don't make decisions, and help user risk management."

    20Core Takeaway from This Unit

    A trading alert helper bot is not automatic trading.

    A good alert bot doesn't make decisions for the user. Instead, it organizes price, news, records, and risk items the user might miss.

    Start with price alerts and trading journal assistance first. News summaries must always show source and time, and risk checklists must become a pre-entry habit.

    Three core operating principles are critical.

    1. Show source and time.
    2. Reduce duplicate alerts.
    3. User makes buy or sell decisions.

    Following these principles, NanoClaw or HermesClaw on your Mac mini can become more than a simple messaging agent — it becomes a practical trading assistant that organizes your routine.

    16. Real-World Case 3: Building a Work Automation Agent

    01What You'll Do in This Section

    A work automation agent divides into three goals.

    First, find repetitive work and classify it as automation candidates. Second, build a structure to summarize messages and documents and organize action items. Third, create a workflow where tasks requiring execution get user approval before processing.

    Trying to automate all work from the beginning is easy to fail at. It's safer to start work automation in this order:

    1. Read-only summaries
    2. Classification and organization
    3. Draft creation
    4. Execution after approval
    5. Limited repeated automation

    02Output Directory Structure

    A work automation agent prioritizes rules over functionality. You must first decide what can be done, what must not be done, and what's only possible after approval.

    The deliverable from the agent we build in this section has the following structure:

    work-agent/ ├── README.md ├── RUNBOOK.md ├── rules/ │ ├── message-classification.md │ ├── summary-rules.md │ ├── file-organizing-rules.md │ └── approval-rules.md ├── logs/ │ ├── actions.log │ └── approvals.log └── prompts/ ├── work-agent-system-prompt.md ├── message-summary-prompt.md ├── action-item-prompt.md └── approval-check-prompt.md

    03Characteristics of Good Automation Candidates

    The first step in work automation is finding repetitive work. Good automation candidates have these characteristics:

    For example, summarizing messages every morning that need reading, organizing action items after meetings, drafting email replies, creating file organization candidates in the downloads folder, drafting weekly work reports, and classifying customer inquiries by type are potential automation candidates.

    04Work That's Dangerous to Automate

    Conversely, there's work dangerous to automate. Agents must never automatically execute the following tasks:

    Don't give execution authority to work automation agents from the start. Initially, it should be an "organization-only agent."

    Initially, "safely reducing one repeated task" is more important than "doing a lot of automation."

    05File for Organizing Automation Candidates

    You can create a file organizing repetitive work like this:

    # automation-candidates.md ## Automation Candidates ### Repeated Daily - Morning message summary - Today's to-do list organization - Key email classification ### Repeated Weekly - Weekly work report draft - Meeting notes organization - Incomplete task list organization ### Dangerous to Automate - Email auto-sending - File auto-deletion - Customer info external sharing - Payment or contract-related execution ## Current Automation Stage - Stage 1: Read-only - Stage 2: Draft creation - Stage 3: Execution after approval

    06Importance of Message Classification

    The most basic function of a work automation agent is message classification. If you treat all incoming daily messages with equal importance, fatigue rises. When an agent classifies messages like this, it's easier to prioritize what to check:

    1. Urgent messages
    2. Messages needing replies
    3. Reference messages
    4. Messages to hold
    5. Spam or ignorable messages

    Classification criteria must be clear. If criteria are ambiguous, agents can't judge consistently.

    07Message Classification Rules

    You can set message classification rules like this:

    Urgent messages: Requests needing handling today, content about outages, errors, payments, contracts, customer complaints, direct requests from superiors or key customers, deadline changes or approaching deadlines

    Messages needing replies: Messages containing questions, messages with confirmation requests, messages needing schedule coordination, messages requesting materials

    Reference messages: Announcements, newsletters, meeting shared materials, progress updates not needing replies

    Messages to hold: Requests with insufficient information, requests with unclear responsibility, content difficult to judge now

    Prohibitions: The agent doesn't send replies arbitrarily, and marks ambiguous urgency as "needs verification." Don't make up names, customer names, amounts, or schedules.

    08Message Classification Result Example

    Actual message classification results can look like this:

    [Message Classification Result] Classification: Needs reply Sender: Kim OO Key content: Inquiry on whether meeting time change is possible tomorrow Action needed: Confirm available time and reply Urgency: Medium Estimated deadline: Reply recommended today Note: Don't confirm answer before checking calendar

    The important point here is separating "classification" from "execution." The agent can tell you replies are needed, but the actual reply should be sent after user verification.

    09Good Format for Work Summaries

    The most used function in work automation agents is summarization. Summary subjects include meeting content, Slack/Discord messages, emails, long documents, customer inquiries, work instructions, and project progress updates.

    Good summaries aren't just short. They must be directly usable in work. Work summaries work well in this format:

    [Work Summary] Key content: - Decided matters: - Action items: - Responsible: - To do: - Deadline: Needs verification: - Risks: -

    10Meeting Summary Prompt

    You can make meeting summary prompts like this:

    You are a work meeting summary assistant. Summarize the following content for work use. Rules: 1. Distinguish core content from action items. 2. Separately mark responsible parties, to-do items, and deadlines. 3. Don't write uncertain content as final. 4. Put missing information in "needs verification." 5. Don't make up content not in the meeting. Output format: [Meeting Summary] - Key content: - Decided matters: - Action items: - Needs verification: - Risks:

    11Real Meeting Summary Example

    Assuming meeting notes say "Make landing page draft within this week, review ad materials on Monday next week. Minsu will draft copy, Jiyeon will do design mockup. Budget not yet confirmed," the agent should organize it like this:

    [Meeting Summary] Key content: - Decided to prepare landing page draft within this week. - Decided to review ad materials on Monday next week. Action items: - Minsu: Draft copy - Jiyeon: Design mockup Needs verification: - Budget confirmation status - Exact deadline date for landing page draft - Ad material review time Risks: - Ad campaign timeline could slip if budget isn't confirmed.

    This summary can be directly used to organize work flow.

    12Safe Structure for File Organization Automation

    File organization automation is convenient but requires care. Making agents automatically delete or move files from the start is risky. It's safer to first create only "organization candidates" and execute after user verification.

    When there are many files in the downloads folder, the agent can create organization candidates like this:

    [File Organization Candidates] 1. Document candidates - 2026_project_plan.pdf - meeting_notes.docx Recommended folder: - Documents/Work/Projects/ 2. Image candidates - screenshot-2026-06-14.png - chart-export.png Recommended folder: - Pictures/Screenshots/ 3. Duplicate suspicion candidates - report_final.pdf - report_final_copy.pdf Recommended action: - Don't auto-delete; have user verify directly

    13File Organization Rules

    You can set file organization rules like this:

    Basic principle: Don't delete automatically, and don't move automatically at first either. Only create organization candidate lists, and execute filename changes after user approval. Mark duplicate files as "verification candidates" not "deletion candidates."

    Classification criteria: Documents (pdf, docx, hwp, txt, md), Images (png, jpg, jpeg, webp), Compressed files (zip, tar, gz), Development files (js, py, json, yaml, env)

    Risky files: Don't automatically modify or move .env files, key files, certificate files, contracts, tax documents, or files containing customer information.

    14File Move Verification Example

    In actual operations, it's good to have agents show command drafts first instead of directly changing files:

    [Verification Before Execution] Proposing the following file move. Before move: ~/Downloads/meeting_notes.docx After move: ~/Documents/Work/Meetings/meeting_notes.docx Reply with "approve" to execute.

    Following this structure lets you operate file organization automation safely too.

    15Approval-After-Execution Structure

    The most important structure in work automation is execution after approval. Dividing what agents can do into four stages is safe:

    1. Reading
    2. Organization
    3. Draft creation
    4. Execution after user approval

    For example, email reply automation should be structured like this: When a user requests "Make a draft reply to this email," the agent drafts but doesn't send. When the user says "Good. Send," the agent verifies once more before sending.

    16Approval Rules Definition

    Approval rules must be clear.

    Possible without approval: Summarizing, classifying, generating checklists, drafting email replies, generating file organization candidates

    Possible after approval: Sending emails, creating calendar events, moving files, renaming files, generating external sharing links

    Prohibited tasks: Auto-deleting files, executing payments, auto-sending contracts, externally sending customer information, outputting passwords or API keys, sending bulk messages without user verification

    Approval message: Before execution, must show the task to execute, target, state before change, state after change, how to revert, and required approval phrase.

    17Execution Approval Request Example

    Actual approval request messages can be created like this:

    [Execution Approval Request] Task: File move Target: ~/Downloads/report.pdf Move location: ~/Documents/Work/Reports/report.pdf Notes: - This task changes file location. - It does not delete. - If there's a problem, can move back to Downloads folder. To execute, enter the following phrase exactly. Approve: report.pdf move

    Making approval phrases specific reduces problems when users accidentally reply with "yes" or "okay."

    18Morning Work Briefing Example

    An actual usage example is like this. Morning work briefing:

    [Morning Work Briefing] Items to check today: 1. Team meeting at 10am 2. 3 unanswered emails from yesterday 3. 2 tasks with deadline today Priorities: - Customer inquiry replies - Final meeting material verification - Weekly report draft creation Notes: - Need to recheck schedule changes in calendar

    19Action Item Organization Example

    Organizing action items after a meeting:

    [Action Item Organization] Meeting topic: New landing page production Decided matters: - Create draft within this week - Review ad materials Monday next week To do: 1. Minsu: Draft copy 2. Jiyeon: Design mockup 3. User: Confirm budget status Needs verification: - Exact deadline - Ad material review time - Budget confirmation status

    20Email Reply Draft Example

    Email reply draft:

    [Email Reply Draft] Hello Kim OO. Confirmed your email about meeting schedule change. I'll check available time and reply again. Thank you. Notes: - Not yet sent. - Must add actual available times after checking calendar.

    21File Organization Candidate Example

    Downloads folder organization candidates:

    [Downloads Folder Organization Candidates] Document files: - project_plan.pdf - meeting_notes.docx Image files: - screenshot-001.png - chart-export.png Suspected duplicates: - report_final.pdf - report_final_copy.pdf Recommendation: - Don't delete; verify first. - Proceed with move only after user approval.

    With just this much functionality, you can significantly reduce work time and organization fatigue.

    22Points to Watch During Operation

    Work automation agents require more care than personal assistant agents. Work data can contain customer information, internal documents, contract content, schedules, and payment information.

    First, minimize work account permissions. Don't connect full Gmail, full Drive, full Calendar permissions from the start—limit to necessary folders, labels, and channels first.

    Second, protect customer and personal information. When the agent creates summaries, ensure customer names, phone numbers, emails, contract amounts, and similar information don't go to external logs or messaging channels.

    23Security and Audit Logs

    Third, prohibit auto-sending. The riskiest automation in work is auto-sending. Email, customer messages, and contract notices must be sent only after user verification.

    Fourth, keep audit logs. Record what requests the agent received, what drafts it created, and what tasks it executed.

    [2026-06-14 09:30] Request: Meeting notes summary Task: Generate summary Executed: Read-only Result: Summary sent to user [2026-06-14 10:15] Request: Move report.pdf Task: Propose file move Executed: Awaiting approval Result: Not executed

    With operation logs, it's easy to find causes when problems occur.

    24Completion Criteria Checklist

    Work automation agents can only enter actual use after passing these criteria:

    Repetitive work definition: Is the automation work clear and non-automation work defined, stages of reading/organizing/drafting/execution separated, and work with high impact if mistakes happen excluded?

    Message classification: Are urgency criteria in place, reply-needed criteria in place, reference criteria in place, ambiguous messages classified as "needs verification," and agents not sending replies arbitrarily?

    Summary response: Are core content and action items distinguished, responsible parties/to-do/deadlines marked, non-existent content not invented, and uncertain content marked "needs verification"?

    25File Organization and Security Checklist

    File organization: Don't auto-delete, get approval before moving, don't touch risky files, mark duplicate files as verification candidates not deletion candidates, and show paths before and after change?

    Security: Minimized work account permissions, sensitive information not remaining in logs, external sharing not automated, customer and personal information protected, API keys and auth files not output?

    Operations: RUNBOOK.md exists, stopping method documented, action logs exist, approval logs exist, recovery method on failure exists?

    26Core of Completion Criteria

    Completion criteria is not "the agent executes something."

    Completion criteria is "users can confidently delegate repetitive organizing work."

    Defining and verifying this criterion clearly lets you build safer and more trustworthy work automation agents.

    27Key Summary of This Section

    Work automation agents should start with small repetitive tasks.

    At first, only entrust reading, summarizing, classifying, and draft creation. Tasks causing actual change like email sending, file moving, and schedule creation must execute only after user approval.

    Three principles matter most in work automation:

    Following these principles lets you use NanoClaw or HermesClaw not as a simple messaging agent, but as a practical work assistance system quietly running on Mac mini.

    17. Recommended Configurations Based on M4 / M5

    01Lightweight Entry-Level Configuration

    Suitable for people installing and testing NanoClaw or HermesClaw for the first time.

    The goal is simple. Install a messaging agent, test local CLI, connect to a test channel like Telegram or Discord, verify API-based responses, and confirm it runs again after rebooting.

    The core of entry-level configuration prioritizes these items over CPU performance:

    Recommended for

    Users installing NanoClaw for the first time, users testing HermesClaw structure, users wanting to operate just one or two messaging agents, users prioritizing API calls over local LLM

    Recommended direction

    Start with M4 base model, choose memory with one step of headroom above minimum requirements, don't set storage too small considering logs and Docker images

    Your Mac mini agent starts stably, receives messages, and sends responses.

    02Stable Practical-Use Configuration

    Suitable for people wanting to connect agents to real-life or work.

    Examples: Personal secretary agent, trading alert bot, work summary agent, schedule briefing agent, message summarization and auto-draft replies, 24-hour standby alert system.

    What to consider in practical-use configuration:

    Running one agent may feel light, but actual operation runs Docker, gateway, browser, terminal, logs, messaging apps, and backup scripts simultaneously.

    Practical-use criteria

    Does it not run duplicates? Does it revive after rebooting? Are API keys stored securely? Do logs grow excessively? Can it be recovered when problems occur?

    Recommended direction

    Consider M4 base or M4 Pro, choose memory with headroom, select storage generously above minimum, must include log rotation and backup structure

    03Local AI Experimentation Configuration

    Suitable for people wanting to run models directly on Mac mini.

    Local AI experimentation: run local LLM, test small model inference, document summarization experiments, test code assistant models, experiment with embedding or RAG, local response experimentation without API fallback.

    In local AI experimentation, memory often becomes more critical than CPU. Models must be loaded into memory, and Docker or gateway might run simultaneously.

    Lightweight experimentation
    Run small models, short document summarization, test-purpose local inference
    Mid-scale experimentation
    Compare multiple models, process long documents, RAG experimentation, run messaging agent alongside local model
    Production-grade local AI
    Extended local inference, run multiple agents and models in parallel, mixed operation with API fallback and local model

    Model files, Docker images, logs, and test data accumulate, and storage shrinks faster than expected.

    Recommended for

    Users wanting to reduce API costs, users wanting to run local LLM directly, users testing small models like Gemma or Llama families, users wanting to connect agents with local models

    Recommended direction

    Prioritize memory, choose storage generously, consider M4 Pro or later Pro line, also consider external SSD possibility

    It's good to start with small models and verify: Does the model run normally? Is response speed practical? Is memory pressure severe? Does it stay stable running alongside agents? Are heat and fan noise problems?

    0424-Hour Operation Configuration

    Cases where Mac mini is used like a small server.

    24-hour operation items to check: power stability, network stability, auto-startup, log rotation, disaster recovery, backup, heat management, remote access.

    Mac mini is quiet and low power, suitable for continuous operation, but you must verify these settings:

    In 24-hour operation, "how to recover when problems occur" matters more than performance.
    Essential documentation

    RUNBOOK.md: How to run/stop/restart/check logs/verify after rebooting. INCIDENTS.md: Incident time, symptoms, causes, solutions, prevention

    Recommended direction

    Choose memory and storage generously, prioritize wired network, when using external SSD choose stable products, must include auto-startup and log rotation settings

    05M4-Based Recommendations

    As of the writing date, Mac mini centers on M4 and M4 Pro configurations.

    If running only NanoClaw or HermesClaw, even M4 base can be a sufficient starting point. For messaging agents, API calls, Docker gateway, and simple auto-execution, stable operational structure matters more than high-performance GPU.

    M4 base recommended when
    Installing NanoClaw for the first time, using primarily API-based agents, connecting 1-2 messaging apps, testing local LLM lightly only, wanting to reduce costs, starting 24-hour operation small
    M4 Pro recommended when
    Operating multiple Docker containers, attaching gateway, database, vector store, etc., frequently experimenting with local AI, processing long documents or RAG experimentation, operating multiple agents simultaneously, planning long-term use as work automation server
    Memory decision — messaging agent focus
    Can start with base memory, practical use recommends one step of headroom
    Memory decision — API automation focus
    Running multiple tools simultaneously, so memory headroom recommended
    Memory decision — local AI experiment focus
    Prioritize memory as much as possible
    Memory decision — long-term operation focus
    Choose both memory and storage generously

    Using Mac mini as an automation server, these files accumulate continuously: Docker images, Docker volumes, log files, backup files, model files, test data, document summary cache.

    Entry-level
    M4 base, API-based use, start with one messaging agent
    Practical use
    M4 base advanced configuration or M4 Pro, memory and storage headroom recommended, include auto-startup/log rotation/backup
    Local AI experiment
    Prioritize M4 Pro, memory first, consider model storage
    Long-term operation
    Stability-focused, wired network, backup and RUNBOOK essential

    06Items to Check After M5 Official Launch

    You cannot assume that just because M5 arrived it's automatically better for your current purpose. For NanoClaw and HermesClaw operation, compatibility, stability, price, memory options, and Docker support may matter more than raw performance.

    1. Official specifications
    CPU configuration, GPU configuration, Neural Engine, memory options, storage options, memory bandwidth, port configuration
    2. Pricing
    Base price, memory upgrade cost, storage upgrade cost, comparison with M4 inventory or discount prices
    3. Docker compatibility
    Docker Desktop Apple Silicon support status, existing Compose files run normally, image compatibility, gateway container execution
    4. Local model performance
    Small model inference speed, memory usage, heat and power consumption, extended execution stability
    5. Operation stability
    Auto-startup after rebooting, launchd operation, network stability, log and backup structure

    Practical tests to run immediately after M5 launch: Docker execution (docker info), basic container execution (docker run hello-world), NanoClaw/HermesClaw installation test, reboot test, local model test.

    Worth waiting for
    Don't need Mac mini right now, local AI experimentation is a big part, new chip's AI performance gain is important, plan to use 3+ years long-term, prioritize latest specs over M4 discount
    OK to choose M4 now
    Need to operate agents right now, API-based automation is the focus, 1-2 messaging agents are the goal, local LLM is supplementary experimentation only, prioritize stable verified environment, cost-effectiveness matters more

    While waiting for M5, there's much you can do: understand NanoClaw structure, understand HermesClaw structure, prepare messaging accounts, organize API key management, write RUNBOOK template, document security rules, organize list of work to automate.

    Will the agents I build be API-focused or local AI-focused? What I need now — is it performance or a stable operation environment?

    07Section 17 Final Recommendation Table

    Below is a purpose-based recommendation at a glance.

    First installation test
    Consider starting with M4 base | Core criteria: cost, installation ease, Docker stability
    Personal secretary agent
    M4 base advanced configuration or M4 Pro | Core criteria: memory headroom, auto-startup, security
    Trading alert bot
    M4 base or higher | Core criteria: 24-hour operation, network, duplicate alert prevention
    Work automation agent
    M4 base advanced configuration or M4 Pro | Core criteria: logs, approval structure, file access restrictions
    Local AI experimentation
    M4 Pro or later Pro line | Core criteria: memory, storage, model execution stability
    Long-term operation server
    Configuration with memory and storage headroom | Core criteria: backup, log rotation, disaster recovery
    Waiting for M5
    Decide after official specs | Core criteria: price, Docker, local model performance

    08Section 17 Core Summary

    When choosing Mac mini for NanoClaw or HermesClaw operation, purpose comes first.

    If messaging agents and API-based automation are the focus, starting with M4 base is realistic enough. What matters is stable execution, automatic recovery, security, and log management over high performance.

    Considering local AI experimentation, memory and storage become more important. Model files, Docker images, and logs accumulate together, so it's good to build in headroom from the start.

    M5 series must be decided after checking official specs, price, Docker compatibility, and local model performance. Rather than choosing just because it's the newest chip, you should first determine how your agents will operate.

    Final criteria
    If API-focused, look at stability and cost. If local AI-focused, look at memory and storage. If 24-hour operation, look at auto-startup and recovery structure.

    With this standard, you can use Mac mini not as a simple desktop, but as a personal AI automation server running NanoClaw and HermesClaw stably.

    18. Final Recommendations

    01Lecture Overview

    This section is about compressing previous lectures covering installation, execution verification, automatic startup, security, troubleshooting, and practical cases into a single execution sequence.

    Don't try to build the perfect AI automation server from the start. Begin small and create a structure that can be stably operated.

    02Recommended Sequence for Beginners

    Rather than adding many features, the safest approach is to proceed in this order.

    1Prepare Mac mini
    2Install NanoClaw
    3Messaging Test
    4Configure Automatic Startup
    5Security Settings → Apply Real-World Cases

    03Step 1: Prepare Mac mini

    First, prepare your Mac mini to function like an AI automation server. Items to check:

    First create a state where Mac mini is stably powered on and necessary development tools are functioning properly.

    04Step 2: Install NanoClaw

    For beginners, starting with NanoClaw is a good choice. Before understanding the complex gateway structure, you can first verify the message send/receive flow.

    Create installation folder → Verify official installation command → Execute installation → Select authentication method → Connect to local CLI or test messaging channel → Send first test message

    First Day Goal (This is enough)

    05Step 3: Messaging Test

    After installation, don't connect your actual account immediately. First, verify with a test account or local CLI. Keep test messages short and simple:

    Hello. Currently testing. Answer in one sentence.

    Normal Response Criteria

    Key Point

    At this stage, what matters is not "clever responses" but stable send/receive.

    06Step 4: Automatic Startup and Security Configuration

    Automatic startup is not a convenience feature but a recovery mechanism. If the agent doesn't restart after rebooting, it's hard to use as a 24-hour server. There are usually three methods:

    Don't enable automatic startup when manual execution isn't stable.

    Enabling automatic startup in an unstable state repeats the same error, only growing logs and making root cause identification harder.

    07Security Configuration at This Stage

    Along with automatic startup, verify the following.

    08Step 5: Apply Real-World Cases

    Only after basic execution, messaging test, automatic startup, and security settings, apply real-world cases.

    Personal assistant agent → Trading helper alert bot → Work automation agent

    Don't automate all features from the start. The safest beginning is read-only or draft generation. For a personal assistant, start with daily task organization, message summaries, reply drafts, memo organization, and end-of-day summaries. For trading, start with alerts and record assists rather than automated trading. For work automation, start with classification, summarization, and drafts rather than sending or deleting.

    09Who NanoClaw Is Right For

    NanoClaw is the most realistic starting point for beginners.

    NanoClaw is enough at first. HermesClaw or complex provider routing can be added later.

    10NanoClaw Recommended Installation Order

    1. Verify Mac mini basic environment
    2. Verify Homebrew, Git, Docker installation
    3. Verify Node.js or required runtime
    4. Create NanoClaw installation folder
    5. Execute official installation command
    6. Choose local CLI or test channel
    7. Authenticate Claude / Anthropic
    8. Send first test message
    9. Check logs → Backup after installation

    The most common mistake is authentication method. Subscription login and API key method are different, and mixing them causes problems.

    11Authentication Method Record Template

    During installation, it's good to organize like this.

    ## Authentication Method Record - Usage method: Subscription login / API key - provider: Claude / Anthropic / Other - API key storage location: .env - Test completion status: YES / NO - Last normal response time:

    12NanoClaw Verification Before Real Use (1/2)

    Message Send/Receive

    API Calls

    13NanoClaw Verification Before Real Use (2/2)

    Automatic Startup

    Security · Backup

    14NanoClaw Basic Operation Prompt

    Right after installation, inject operation rules into the agent first.

    # Basic Operation Rules You are currently a personal AI agent in testing phase. ## Goals - Stably receive and respond to messages. - Don't guess unknown information. - Require user confirmation before executing privileged tasks. - Never output API keys, tokens, passwords, or personal information. ## Prohibited Actions - File deletion / external transmission / automatic payment prohibited - Arbitrary access to production accounts prohibited - Execution of unapproved commands prohibited ## Response Style - Short and clear. For errors, divide into possible causes. - Mark uncertain things as UNKNOWN.

    The purpose is not to make it smart but to prevent dangerous actions at startup.

    15Starting with HermesClaw

    HermesClaw is closer to a proxy layer than a simple app, so understanding the structure is more important.

    People Who Can Choose from the Start

    People Who Should Wait

    16Verify Hermes Agent First

    Before installing HermesClaw, Hermes Agent must work properly on its own.

    Install Hermes Agent → Verify hermes command → Run hermes doctor → Verify provider configuration → CLI test → Check gateway status

    Short requests should get normal responses in CLI.

    Currently testing Hermes Agent. Answer in one sentence.

    If this step fails, installing HermesClaw won't solve the problem.

    17OpenClaw Configuration Backup

    When migrating from OpenClaw to HermesClaw, always backup before migration. Targets: OpenClaw and gateway config files, token file list, .env, Docker Compose, port usage state, existing logs, installation folder structure.

    Don't share sensitive information directly. Record only list and hash.

    # Pre-Migration Backup Record ## Backup Targets - OpenClaw / Hermes config folder: - .env file existence: - Docker Compose file / token file existence: ## Caution - Don't record API key/token originals - Record only filenames and hash for sensitive files

    18Gateway Stability Check + Operation Prompt

    In HermesClaw, the most important is gateway stability: gateway running status, port conflicts, baseUrl, token validity, messaging auth persistence, repeated errors in logs. Port conflicts can cause messages not arriving or arriving but replies not sending.

    # HermesClaw Test Operation Rules ## Check - Hermes Agent / gateway / messaging auth status - Port conflicts · API calls · repeated errors in logs ## Prohibited - Automatic production account connection / token sharing prohibited - Arbitrary config folder deletion / arbitrary migration overwrite prohibited - External port exposure prohibited ## If Problem Occurs: symptom → cause → commands to check first → dangerous action → safe next step

    19Final Pre-Production Checklist

    Installation completion and production-ready status are different. Production-ready means:

    Message send/receive functional API calls working Automatic startup working Security settings complete Backup complete Logs viewable Failure recovery process exists
    Method

    Pass through the following 6 areas (message, API, automatic startup, security, backup, logs) one by one.

    20Checklist (1/2) — Message · API · Automatic Startup

    Message Send/Receive

    API Calls

    Automatic Startup

    21Checklist (2/2) — Security · Backup · Logs

    Security

    Backup

    Logs

    22Long-Term Operation Tips (1/2)

    Start Small

    One channel One agent One provider One role Minimize automation

    Starting small makes root cause easier to find when problems occur.

    Updates Carefully

    23Long-Term Operation Tips (2/2)

    Keep Incident Records

    Record occurrence time · symptom · recent changes · cause (confirmed/estimated) · resolution process · prevention. As incident records accumulate, automation quality improves.

    Maintain Test Environment

    Separate test/production folders, .env, messaging accounts, and ports. Verify in test first, then apply to production.

    Start Automation After Approval

    Step 1: Read-only Step 2: Summarization Step 3: Draft generation Step 4: Execute after user approval Step 5: Limited automation

    Especially for sending, deletion, payment, account change, and external integration, always start with approval before execution.

    24Final Recommendations Summary

    Most recommended flow for beginners:

    1. Prepare Mac mini basic environment
    2. Install NanoClaw
    3. Connect local CLI or test channel
    4. Short test message send/receive → Check logs
    5. Configure automatic startup → Security settings
    6. Create backup and RUNBOOK
    7. Apply personal assistant agent first
    8. Consider HermesClaw if needed
    Start small. Keep records. Execute after approval.

    25Lecture Conclusion + Practice Assignment

    More important than installation is stable operation.

    A good server is not completed by hardware alone. Operation rules, security standards, failure recovery procedures, and incident records must be together.

    Practice Assignments

    Section 18 · Conclusion

    Section 18 Key Takeaways

    Next Section

    19. Update Log

    19. Update Log

    01Why Keep an Update Log

    AI agent tools can change their installation commands, authentication methods, support channels, Docker configurations, and model provider policies at any time. Mac mini will also change its recommendation criteria when new chips and configurations appear after M4 and M4 Pro.

    Therefore, this guide should be managed as a living operational document that is continuously verified and supplemented, rather than a write-once document.

    Benefits of Keeping an Update Log

    02Keeping an Initial Write Date

    First, record the initial write date. It's good not just to note the date, but also to specify what environment the guide was written for.

    ## Initial Write Date - Date written: 2026-06-14 - Written for: Mac mini M4 / M4 Pro basis - Operating system: Based on latest macOS stable version - Main purpose: NanoClaw / HermesClaw installation and operational guide - Usage method: Messaging-based AI agent, API-based automation, Docker operation

    03Documenting the Verification Environment

    Recording which environment was used for verification increases credibility.

    ## Initial Verification Environment - Equipment: Mac mini M4 - CPU architecture: Apple Silicon - Docker: Docker Desktop for Mac - Package management: Homebrew - Core tools: Git, Node.js or Python - AI usage method: Claude / Anthropic account or API key method - Messaging test: Local CLI or test messaging account

    04Not Making Assumptions About Basis

    The important thing is not writing that "this guide works exactly the same in all environments." Instead, specify your basis clearly.

    This guide was written based on M4 Mac mini. For M5 Mac mini or later models, you must recheck official specifications and tool compatibility.
    Writing this down helps maintain the guide's credibility over time.

    05Revisit After M5 Official Announcement (1/2)

    When M5 Mac mini or later models are officially released, recheck the following items.

    Hardware Specifications

    Pricing

    06Revisit After M5 Official Announcement (2/2)

    Operational Compatibility

    Local AI Experimentation

    07Separate M5 Verified/Unverified Items

    When modifying M5-related content, it's good to separate what has actually been verified from what still needs verification rather than being definitive.

    ## M5 Verification Status ### Verified - Docker Desktop execution verified - Basic container execution verified - Messaging agent local CLI test verified ### Needs Verification - 24-hour continuous operation stability - HermesClaw gateway long-duration operation - Local LLM real-world performance - Heat generation and power consumption

    Recording this way lets readers know which sections they can trust and follow.

    08Installation Command Change History

    Commands for NanoClaw, Hermes Agent, HermesClaw, and OpenClaw can change over time. When installation commands change, don't just fix the main text—also record it in the change history.

    ## Installation Command Change History ### 2026-06-14 - Initial write - Added NanoClaw / HermesClaw installation section - Added Docker / launchd auto-start section ### 0000-00-00 - Confirmed official installation command change → Remove old command, reflect new command - Add post-installation verification command

    09What to Check When Updating Installation Commands

    When modifying installation commands, always verify the following.

    - Based on official documentation - Not based on unofficial forks - Works on macOS Apple Silicon - Does not conflict with existing installations - Does not include deletion or overwrite options

    In beginner guides, users often copy-paste commands directly, so don't include dangerous commands as-is.

    10Commands Not to Include As-Is

    Commands to watch: - rm -rf - Install scripts run with sudo - curl | bash from unclear sources - Install commands that overwrite existing settings - Commands that output tokens or API keys
    Principle

    When updating installation commands, verify in a test environment first before reflecting in the main text.

    11Security-Related Change History

    In AI agent operation, security standards must be continuously updated. Initially, it's just about hiding API keys, but as you move toward real operation, you need to care about messaging accounts, Docker permissions, external access, file access scope, and log management.

    ## Security-Related Change History ### 2026-06-14 - Added .env file management criteria - Added principle of not writing API keys directly in code - Recommended separating actual-use and test messaging accounts - Added criteria for blocking external access by default, minimizing Docker permissions ### 0000-00-00 - Add API key rotation procedure - Add log-sharing sensitive information masking procedure - Strengthen file access scope limits (no home directory full mount, no Docker socket mount)

    12One Principle for Security Updates

    When updating security standards, verify API key storage method, .env permissions, .gitignore settings, messaging account separation, external port exposure, Docker permissions, mount folder scope, and sensitive information in logs and backups.

    Even if the agent makes a mistake, the damage scope should be small.

    So with each new feature, verify "if this feature fails, what could be exposed or changed?" For example: if you added a file cleanup function to work automation, record in security logs: no auto-delete, user approval before moving, no .env/key/certificate access, and execution logging.

    13Real-World Example Addition History

    This guide covers three practical cases: personal assistant agent, trading helper alert bot, and work automation agent. When adding new cases, maintain the same format as existing ones.

    ## Real-World Example Addition History ### 2026-06-14 - Added personal assistant agent example - Added trading helper alert bot example - Added work automation agent example ### 0000-00-00 - Added document summarization dedicated agent / development helper agent examples

    14Questions When Adding a New Example

    When adding a new practical example, you must answer the following questions.

    - What is the goal of this example? - What should never be automated? - What tasks does the user need to approve? - What is the damage if it fails? - Are there logs and recovery methods? - What should beginners avoid doing?

    In practical examples, operational standards matter more than features. A good example is safe, repeatable automation, not flashy automation.

    15Wrapping Up the Entire Guide

    We've reviewed the entire flow of using NanoClaw and HermesClaw on Mac mini. The key is not completing complex AI automation all at once, but running one small messaging agent stably and then building real-world automations on top of it one by one.

    Goals in This Order

    1Receive and reply to messages
    2Run again after reboot
    3Have security and backup in place
    4Attach one of personal assistant, trading alert, or work automation to your actual routine

    16Five Principles to Remember at the End

    1. Start small. 2. Connect real accounts later. 3. Manual execution stability comes before automatic execution. 4. Never automate sending, deleting, payment, or ordering. 5. When problems occur, documenting the cause comes before reinstalling.

    What matters more than the device's name is how you operate it. What the agent can do matters less than what you keep it from doing.

    Start small and operate long-term. Keep logs, make backups, and set up a structure where you can recover from mistakes, and NanoClaw and HermesClaw on your Mac mini become a reliable personal automation system.