★ FEATURED ARTICLE 1. nanobot 的 4000 行代码为什么值得每个 Agent 开发者读一遍nanobot 是一个用约 4000 行 Python 实现的轻量级 AI Agent 框架核心能力包括 ReAct 循环、工具注册、记忆存储和多通道接入。它适合个人开发者、想理解 Agent 底层原理的学习者以及需要快速搭建私人助手的场景。我第一次翻它的源码时最直观的感受是整个项目没有一处“为了架构而架构”的设计每个文件都能在五分钟内读完并理解它在做什么。这种体感在当下的 Agent 框架生态里非常稀缺。LangChain 的抽象层叠了又叠CrewAI 把多 Agent 协作做成了独立范式OpenClaw 功能全但代码量到了 43 万行级别。nanobot 反过来走了一条 Unix 哲学的路做一件事并把它做好。接入层只管消息收发核心引擎只管“思考-行动-观察”循环能力层提供可插拔的工具和记忆存储。三层之间通过明确的接口通信改一层不会牵连另一层。它的记忆系统用 Markdown 文件做持久化MEMORY.md 存长期记忆memory/YYYY-MM-DD.md 记每日笔记skills/ 目录放技能文档。人类可读、可直接编辑、能用 Git 管版本、零外部依赖。工具注册用一个tool装饰器搞定不需要继承基类不需要写注册配置文件。这种“约定优于配置”的思路把二次开发门槛压到了极低。但轻量框架有一个绕不开的现实问题LLM 接入。nanobot 本身不绑定任何模型供应商你需要自己配 Base URL、API Key 和 Model ID。如果每个项目都去单独申请 Key、单独配环境变量、单独处理不同供应商的接口差异轻量框架的“轻”就被抵消了。我试过在三个不同项目里分别维护三套 Key 和 Base URL切换模型时改配置改到烦。后来统一走 TaoToken 的 API 通道一个 Key 覆盖多家模型Base URL 固定不变nanobot 的 auth.json 只写一份配置就能跑通。下面从环境准备开始把整条链路拆开讲。2. TaoToken 统一 Key 通道的前置准备与 auth.json 配置TaoToken 是一个统一 API 网关对外暴露兼容 OpenAI 规范的接口。你只需要一个 API Key 和一个固定的 Base URL就能在 nanobot 里调用不同供应商的模型不用为每个模型单独改代码或维护多套凭证。对 nanobot 这种轻量框架来说这意味着 auth.json 里只写一份配置切换模型只改 Model ID 一个字段。先拿到 Key。打开 https://taotoken.net/api-keys 登录后在控制台创建 API Key。建议按项目命名比如nanobot-dev方便后续排查是哪个项目在调用。创建后立即复制保存页面刷新后不再完整显示。Base URL 固定为https://taotoken.net/api注意末尾不要加/v1TaoToken 的网关会自动路由。如果你在代码里用的是 OpenAI SDKSDK 内部会拼/v1/chat/completions所以 Base URL 写到/api即可。nanobot 的凭证配置放在项目根目录的auth.json里。如果你是从 GitHub 克隆的源码先复制模板cd nanobot cp auth.example.json auth.json然后用编辑器打开auth.json填入以下内容{ base_url: https://taotoken.net/api, api_key: sk-你的TaoToken密钥, model: claude-sonnet-4-20250514, max_tokens: 4096, temperature: 0.7 }字段说明用表格对照更清楚字段必填说明base_url是固定填https://taotoken.net/api不要加/v1api_key是从 TaoToken 控制台创建的 Key以sk-开头model是Model ID如claude-sonnet-4-20250514、gpt-4o等max_tokens否单次回复最大 token 数默认 4096temperature否采样温度0 到 1 之间默认 0.7如果你用环境变量管理凭证nanobot 也支持从TAOTOKEN_API_KEY读取。在.env文件里写TAOTOKEN_API_KEYsk-你的TaoToken密钥 TAOTOKEN_BASE_URLhttps://taotoken.net/api然后在auth.json里把api_key留空或写env:TAOTOKEN_API_KEY框架启动时会自动替换。这样做的好处是 auth.json 可以提交到 GitKey 不会泄露。注意auth.json 里如果同时写了明文 Key 和环境变量引用明文优先级更高。建议只保留一种方式避免排查时分不清用的是哪个。配置完成后先别急着跑 Agent。用一条 curl 命令验证 Key 和 Base URL 是否通curl -s https://taotoken.net/api/v1/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer sk-你的TaoToken密钥 \ -d { model: claude-sonnet-4-20250514, messages: [{role: user, content: 回复 OK 两个字母}], max_tokens: 16 }如果返回 JSON 里choices[0].message.content包含OK说明 Key 和 Base URL 都正确。如果返回 401检查 Key 是否复制完整、是否有多余空格。如果返回 404检查 Base URL 是否误加了/v1或末尾斜杠。这一步看起来简单但它是后面所有 Agent 调用的基础。我踩过的坑是auth.json 里 Base URL 写成了https://taotoken.net/api/v1结果 nanobot 内部再拼一次/v1/chat/completions变成/api/v1/v1/chat/completions直接 404。改回/api就好了。3. 可复制的 nanobot Agent 工具调用配置与完整验证流程nanobot 的工具调用链路是用户消息进入 AgentLoopContextBuilder 组装上下文LLM 返回工具调用意图ToolRegistry 查找并执行对应工具结果回传给 LLM 生成最终回复。整条链路里LLM 接入点只有一个就是 auth.json 里的 Base URL 和 Model ID。所以只要这一层通了工具调用就能跑。先定义一个最简单的工具。在tools/目录下新建weather.pyfrom nanobot.tools import tool tool(description获取指定城市的天气信息) def get_weather(city: str) - str: 根据城市名返回天气描述。实际项目中替换为真实 API 调用。 weather_data { 北京: 晴气温 22°C湿度 40%, 上海: 多云气温 25°C湿度 65%, 深圳: 阵雨气温 28°C湿度 80%, } return weather_data.get(city, f{city} 的天气数据暂不可用)这个装饰器会把函数注册到 ToolRegistryLLM 在需要时会自动调用。你不需要写任何注册代码也不需要继承基类。接下来写一个最小启动脚本run_agent.pyimport asyncio from nanobot import Agent from nanobot.config import load_auth async def main(): auth load_auth(auth.json) agent Agent( base_urlauth[base_url], api_keyauth[api_key], modelauth[model], tools_dirtools, memory_dirmemory, ) response await agent.chat(北京今天天气怎么样) print(response) if __name__ __main__: asyncio.run(main())运行python run_agent.py预期输出类似北京今天天气是晴气温 22°C湿度 40%。如果你在日志里看到Tool call: get_weather(city北京)说明工具调用链路完整走通了。LLM 先返回了工具调用意图ToolRegistry 执行了get_weather结果回传后 LLM 生成了自然语言回复。再验证一次多轮工具调用。把问题改成“北京和深圳的天气分别怎么样”LLM 应该连续调用两次get_weather一次传北京一次传深圳。日志里会看到两条 Tool call 记录。这说明 nanobot 的 AgentLoop 支持在同一轮对话里多次工具调用不需要你手动编排。如果你用的是 Claude Code 或 Cline 这类编辑器插件配置方式略有不同。以 Cline 的 MCP 配置为例在cline_mcp_settings.json里写{ mcpServers: { nanobot-tools: { command: python, args: [-m, nanobot.mcp_server], env: { TAOTOKEN_API_KEY: sk-你的TaoToken密钥, TAOTOKEN_BASE_URL: https://taotoken.net/api, TAOTOKEN_MODEL: claude-sonnet-4-20250514 } } } }这里三件套必须写全Base URL 填https://taotoken.net/apiKey 填 TaoToken 的 KeyModel ID 填你要用的模型。缺任何一个都会导致 MCP Server 启动后调用失败。提示nanobot 的 MCP Server 模式需要额外安装mcp依赖运行pip install mcp即可。如果你不需要在编辑器里调用 nanobot 工具可以跳过这一段。验证成功后你可以把tools/目录下的工具逐步替换成真实业务逻辑。比如把get_weather换成调用真实天气 API或者新增send_email、query_database等工具。只要保持tool装饰器和函数签名不变LLM 就能自动发现并调用它们。4. nanobot 工具调用中 reading choices 报错与 local proxy failed 排查工具调用跑通之后实际使用中会遇到几类高频报错。我按出现频率从高到低排列每个都给出定位方法和修复步骤。报错一KeyError: choices或reading choices完整报错通常长这样KeyError: choices 或者 TypeError: NoneType object is not subscriptable File nanobot/llm/client.py, line 87, in chat content response[choices][0][message][content]这个报错的根因是 LLM 返回的 JSON 里没有choices字段。常见原因有三个第一Base URL 写错了。如果你把 Base URL 写成https://taotoken.net/api/v1请求会打到/api/v1/v1/chat/completions网关返回 404 的 HTML 页面解析 JSON 时自然找不到choices。修复方法把 auth.json 里的base_url改回https://taotoken.net/api。第二API Key 无效或过期。TaoToken 返回 401 时响应体是{error: {message: Invalid API key}}没有choices字段。修复方法去 https://taotoken.net/api-keys 重新创建一个 Key替换 auth.json 里的值。第三Model ID 拼写错误。比如把claude-sonnet-4-20250514写成claude-sonnet-4网关找不到对应模型返回错误信息。修复方法在 TaoToken 控制台的模型列表里复制准确的 Model ID。排查时可以在 nanobot 的 LLM client 里加一行调试日志import json print(json.dumps(response, ensure_asciiFalse, indent2))把完整响应打出来一眼就能看出是 401、404 还是模型不存在。报错二local proxy failed或连接超时完整报错httpx.ConnectError: [Errno 111] Connection refused 或者 local proxy failed: connect timeout这个报错说明请求根本没发出去或者发到了错误的地址。检查顺序先确认base_url是不是https://taotoken.net/api不要有多余的路径或端口。然后确认本机网络能访问外网用curl -I https://taotoken.net/api看是否返回 200 或 401。如果 curl 也超时说明是网络层问题不是 nanobot 配置问题。还有一种情况是环境变量里残留了旧的代理设置。检查HTTP_PROXY和HTTPS_PROXY是否被设置成了无效地址echo $HTTP_PROXY echo $HTTPS_PROXY如果有值且不是你预期的用unset HTTP_PROXY HTTPS_PROXY清掉再跑。报错三OAuth token expired或invalid_grant这个报错通常出现在你用 Claude Code 或 Cline 的 OAuth 登录方式接入时。TaoToken 走的是 API Key 认证不需要 OAuth。如果你在编辑器插件里同时配了 OAuth 和 API Key插件可能优先用了过期的 OAuth token。修复方法在插件设置里把认证方式切换为 API Key填入 TaoToken 的 KeyBase URL 填https://taotoken.net/api。如果你用的是 Claude Code 的auth.json确保文件里只有api_key字段没有oauth_token或refresh_token。报错四工具调用返回Tool not found完整报错ToolNotFoundError: get_weather is not registered这说明 LLM 返回了工具调用意图但 ToolRegistry 里找不到对应工具。检查三件事tools/目录下是否有weather.py函数是否加了tool装饰器Agent初始化时tools_dir参数是否指向了正确的目录。如果工具文件在子目录里比如tools/weather/current.py需要确保tools/__init__.py里做了导入或者tools_dir指向了包含所有工具文件的根目录。报错五max_tokens超限完整报错Error code: 400 - max_tokens exceeds model limit不同模型的 max_tokens 上限不同。Claude Sonnet 4 支持到 8192GPT-4o 支持到 16384。如果你在 auth.json 里写了 32768网关会直接拒绝。修复方法把max_tokens改到模型支持范围内或者直接删掉这个字段让网关用默认值。排查完这些报错后建议把 auth.json 和 tools/ 目录一起纳入版本管理。auth.json 里用环境变量引用 Keytools/ 目录直接提交。这样换机器或换项目时克隆下来改一下环境变量就能跑不用重新配一遍。5. 从 nanobot 到 Coding Plan轻量 Agent 的长期接入策略nanobot 的工具调用链路验证通过后下一步通常是把它接入日常开发流程。这里有两种典型用法一种是把 nanobot 当私人助手通过 Telegram 或飞书通道接收消息、调用工具、返回结果另一种是把 nanobot 的工具集暴露给编辑器插件在写代码时直接调用。如果你走的是长期编码和 Agent 协作路线TaoToken 的 Coding Plan 比按量计费的 API Key 更适合。Coding Plan 提供固定的月度额度覆盖 Claude、GPT 等主流模型适合每天都有 Agent 调用的场景。开通入口在 https://taotoken.net/console 登录后在套餐页面选择 Coding Plan。接入方式和 API Key 一致Base URL 仍然是https://taotoken.net/api只是 Key 的权限和额度不同。你可以在 auth.json 里用同一个字段名切换套餐时只换 Key 的值代码不用改。对于需要多模型对比的场景比如同一段工具调用逻辑分别用 Claude 和 GPT 跑一遍看效果TaoToken 的模型对话页面可以直接在浏览器里切换模型测试不用改代码。入口在 https://taotoken.net/chat 输入 prompt 后选择模型即可。验证通过后再把 Model ID 写回 auth.json。nanobot 的轻量哲学和 TaoToken 的统一通道其实是互补的。nanobot 把 Agent 核心压到 4000 行让你能读懂每一处逻辑TaoToken 把模型接入压到一个 Base URL 和一个 Key让你不用为每个供应商维护一套配置。两者结合从克隆代码到跑通第一个工具调用我实测下来大概十分钟。如果你在配置过程中遇到 auth.json 解析报错或者工具调用返回的 JSON 结构不符合预期可以先在 https://taotoken.net/doc 查接口文档确认请求体和响应体的字段名。文档里有完整的 curl 示例和错误码说明比在代码里逐行调试快得多。最后一步把run_agent.py里的agent.chat()换成你的真实业务问题比如“帮我查一下今天有哪些待办事项”或者“把这段代码里的 TODO 提取出来”。只要工具函数写好了剩下的交给 AgentLoop 和 TaoToken 的模型通道。
阅读完成 · 觉得有帮助？
