当前位置：首页 > news >正文

从OpenClaw到NanoClaw：极简AI Agent框架源码解析与实践指南

news 2026/8/5 4:00:42

1. 项目初探：从“OpenClaw”到“NanoClaw”的进化之路

最近在AI Agent的圈子里，OpenClaw这个名字热度不低，但随之而来的就是部署复杂、依赖繁多的抱怨。很多开发者，包括我自己，都曾被它那庞大的代码库和略显“臃肿”的架构劝退。就在大家琢磨着怎么给它“瘦身”的时候，一个名为“NanoClaw”的项目悄然出现在GitHub上，短短时间就收获了4.5K的Star。这个项目的口号非常吸引人：超极简、轻量级、8分钟理解源码。这听起来像是一个营销话术，但作为一个对Agent框架有实际部署和二次开发需求的老码农，我决定亲自下场，看看它到底是“真香”还是“噱头”。

NanoClaw，顾名思义，可以看作是OpenClaw的“纳米级”实现。它的核心目标不是复刻OpenClaw的所有功能，而是提炼其最核心的Agent思想与工作流，用最少的代码、最清晰的架构呈现出来。这就像把一本厚重的教科书，浓缩成几页核心的思维导图。对于想快速入门Agent原理、理解一个可运行的Agent系统内部如何流转的开发者来说，这无疑是一条捷径。它剥离了生产环境中那些复杂的工程化封装、各种中间件适配和性能优化层，直指Agent的“心脏”——任务规划、工具调用、记忆与反思循环。

那么，它到底适合谁呢？首先，绝对是AI应用和Agent领域的初学者。如果你被LangChain、AutoGen、OpenClaw这些大而全的框架搞得晕头转向，不知道从哪里开始看源码，NanoClaw就是为你准备的“解剖样本”。其次，它也适合需要快速验证某个Agent想法或工作流的中高级开发者。在原型设计阶段，你不需要一个重型框架，你需要的是一个能快速跑起来、逻辑清晰、方便你随意“动手术”的实验平台。NanoClaw的极简特性正好满足了这一点。最后，对于教育者和技术布道者来说，这也是一个绝佳的教学案例，可以清晰地展示Agent各个组件是如何协同工作的。

在深入代码之前，我们先明确一下NanoClaw解决的“元问题”：它试图证明，一个具备基本能力的AI Agent，其核心逻辑可以非常简洁。这挑战了“功能强大必然伴随结构复杂”的固有印象。接下来，我们就花上“8分钟”（当然，实际深入分析需要更久），一层层剥开它的源码，看看这个“纳米级”的Agent是如何被构建出来的。

2. 极简架构解析：核心模块与数据流转

NanoClaw的整个项目结构干净得令人舒适，没有深不见底的目录树。通常，它的核心源码可能就集中在几个Python文件里，比如core.py、agent.py、tools.py和workflow.py。这种设计意图非常明确：每个文件职责单一，共同勾勒出Agent的完整生命周期。我们先从宏观上把握它的架构。

2.1 核心四件套：Agent, Task, Tool, Memory

一个能自主工作的Agent，离不开这几样东西。NanoClaw用最直接的方式定义了它们：

Agent（智能体）：这是大脑。在NanoClaw中，Agent类可能非常精简，它的核心属性就是一个LLM（大语言模型）的客户端（比如调用OpenAI或Claude的API），以及一个工具列表。它的核心方法可能就是think或act，接收一个任务或观察，然后决定下一步做什么——是调用工具，还是直接给出答案。
Task（任务）：这是目标。它可能被定义为一个简单的字符串描述，或者一个稍微结构化的对象，包含任务ID、描述、状态（待处理、执行中、完成、失败）等。NanoClaw的任务系统可能不会像OpenClaw那样支持复杂的子任务分解树，而是采用更线性的方式，或者只实现一层简单的分解，以保持简洁。
Tool（工具）：这是手脚。这是Agent与外部世界交互的接口。NanoClaw中的工具定义会遵循一个简单的标准，比如每个工具都是一个Python函数，并附带上一个给LLM看的描述（名称、功能、参数schema）。当Agent决定使用工具时，就调用对应的函数。常见的工具可能包括：搜索网页、查询数据库、执行系统命令、读写文件等。
Memory（记忆）：这是经验。为了让Agent有上下文感知能力，它需要记住之前的对话和操作。NanoClaw可能实现了一种极简的记忆机制，比如一个固定长度的对话历史列表，或者一个基于向量数据库的简单检索。这部分通常是可选的，在最小化版本中，可能只是一个在会话中不断追加的列表。

