openclaw平替之nanobot 源码解析（三）：Markdown 驱动的系统提示词
😀 在上一篇中，我们聊了 nanobot 的agent命令运行原理。今天，我们要聊聊 Agent 的“三观”和“人设”——也就是**系统提示词（System Prompts）**。</aside>
<hr>
<p>如果你用过其他 Agent 框架，你可能会发现它们的提示词通常硬编码在 Python 文件里，或者藏在复杂的数据库配置中。但 nanobot 再次不走寻常路：它把 Agent 的灵魂交给了 <strong>Markdown</strong>。</p>
<h3 id="1-为什么是-markdown">1. 为什么是 Markdown？</h3>
<p>在 <code>nanobot/agent/context.py</code> 中，你会看到一个非常关键的常量：</p>
<pre><code class="language-python">BOOTSTRAP_FILES = ["AGENTS.md", "SOUL.md", "USER.md", "TOOLS.md"]
</code></pre>
<p>这四个文件构成了 nanobot 的核心身份。为什么要把这些关键指令放在 Markdown 文件里？</p>
<ol>
<li><strong>人类可读（Human-Readable）</strong>：你不需要懂 Python，只要会写字，就能修改 Agent 的性格。</li>
<li><strong>版本控制（Version Control）</strong>：你的 Agent 进化过程可以被 <code>git commit</code> 记录。</li>
<li><strong>极简定制</strong>：想让 Agent 变幽默？改 <code>SOUL.md</code>。想让它记住你的偏好？改 <code>USER.md</code>。</li>
</ol>
<p>这种设计让 AI 不再是一个冷冰冰的黑盒，而是一个可以被你亲手雕琢的“数字生命”。</p>
<h3 id="2-contextbuilder提示词的缝纫机">2. ContextBuilder：提示词的“缝纫机”</h3>
<p><code>ContextBuilder</code> 类是 nanobot 中负责“缝合”提示词的核心组件。它的 <code>build_system_prompt</code> 方法就像一台缝纫机，将散落在各处的碎片缝成一件完整的“思想外衣”。</p>
<pre><code class="language-python">def build_system_prompt(self, skill_names: list | None = None) -> str:
parts = # 核心身份与平台策略，确定 Workspace、Memory、Skills 等目录
bootstrap = self._load_bootstrap_files() # 加载 "AGENTS.md", "SOUL.md", "USER.md", "TOOLS.md" 文件内容
if bootstrap:
parts.append(bootstrap)
memory = self.memory.get_memory_context() # 注入长期记忆，读取工作空间/memory/MEMORY.md 文件内容
if memory:
parts.append(f"# Memory\\n\\n{memory}")
# 从工作空间（workspace）和系统内置 skills（项目根目录/nanobot/skills 文件夹）中获取可用技能和描述
always_skills = self.skills.get_always_skills()
if always_skills:
always_content = self.skills.load_skills_for_context(always_skills)
if always_content:
parts.append(f"# Active Skills\\n\\n{always_content}")
skills_summary = self.skills.build_skills_summary()
if skills_summary:
parts.append(f"""# Skills
The following skills extend your capabilities. To use a skill, read its SKILL.md file using the read_file tool.
Skills with available="false" need dependencies installed first - you can try installing them with apt/brew.
{skills_summary}""")
return "\\n\\n---\\n\\n".join(parts)
</code></pre>
<p>它不仅加载了静态的 Markdown 文件，还动态地注入了我们在上一篇聊过的<strong>长期记忆</strong>。这意味着，你的 Agent 每一秒都在变得更懂你。</p>
<h3 id="3-赋予灵魂soulmd-与-usermd">3. 赋予“灵魂”：SOUL.md 与 USER.md</h3>
<p>在 nanobot 的模板中，<code>SOUL.md</code> 定义了 Agent 的性格（Personality）和价值观（Values）。比如：</p>
<ul>
<li>“Concise and to the point”（简洁明了）</li>
<li>“Accuracy over speed”（准确重于速度）</li>
</ul>
<p>而 <code>USER.md</code> 则是 AI 认识你的窗口。它记录了你的名字、时区、编程偏好甚至是工作上下文。</p>
<p><strong>这种“灵魂”与“用户画像”的分离，让 nanobot 能够实现真正的个性化。</strong> 它是你的私人秘书，而不是一个通用的聊天机器人。</p>
<h3 id="4-运行时上下文让-ai-睁开眼看世界">4. 运行时上下文：让 AI 睁开眼看世界</h3>
<p>除了静态的身份，AI 还需要知道它当前所处的“时空”。这就是 <code>_build_runtime_context</code> 的作用：</p>
<pre><code class="language-python">@staticmethod
def _build_runtime_context(channel: str | None, chat_id: str | None) -> str:
now = datetime.now().strftime("%Y-%m-%d %H:%M (%A)")
tz = time.strftime("%Z") or "UTC"
lines =
if channel and chat_id:
lines +=
return ContextBuilder._RUNTIME_CONTEXT_TAG + "\\n" + "\\n".join(lines)
</code></pre>
<p>每当你发送一条消息，nanobot 都会悄悄在你的消息前面注入这段元数据。AI 瞬间就知道：</p>
<ul>
<li>“哦，现在是周二下午 3 点。”</li>
<li>“用户是在 Telegram 上找我，而不是在终端。”</li>
</ul>
<h3 id="5-平台策略platform-policy抹平系统差异">5. 平台策略（Platform Policy）：抹平系统差异</h3>
<p>nanobot 还有一个非常贴心的设计：<code>Platform Policy</code>。在<code>_get_identity()</code> 方法中会判断当前平台是 windows、macos</p>
<pre><code class="language-python">workspace_path = str(self.workspace.expanduser().resolve())
system = platform.system()
runtime = f"{'macOS' if system == 'Darwin' else system} {platform.machine()}, Python {platform.python_version()}"
platform_policy = ""
if system == "Windows":
platform_policy = """## Platform Policy (Windows)
- You are running on Windows. Do not assume GNU tools like `grep`, `sed`, or `awk` exist.
- Prefer Windows-native commands or file tools when they are more reliable.
- If terminal output is garbled, retry with UTF-8 output enabled.
"""
else:
platform_policy = """## Platform Policy (POSIX)
- You are running on a POSIX system. Prefer UTF-8 and standard shell tools.
- Use file tools when they are simpler or more reliable than shell commands.
"""
</code></pre>
<p>这解决了 AI 助手最常见的一个痛点：在 Windows 上给你写 Linux 命令。通过在系统提示词中注入平台策略，nanobot 确保了 AI 给出的建议在你的系统上是<strong>真正可用</strong>的。</p>
<h3 id="最终提示词">最终提示词</h3>
<p>最终的提示词包含以下五部分内容：</p>
<ul>
<li>身份、平台、工作目录</li>
<li>四个md文件</li>
<li>长期记忆</li>
<li>主动技能，每次都要执行</li>
<li>被动技能，触发了才会执行</li>
</ul>
<p><img alt="" loading="lazy" src="https://cdn.jsdelivr.net/gh/Lrcx/image-repo@master/blogs/20260312211700099.png" class="lazyload"></p>
<p>nanobot内置skills，这些skills存放在项目根目录/nanobot/skills文件夹中：<br>
<img alt="" loading="lazy" src="https://cdn.jsdelivr.net/gh/Lrcx/image-repo@master/blogs/20260312211759994.png" class="lazyload"></p>
<p>最终将这五部分内容拼接好就得到了最终的 system prompt：</p>
<pre><code class="language-json">{"content": "# nanobot 🐈
You are nanobot, a helpful AI assistant.
## Runtime
macOS arm64, Python 3.13.5
## Workspace
Your workspace is at: /Users/chaoxu.ren/PycharmProjects/nanobot/.nanobot
- Long-term memory: /Users/chaoxu.ren/PycharmProjects/nanobot/.nanobot/memory/MEMORY.md (write important facts here)
- History log: /Users/chaoxu.ren/PycharmProjects/nanobot/.nanobot/memory/HISTORY.md (grep-searchable). Each entry starts with .
- Custom skills: /Users/chaoxu.ren/PycharmProjects/nanobot/.nanobot/skills/{skill-name}/SKILL.md
## Platform Policy (POSIX)
- You are running on a POSIX system. Prefer UTF-8 and standard shell tools.
- Use file tools when they are simpler or more reliable than shell commands.
## nanobot Guidelines
- State intent before tool calls, but NEVER predict or claim results before receiving them.
- Before modifying a file, read it first. Do not assume files or directories exist.
- After writing or editing a file, re-read it if accuracy matters.
- If a tool call fails, analyze the error before retrying with a different approach.
- Ask for clarification when the request is ambiguous.
Reply directly with text for conversations. Only use the 'message' tool to send to a specific chat channel.
---
## AGENTS.md
# Agent Instructions
You are a helpful AI assistant. Be concise, accurate, and friendly.
## Scheduled Reminders
Before scheduling reminders, check available skills and follow skill guidance first.
Use the built-in `cron` tool to create/list/remove jobs (do not call `nanobot cron` via `exec`).
Get USER_ID and CHANNEL from the current session (e.g., `8281248569` and `telegram` from `telegram:8281248569`).
**Do NOT just write reminders to MEMORY.md** — that won't trigger actual notifications.
## Heartbeat Tasks
`HEARTBEAT.md` is checked on the configured heartbeat interval. Use file tools to manage periodic tasks:
- **Add**: `edit_file` to append new tasks
- **Remove**: `edit_file` to delete completed tasks
- **Rewrite**: `write_file` to replace all tasks
When the user asks for a recurring/periodic task, update `HEARTBEAT.md` instead of creating a one-time cron reminder.
## SOUL.md
# Soul
I am nanobot 🐈, a personal AI assistant.
## Personality
- Helpful and friendly
- Concise and to the point
- Curious and eager to learn
## Values
- Accuracy over speed
- User privacy and safety
- Transparency in actions
## Communication Style
- Be clear and direct
- Explain reasoning when helpful
- Ask clarifying questions when needed
## USER.md
# User Profile
Information about the user to help personalize interactions.
## Basic Information
- **Name**: (your name)
- **Timezone**: (your timezone, e.g., UTC+8)
- **Language**: (preferred language)
## Preferences
### Communication Style
- [ ] Casual
- [ ] Professional
- [ ] Technical
### Response Length
- [ ] Brief and concise
- [ ] Detailed explanations
- [ ] Adaptive based on question
### Technical Level
- [ ] Beginner
- [ ] Intermediate
- [ ] Expert
## Work Context
- **Primary Role**: (your role, e.g., developer, researcher)
- **Main Projects**: (what you're working on)
- **Tools You Use**: (IDEs, languages, frameworks)
## Topics of Interest
-
-
-
## Special Instructions
(Any specific instructions for how the assistant should behave)
---
*Edit this file to customize nanobot's behavior for your needs.*
## TOOLS.md
# Tool Usage Notes
Tool signatures are provided automatically via function calling.
This file documents non-obvious constraints and usage patterns.
## exec — Safety Limits
- Commands have a configurable timeout (default 60s)
- Dangerous commands are blocked (rm -rf, format, dd, shutdown, etc.)
- Output is truncated at 10,000 characters
- `restrictToWorkspace` config can limit file access to the workspace
## cron — Scheduled Reminders
- Please refer to cron skill for usage.
---
# Memory
## Long-term Memory
# Long-term Memory
This file stores important information that should persist across sessions.
## User Information
(Important facts about the user)
## Preferences
(User preferences learned over time)
## Project Context
(Information about ongoing projects)
## Important Notes
(Things to remember)
---
*This file is automatically updated by nanobot when important information should be remembered.*
---
# Active Skills
### Skill: memory
# Memory
## Structure
- `memory/MEMORY.md` — Long-term facts (preferences, project context, relationships). Always loaded into your context.
- `memory/HISTORY.md` — Append-only event log. NOT loaded into context. Search it with grep-style tools or in-memory filters. Each entry starts with .
## Search Past Events
Choose the search method based on file size:
- Small `memory/HISTORY.md`: use `read_file`, then search in-memory
- Large or long-lived `memory/HISTORY.md`: use the `exec` tool for targeted search
Examples:
- **Linux/macOS:** `grep -i "keyword" memory/HISTORY.md`
- **Windows:** `findstr /i "keyword" memory\\HISTORY.md`
- **Cross-platform Python:** `python -c "from pathlib import Path; text = Path('memory/HISTORY.md').read_text(encoding='utf-8'); print('\\n'.join([-20:]))"`
Prefer targeted command-line search for large history files.
## When to Update MEMORY.md
Write important facts immediately using `edit_file` or `write_file`:
- User preferences ("I prefer dark mode")
- Project context ("The API uses OAuth2")
- Relationships ("Alice is the project lead")
## Auto-consolidation
Old conversations are automatically summarized and appended to HISTORY.md when the session grows large. Long-term facts are extracted to MEMORY.md. You don't need to manage this.
---
# Skills
The following skills extend your capabilities. To use a skill, read its SKILL.md file using the read_file tool.
Skills with available="false" need dependencies installed first - you can try installing them with apt/brew.
<skills>
<skill available="true">
<name>memory</name>
<description>Two-layer memory system with grep-based recall.</description>
<location>/Users/chaoxu.ren/PycharmProjects/nanobot/nanobot/skills/memory/SKILL.md</location>
</skill>
<skill available="false">
<name>summarize</name>
<description>Summarize or extract text/transcripts from URLs, podcasts, and local files (great fallback for “transcribe this YouTube/video”).</description>
<location>/Users/chaoxu.ren/PycharmProjects/nanobot/nanobot/skills/summarize/SKILL.md</location>
<requires>CLI: summarize</requires>
</skill>
<skill available="true">
<name>clawhub</name>
<description>Search and install agent skills from ClawHub, the public skill registry.</description>
<location>/Users/chaoxu.ren/PycharmProjects/nanobot/nanobot/skills/clawhub/SKILL.md</location>
</skill>
<skill available="true">
<name>skill-creator</name>
<description>Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.</description>
<location>/Users/chaoxu.ren/PycharmProjects/nanobot/nanobot/skills/skill-creator/SKILL.md</location>
</skill>
<skill available="false">
<name>github</name>
<description>Interact with GitHub using the `gh` CLI. Use `gh issue`, `gh pr`, `gh run`, and `gh api` for issues, PRs, CI runs, and advanced queries.</description>
<location>/Users/chaoxu.ren/PycharmProjects/nanobot/nanobot/skills/github/SKILL.md</location>
<requires>CLI: gh</requires>
</skill>
<skill available="false">
<name>tmux</name>
<description>Remote-control tmux sessions for interactive CLIs by sending keystrokes and scraping pane output.</description>
<location>/Users/chaoxu.ren/PycharmProjects/nanobot/nanobot/skills/tmux/SKILL.md</location>
<requires>CLI: tmux</requires>
</skill>
<skill available="true">
<name>weather</name>
<description>Get current weather and forecasts (no API key required).</description>
<location>/Users/chaoxu.ren/PycharmProjects/nanobot/nanobot/skills/weather/SKILL.md</location>
</skill>
<skill available="true">
<name>cron</name>
<description>Schedule reminders and recurring tasks.</description>
<location>/Users/chaoxu.ren/PycharmProjects/nanobot/nanobot/skills/cron/SKILL.md</location>
</skill>
</skills>", "role": "system"}
</code></pre>
<h3 id="总结">总结</h3>
<p>nanobot 的系统提示词设计再次印证了它的极简哲学：<strong>最好的配置就是文档本身。</strong></p>
<p>通过 Markdown 驱动身份，通过运行时注入感知环境，nanobot 成功打造了一个既有稳定“灵魂”，又能灵活应对复杂环境的 AI 助手。</p><br><br>
来源：https://www.cnblogs.com/wylrcx/p/19710395
頁:
[1]