2.2 工作流引擎：从输入到输出的心跳

架构是静态的，工作流是动态的。NanoClaw最精彩的部分，在于它如何将这些模块串联起来，形成一个可以自动运转的循环。这个工作流通常是这样一个循环：

[用户输入/任务] -> [Agent思考] -> [决定调用工具?] -> [是] -> [执行工具] -> [观察结果] -> [更新记忆] -> [循环思考] -> [否] -> [生成最终回答] -> [结束]

这个循环在代码中可能体现为一个while循环或一个状态机。循环的退出条件是Agent认为任务已经完成（生成了最终回答）。在每次循环中，Agent都会根据当前的任务描述、历史对话和工具列表，决定下一步行动。这个决策过程，就是LLM根据特定提示词（Prompt）进行推理的过程。

NanoClaw的巧妙之处在于，它把这个提示词模板设计得非常清晰且内聚，直接写在代码里或一个单独的配置文件中，让你一眼就能看懂Agent的“思考逻辑”。例如，提示词会明确告诉LLM：“你是一个AI助手，你可以使用以下工具：[工具列表]。当前任务是：[任务]。历史对话是：[记忆]。请分析是否需要使用工具，如果需要，请严格按照JSON格式输出工具调用请求；如果不需要，请直接输出最终答案。”

这种“思考-行动”循环，是ReAct（Reasoning and Acting）等经典Agent范式的极简实现。通过阅读这部分的代码，你可以毫无障碍地理解Agent自主性的来源。

2.3 与OpenClaw的对比：减法做在哪里？

理解了NanoClaw有什么，更要理解它没什么。相比OpenClaw，它主要做了以下减法：

去除了复杂的技能（Skill）管理系统：OpenClaw可能有复杂的技能注册、发现、组合机制。NanoClaw可能将“技能”简化为“工具”，或者只保留少数几个核心、预定义的工具。
简化了任务规划与调度：OpenClaw可能具备强大的任务分解、依赖关系处理和并行调度能力。NanoClaw可能只做简单的顺序执行或极浅层的任务分解。
裁剪了多种记忆类型：OpenClaw可能有短期记忆、长期记忆、向量记忆等多种记忆体。NanoClaw很可能只保留最基本的对话历史作为短期记忆。
省略了高级监控与评估：OpenClaw可能集成了丰富的日志、指标收集和Agent表现评估模块。NanoClaw可能只有最基础的打印日志。
简化了部署与集成：OpenClaw可能支持Docker容器化、Kubernetes部署、与飞书/钉钉等平台深度集成。NanoClaw就是一个纯粹的Python库/脚本，需要你自己写胶水代码去集成。

这些减法带来的直接好处就是代码量骤降、逻辑路径单一、学习成本极低。你不再需要面对一个由微服务、消息队列、配置中心组成的分布式系统，而是面对一个你可以从头到尾、单步调试的Python程序。这对于理解本质，至关重要。

3. 8分钟源码速览：关键代码片段精读

现在，我们进入实战环节，假设我们只有8分钟来浏览核心源码。我们应该关注哪些文件、哪些函数？我会带你像读一篇精悍的短篇小说一样，抓住它的主线剧情。

3.1 入口与配置：一切从哪里开始？

通常，一个极简项目的入口非常明显。我们首先找到一个像main.py、cli.py或example.py的文件。这里展示了如何启动一个Agent并运行一个任务。

# 假设的示例代码，风格贴近NanoClaw的极简思想 from nanoclaw.agent import Agent from nanoclaw.tools import search_web, calculator def main(): # 1. 初始化Agent，传入LLM配置（这里是模拟，实际是API Key） agent = Agent( model="gpt-4", tools=[search_web, calculator], # 工具列表 memory_size=10 # 记忆容量 ) # 2. 定义一个任务 task = "请搜索一下今天北京的天气，然后计算如果气温下降5度，会是多少度。" # 3. 运行Agent final_answer = agent.run(task) print(f"Agent最终回答: {final_answer}") if __name__ == "__main__": main()

这段代码清晰地展示了三部曲：创建Agent、定义任务、执行运行。Agent类的初始化参数点明了它的核心依赖：模型、工具和记忆。run方法就是那个核心的工作流循环入口。

3.2 Agent核心类：`think`与`act`的舞蹈

接下来，我们打开agent.py。核心一定是Agent类，而类的核心方法可能就是run、think和_call_tool。

class Agent: def __init__(self, model, tools, memory_size=5): self.model = model # LLM客户端 self.tools = {tool.name: tool for tool in tools} # 工具字典，方便按名调用 self.memory = [] # 简易记忆，存储交互历史 self.memory_size = memory_size def run(self, task): """核心运行循环""" self._add_to_memory(f"Human: {task}") max_steps = 10 # 防止无限循环 for step in range(max_steps): # 让Agent思考下一步 thought = self.think() # 解析思考结果，判断是调用工具还是最终回答 if thought.get("action") == "tool_call": tool_name = thought["tool_name"] tool_args = thought["args"] # 执行工具 observation = self._call_tool(tool_name, tool_args) self._add_to_memory(f"Tool {tool_name} returned: {observation}") elif thought.get("action") == "final_answer": answer = thought["answer"] self._add_to_memory(f"Assistant: {answer}") return answer # 循环结束，返回最终答案 else: # 处理意外情况，比如让Agent重新思考 self._add_to_memory("System: Invalid thought format. Please reconsider.") return "任务执行超时或未能完成。" def think(self): """基于当前记忆和任务，让LLM决定下一步行动""" prompt = self._build_think_prompt() # 构建提示词 response = self.model.generate(prompt) # 调用LLM # 解析LLM的响应，期望是一个结构化的JSON parsed_thought = self._parse_response(response) return parsed_thought def _call_tool(self, name, args): """查找并执行工具""" if name in self.tools: return self.tools[name].func(**args) # 执行工具函数 else: return f"Error: Tool '{name}' not found." def _add_to_memory(self, message): """管理记忆，控制长度""" self.memory.append(message) if len(self.memory) > self.memory_size * 2: # 简单裁剪策略 self.memory = self.memory[-self.memory_size:]

run方法里的for循环就是Agent的心跳。think方法是决策中枢，它构建提示词、调用LLM并解析响应。_call_tool是执行单元。整个流程线性且清晰，没有复杂的异步或回调。

3.3 提示词工程：Agent的“思维框架”

_build_think_prompt这个方法至关重要，它定义了Agent的“性格”和“思考方式”。我们看看它可能的样子：

def _build_think_prompt(self): # 工具描述部分 tools_desc = "\n".join([f"- {tool.name}: {tool.description} (参数: {tool.args_schema})" for tool in self.tools.values()]) # 记忆（对话历史）部分 memory_context = "\n".join(self.memory[-self.memory_size:]) # 取最近N条 prompt = f""" 你是一个有帮助的AI助手。你可以使用以下工具： {tools_desc} 当前的对话历史： {memory_context} 请根据以上信息，决定下一步行动。你必须二选一： A. 调用工具：如果你需要更多信息或需要执行操作来完成人类的任务。 B. 直接回答：如果你已经拥有足够的信息来给出最终、完整的答案。 如果你选择A（调用工具），请严格按以下JSON格式回复： {{ "action": "tool_call", "tool_name": "工具名", "args": {{"参数名": "参数值"}} }} 如果你选择B（直接回答），请严格按以下JSON格式回复： {{ "action": "final_answer", "answer": "你的最终回答内容" }} 只输出JSON，不要有任何其他解释。 """ return prompt

这个提示词就是一个完整的“思维框架”。它明确了角色、可用资源（工具）、上下文（记忆）、行动选项以及输出的严格格式。通过阅读这个模板，你就能完全理解这个Agent是如何被“编程”的。NanoClaw的价值之一，就是把这块通常被隐藏或分散配置的核心逻辑，赤裸裸地展示给你看。

3.4 工具定义：标准化接口

最后，看一眼tools.py，了解工具是如何被定义的。通常采用装饰器或简单的类/字典来标准化。

# 方式一：使用字典定义 def search_web(query): # 模拟搜索 return f"关于'{query}'的搜索结果：..." search_web_tool = { "name": "search_web", "description": "在互联网上搜索信息", "args_schema": {"query": {"type": "string", "description": "搜索关键词"}}, "func": search_web } # 方式二：使用类定义（更清晰） class Tool: def __init__(self, name, description, args_schema, func): self.name = name self.description = description self.args_schema = args_schema self.func = func calculator = Tool( name="calculator", description="执行数学计算", args_schema={"expression": {"type": "string", "description": "数学表达式，如 '2 + 3 * 4'"}}, func=lambda expression: str(eval(expression)) # 注意：实际使用中eval有安全风险，此处仅为示例 )

工具定义的核心是提供一个给LLM看的描述（名称、功能、参数）和一个供程序调用的函数。NanoClaw这里的实现会非常直观，让你立刻明白如何添加自己的自定义工具。

通过以上四个关键代码片段的精读，我们已经在8分钟内走马观花地看完了NanoClaw的核心骨架。它确实做到了极简，每一个部分都直指Agent技术的核心概念，没有多余的装饰。

4. 从理解到实践：部署、运行与自定义

理解了源码，下一步就是让它跑起来。NanoClaw的极简特性使得部署和运行异常简单，但也意味着你需要自己处理一些OpenClaw已经帮你搞定的事情。

4.1 环境准备与快速启动

首先，克隆项目并安装依赖。由于项目极简，依赖项通常很少，可能就是一个requirements.txt，里面包含openai（或anthropic）、requests等基础库。

git clone <NanoClaw的仓库地址> cd nanoclaw pip install -r requirements.txt

然后，你需要设置LLM的API密钥。这通常通过环境变量来完成：

# 如果你使用OpenAI export OPENAI_API_KEY='your-api-key-here' # 如果你使用Claude export ANTHROPIC_API_KEY='your-api-key-here'

最后，运行项目提供的示例脚本：

# 假设项目根目录下有一个 run_example.py python run_example.py

你应该能看到终端里打印出Agent的思考过程、工具调用和最终结果。整个过程如果顺利，几分钟内就能完成。如果遇到类似{ "error": { "code": 400, ...的错误，这通常是API密钥未设置、格式错误，或者请求的模型参数不匹配导致的。检查你的环境变量和代码中模型名称是否正确。

4.2 添加你的第一个自定义工具

这是将NanoClaw用于实际场景的关键一步。假设我们想添加一个获取当前时间的工具。

# my_tools.py import datetime def get_current_time(timezone=None): """获取当前时间。 Args: timezone (str, optional): 时区，例如 'Asia/Shanghai'。默认为系统时区。 Returns: str: 格式化后的当前时间字符串。 """ now = datetime.datetime.now() # 这里可以做时区转换，为简化示例，直接返回 return now.strftime("%Y-%m-%d %H:%M:%S") # 按照NanoClaw的方式封装工具 from nanoclaw.tools import Tool # 假设它有这个基类或方法 current_time_tool = Tool( name="get_current_time", description="获取系统的当前日期和时间。", args_schema={ "timezone": { "type": "string", "description": "可选的时区名称，如 'UTC' 或 'Asia/Shanghai'。", "required": False } }, func=get_current_time )

然后，在初始化Agent时，将这个新工具加入到工具列表中：

from nanoclaw.agent import Agent from my_tools import current_time_tool agent = Agent( model="gpt-4", tools=[current_time_tool, ...], # 加入其他已有工具 memory_size=10 ) # 现在你可以问：“现在几点了？” result = agent.run("现在几点了？") print(result)

通过这个过程，你不仅学会了如何扩展NanoClaw，更深刻地理解了工具是如何被Agent发现和调用的：描述（description）是给LLM看的“说明书”，函数（func）是实际执行的“机器”。

4.3 连接真实世界：集成外部API

一个只会计算和报时的Agent用处有限。真正的威力在于连接外部系统。让我们以调用一个公开的天气API为例。

# weather_tool.py import requests def get_weather(city): """获取指定城市的当前天气。 Args: city (str): 城市名称，例如 'Beijing'。 Returns: str: 天气信息摘要，或错误信息。 """ # 使用一个模拟的或真实的天气API，这里用open-meteo为例（免费，无需key） try: # 首先获取城市坐标（简化处理，实际应用需要更精确的地理编码） geo_url = f"https://geocoding-api.open-meteo.com/v1/search?name={city}&count=1" geo_resp = requests.get(geo_url).json() if not geo_resp.get('results'): return f"未找到城市 '{city}' 的信息。" location = geo_resp['results'][0] lat, lon = location['latitude'], location['longitude'] # 获取天气 weather_url = f"https://api.open-meteo.com/v1/forecast?latitude={lat}&longitude={lon}&current_weather=true" weather_resp = requests.get(weather_url).json() current = weather_resp.get('current_weather', {}) temp = current.get('temperature') windspeed = current.get('windspeed') weathercode = current.get('weathercode') # 可以将weathercode转换为文字描述（这里简化） return f"{city}当前天气：温度{temp}°C，风速{windspeed} km/h，天气代码{weathercode}。" except Exception as e: return f"获取天气信息时出错：{str(e)}" # 封装成工具 weather_tool = Tool( name="get_weather", description="查询指定城市的实时天气情况。", args_schema={ "city": { "type": "string", "description": "城市名称，例如 'Beijing', 'Shanghai'。", "required": True } }, func=get_weather )

将这个工具加入Agent后，它就能回答“北京天气怎么样？”这类问题了。这个过程清晰地展示了如何将任意一个HTTP API、数据库查询或系统命令封装成Agent可用的“技能”。NanoClaw的轻量级设计，使得这种集成变得非常直接和灵活。

5. 深入原理：拆解Agent的决策循环与提示词设计

运行起来之后，我们有必要再回头深入一下原理层，看看NanoClaw这个简洁的循环背后，体现了哪些Agent设计的核心思想。这对于你未来设计更复杂的Agent系统至关重要。

5.1 ReAct范式的极简实现

NanoClaw的工作流本质上是ReAct（Reasoning and Acting）范式的一个高度简化版本。ReAct强调通过推理（Reason）来生成下一步的行动计划或思考轨迹，然后行动（Act）来执行（如调用工具），再根据行动的观察（Observation）进行下一轮推理。在NanoClaw的代码中：

推理（Reason）：体现在think()方法中。LLM根据提示词（包含任务、记忆、工具描述）进行“思考”，其输出（被解析为thought字典）就是推理的结果。这个结果明确指出了下一步是“行动”还是“回答”。
行动（Act）：体现在_call_tool()方法中。根据推理结果执行具体的工具函数。
观察（Observe）：工具执行后的返回值，被作为observation添加到记忆（memory）中，成为下一轮推理的上下文。

这个循环持续进行，直到推理结果指出任务已完成（action: final_answer）。NanoClaw去掉了ReAct论文中常提到的在推理链中显式生成“Thought:”文本的部分，而是直接将推理结构化为JSON指令，这更贴近工程实现，也减少了LLM输出的不确定性。

5.2 提示词设计的艺术与陷阱

NanoClaw的提示词是其能稳定工作的关键。我们来分析一下它的设计精妙之处和可能的改进点：

精妙之处：

角色明确：“你是一个有帮助的AI助手。” 设定了基本行为准则。
上下文清晰：明确提供了“工具列表”和“对话历史”，让LLM知道自己能做什么、之前发生了什么。
选项有限且互斥：只给两个明确的选择（调用工具或最终回答），极大地降低了LLM“胡思乱想”的概率。
输出格式强制：要求“严格按以下JSON格式回复”且“只输出JSON”，这是保证程序能可靠解析的关键。通过Few-Shot示例（在提示词中给出格式样例）能进一步提高稳定性。
指令简洁：没有冗长的背景介绍，所有句子都为达成决策服务。

潜在陷阱与改进点：

工具描述的质量：工具的描述（description）和参数模式（args_schema）必须清晰、准确、无歧义。模糊的描述会导致LLM错误调用或不敢调用。例如，“处理文件”就不如“读取指定文本文件的内容并返回”来得明确。
记忆的局限性：简单的列表式记忆有长度限制，且可能包含大量无关信息。当对话轮次变多时，可能会干扰LLM的判断。改进方向可以是引入摘要记忆（定期总结历史）、或基于向量检索的相关记忆提取。
错误处理与重试：当前的循环中，如果LLM输出不符合JSON格式，或者调用工具出错，处理方式比较简单。一个健壮的Agent需要包含错误处理逻辑，比如当解析失败时，让LLM重新生成；当工具调用失败时，将错误信息反馈给LLM，让它尝试其他方案。
复杂任务规划：当前提示词只支持单步决策。对于“写一份报告并发送邮件”这样的多步骤复杂任务，LLM可能无法在一步内规划完整。这就需要引入更高级的任务分解（Task Decomposition）机制，这通常是OpenClaw等框架的重点，但超出了NanoClaw的极简范畴。你可以在NanoClaw的基础上，让LLM先输出一个任务列表，然后再循环执行每个子任务。

理解这些，你就掌握了设计一个可用Agent的“配方”。你可以基于NanoClaw的骨架，针对自己的应用场景，去优化提示词、增强记忆、完善错误处理，从而构建出更强大、更稳定的智能体。

6. 性能调优与扩展思路

虽然NanoClaw定位是极简和教学，但当我们想把它用于一些轻度实际场景时，还是需要考虑其性能和扩展性。这里分享一些基于其架构的优化思路。

6.1 减少LLM调用次数与成本

每次循环都要调用一次LLM，这是主要的耗时和成本来源。优化方法包括：

批量工具调用：修改提示词，允许LLM在一次思考中规划多个连续的工具调用（如果它们之间没有依赖关系）。例如，让LLM输出一个工具调用列表，然后顺序执行。这需要更复杂的输出解析，但能显著减少交互轮次。
更精准的记忆检索：不要总是把全部历史记忆塞进提示词。可以实现一个简单的基于最近性和相关性的记忆筛选。例如，只保留最近3轮对话和与当前任务关键词相关的历史记录。这能缩短提示词长度，降低Token消耗，有时还能提升效果。
设置超时与最大步数：就像代码中已有的max_steps，这是必须的。防止Agent陷入死循环或因为某个工具失败而卡住。达到上限后，可以总结已获得的信息，尝试给出一个部分答案或明确失败。

6.2 增强可靠性与稳定性

输出格式校验与重试：在_parse_response函数中，加入对JSON格式的严格校验。如果解析失败，不要直接崩溃或使用默认值，而是将错误信息（如“你返回的内容不是有效的JSON”）连同原始问题，再次发送给LLM，要求它重试。通常设置1-2次重试就能解决大部分格式问题。
工具调用异常处理：在_call_tool函数中，用try...except包裹工具执行过程。捕获异常后，将友好的错误信息（如“调用搜索工具时网络超时”）作为观察返回给Agent，让它决定是重试、换一种方式还是向用户求助。
引入验证步骤：对于关键操作（如发送邮件、修改数据），可以在最终执行前，增加一个“验证”环节。让LLM总结它将要执行的操作，并请求用户确认（“我将执行A、B、C，确认吗？”）。这能大大提高系统的安全性。

6.3 架构扩展方向

当你需要更复杂的多Agent协作或持久化时，可以在NanoClaw的基础上进行扩展：

多Agent协作：创建多个NanoClaw Agent实例，每个具备不同的专业工具集。设计一个“协调者”Agent或一套简单的规则（如基于任务类型路由），将任务分配给最专业的Agent去执行，并管理它们之间的通信。这其实就是微型的Agent网络。
状态持久化：将记忆（self.memory）保存到数据库或文件中。每次启动Agent时加载历史，实现跨会话的记忆。这可以让Agent在更长的周期内为用户提供连贯的服务。
集成向量数据库：对于需要基于大量文档知识进行回答的场景，可以将文档切片、向量化后存入向量数据库（如Chroma、Milvus）。然后增加一个“检索”工具，该工具接收用户问题，去向量库中查找最相关的片段，并将这些片段作为上下文提供给LLM。这就升级成了一个简单的检索增强生成（RAG）Agent。

NanoClaw就像一个乐高积木的基础颗粒。它本身功能简单，但结构清晰、接口明确，非常适合作为你构建更复杂AI应用的原型或核心组件。通过上述的优化和扩展，你可以让它从一个小玩具，逐渐成长为一个能解决实际问题的工具。

7. 常见问题排查与实战心得

在实际把玩NanoClaw的过程中，你肯定会遇到各种各样的问题。这里我总结了一些常见的坑和解决思路，以及一些从实战中得来的心得。

7.1 典型错误与解决方案

错误：{ "error": { "code": 400, "message": "...
- 可能原因：这是最常见的API调用错误。400错误通常意味着请求格式有问题。
- 排查步骤：
  - 检查API密钥：确保环境变量设置正确，且密钥有效、有余额。
  - 检查模型名称：代码中指定的模型（如"gpt-4"）是否在你的API账户中可用。有时需要用"gpt-4-turbo-preview"这样的具体名称。
  - 检查请求参数：特别是max_tokens、temperature等参数是否在合理范围内。NanoClaw的默认参数可能不适合所有模型。
  - 查看完整错误信息：错误信息的message字段通常会给出更具体的提示，如“该模型不存在”或“输入token超长”。
错误：JSONDecodeError或无法解析LLM输出
- 可能原因：LLM没有严格按照你要求的JSON格式输出，可能夹杂了其他解释性文字。
- 解决方案：
  - 强化提示词：在提示词中更加强调“只输出JSON，不要有任何其他文字”。可以使用三重引号包裹JSON示例，使其更醒目。
  - 使用LLM的JSON模式：如果使用的LLM API支持（如OpenAI的response_format={ "type": "json_object" }），强烈建议开启。这会强制模型输出合法JSON。
  - 实现解析容错：在解析代码中，尝试用正则表达式从返回文本中提取第一个完整的JSON对象，而不是直接对整个响应进行json.loads()。
问题：Agent陷入循环，不断调用同一个工具
- 可能原因：工具返回的结果没有给Agent提供新的、有价值的信息，或者任务本身模糊，导致Agent无法判断何时结束。
- 解决方案：
  - 优化工具反馈：确保工具返回的信息是明确、结构化、易于理解的。避免返回“成功”或“无结果”这样模糊的信息，而是返回“未找到匹配XXX的数据”或“操作已完成，影响了Y条记录”。
  - 在提示词中明确终止条件：在给LLM的指令中加入更具体的任务完成标准。例如，“当你获得了天气温度和风速信息后，就可以组合成最终答案了。”
  - 引入反思步骤：在每次工具调用后，让LLM简短评估一下当前进度是否足以完成任务。这可以通过在提示词中增加一个问题来实现，比如“基于当前获得的所有信息，你是否已经可以给出最终答案？如果是，请输出最终答案；如果否，请说明还需要什么信息或操作。”

7.2 实战心得与技巧

从小任务开始：不要一开始就让Agent处理“帮我写一个完整的项目计划”这种宏大任务。从“查一下天气”、“计算一下折扣价”这种有明确输入输出、步骤少的任务开始。验证基本流程跑通后，再逐步增加复杂度。
工具设计要“傻瓜式”：给LLM用的工具，其描述和参数要尽可能的“傻瓜化”。LLM不像程序员，它不理解复杂的编程概念。参数名最好用自然语言词汇，描述要像说明书一样一步一步写清楚这个工具是干什么的、输入什么、输出什么。好的工具设计能极大降低提示词工程的难度。
温度（Temperature）参数很重要：在调用LLM时，temperature参数控制输出的随机性。对于Agent的决策环节，通常建议设置为0或一个很低的值（如0.1），以保证其行为是确定和可靠的。如果设置过高，Agent可能会做出一些意想不到的、不稳定的决策。
日志是你的好朋友：在run循环中，详细打印出每一步的thought和observation。这不仅能帮你调试，更是理解Agent“思考过程”的绝佳窗口。你会看到LLM是如何理解任务、选择工具、解析结果的，这个过程本身非常有启发性。
NanoClaw是“起点”，不是“终点”：它的价值在于让你用最小的代价理解了Agent的核心运行机制。当你需要更复杂的特性（如并行任务、流式输出、复杂记忆、可视化监控）时，就应该考虑转向更成熟的框架，如LangChain、AutoGen，甚至是回过头去研究OpenClaw。但那时，你将带着从NanoClaw获得的理解去学习，事半功倍。

通过NanoClaw这个精巧的“显微镜”，我们得以窥见AI Agent内部最本质的齿轮是如何咬合转动的。它剥离了所有冗余，将Agent技术浓缩为一个可运行、可修改、可理解的代码样本。无论你是想快速入门，还是需要一个轻量级的实验平台，它都提供了一个近乎完美的起点。理解它，改造它，最终超越它，这或许就是开源项目带给我们的最大乐趣。

查看全文

http://www.jsqmd.com/news/1330708/