1. 为什么我要在本地跑一个 4000 行的 Agent 框架OpenClaw 火起来之后我身边不少做 Python 的朋友都去 clone 了源码结果大多停在第一步43 万行代码光是搞清楚消息从哪个模块进、工具调用在哪一层被拦截就得花掉一个周末。如果你只是想理解 AI Agent 到底怎么运转或者想快速验证一个「让模型自己调工具干活」的想法这种体量的项目其实有点重。nanobot 解决的就是这个痛点。它是一个用约 4000 行 Python 写成的极简 AI Agent 框架把 OpenClaw 里最核心的几件事——代理循环、消息总线、工具调用、长期记忆、多 LLM 接入——用能读得完的代码量重新实现了一遍。适合谁适合想快速上手 Python AI Agent 的开发者、想拿一个可改可调的骨架做原型的独立开发者以及想搞明白「Agent 框架到底在干什么」的学习者。我这次的目标很明确把 nanobot 在本地跑起来用 TaoToken 的统一 Key 打通模型通道然后发一条真实消息验证整条链路是通的。下面是我实际走通的步骤配置可以直接复制。2. 前置准备TaoToken 统一 Key 与运行环境nanobot 本身通过 LiteLLM 统一接口对接各家模型这意味着你只要给它一个兼容 OpenAI 协议的 base_url 和 key它就能跑。TaoToken 在这里扮演的角色就是那个「统一入口」一个 Key 覆盖多种模型省去在 nanobot 里为每个 provider 单独配环境变量的麻烦。你需要先拿到 Key。访问 https://taotoken.net/api-keys 创建注意这个页面是控制台里的密钥管理入口创建后复制那串 sk- 开头的字符串只显示一次。环境方面Python 3.10 以上即可我本地用的是 3.11。建议单独建虚拟环境避免和系统里的包打架python -m venv venv source venv/bin/activate # Windows 用 venv\Scripts\activate pip install --upgrade pip然后拉取 nanobot 源码并安装依赖。nanobot 的依赖刻意保持精简主要就是 litellm、pydantic、httpx 这几个git clone https://github.com/HKUDS/nanobot.git cd nanobot pip install -e .装完之后用python -c import nanobot; print(nanobot.__file__)确认一下包能被正确导入。如果这一步报 ModuleNotFoundError多半是虚拟环境没激活或者 pip 装到了全局。注意TaoToken 的 API 地址是 https://taotoken.net/api配置时 base_url 要带上这个前缀不要只写域名。Key 通过环境变量注入不要硬编码进 config.toml 提交到仓库。3. 可复制的 config.toml 骨架与 Key 配置nanobot 的配置走 TOML 格式默认会读工作目录下的 config.toml。下面这份是我调通后精简出来的骨架你可以直接拿去改# config.toml - nanobot 最小可运行配置 [agent] name nanobot-local workspace ./workspace max_tool_iterations 5 [provider] # 走 TaoToken 统一入口兼容 OpenAI 协议 model gpt-4o-mini base_url https://taotoken.net/api api_key_env TAOTOKEN_API_KEY [memory] enabled true memory_file MEMORY.md daily_note_dir ./workspace/notes [tools] enabled [read_file, write_file, list_directory, execute_command] workspace_only true [channels.cli] enabled true几个关键点解释一下。[provider]段里的base_url指向 TaoToken 的 API 地址api_key_env告诉 nanobot 从哪个环境变量读 Key这样配置文件本身不含敏感信息。model字段填你想用的模型名TaoToken 会按这个名字路由到对应后端。[tools]段里的workspace_only true是个安全开关它把所有文件操作限制在 workspace 目录内配合 nanobot 内置的命令黑名单能挡住大部分误操作。max_tool_iterations 5控制单条消息最多触发几轮工具调用防止模型陷入死循环。设置环境变量export TAOTOKEN_API_KEYsk-你的keyWindows PowerShell 用$env:TAOTOKEN_API_KEYsk-你的key。想持久化就写进 shell 的 rc 文件但别写进项目里的 .env 然后提交。4. 启动 nanobot 并验证 API 通道连通性配置就绪后先做一次纯 API 连通性验证把 Agent 逻辑排除在外。nanobot 的 provider 层基于 LiteLLM我们可以直接用它的接口打一发请求# verify_channel.py import os from litellm import completion resp completion( modelopenai/gpt-4o-mini, api_basehttps://taotoken.net/api, api_keyos.environ[TAOTOKEN_API_KEY], messages[{role: user, content: 只回复两个字通了}], ) print(resp.choices[0].message.content)跑python verify_channel.py如果终端打印出「通了」说明 Key、base_url、模型名三者都对上了。这一步失败的话先别急着启动 nanobot问题一定在通道层。通道确认后启动 nanobot 本体python -m nanobot --config config.toml你会看到 CLI 通道启动的日志类似[cli] channel started和[agent] loop running。这时候在终端输入一条消息比如「列出 workspace 目录下的文件」观察日志里是否出现工具调用记录[tool] list_directory called with {path: ./workspace} [tool] result: (empty) [agent] response sent如果看到[tool]开头的行说明 AgentLoop 成功解析了模型的工具调用意图并执行了。再试一条带记忆的「记住我的项目叫 nanobot-demo」然后退出重启问它「我的项目叫什么」如果它能答出来说明 MEMORY.md 的读写链路也通了。5. 本篇常见错误排查报错一litellm.exceptions.AuthenticationErrorKey 没读到或者写错了。先echo $TAOTOKEN_API_KEY确认环境变量在当前 shell 可见再检查 config.toml 里api_key_env的名字和实际变量名是否一字不差。注意大小写。报错二openai.APIConnectionError: Connection errorbase_url 写错了。常见的是漏了/api后缀或者写成了https://taotoken.net。正确值是https://taotoken.net/api。另外确认本机网络能正常访问该域名。报错三模型返回model not foundmodel字段填的名字 TaoToken 不认识。换成明确的模型标识比如gpt-4o-mini或claude-3-5-sonnet不要填自定义别名。报错四工具调用不触发模型只回文字检查[tools]段的enabled列表是否包含你期望的工具以及max_tool_iterations是否被设成了 0。另外有些小模型对 function calling 支持不好换一个工具调用能力强的模型再试。报错五PermissionError写文件失败workspace_only true时所有路径都会被解析到 workspace 目录下。如果你传的是绝对路径会被拒绝。改成相对路径或者把 workspace 指到你真正想操作的目录。报错六启动后无响应卡在loop runningCLI 通道可能没启用。确认 config.toml 里有[channels.cli]且enabled true。如果用的是其他通道比如 Telegram需要额外配 token本篇不展开。6. 把 Key 和文档放在手边继续往下改跑通之后你手上就有了一个能读、能改、能扩展的 Agent 骨架。接下来想加自定义工具就继承Tool基类实现name、description、parameters、execute四个成员想换模型改 config.toml 里的model字段即可Key 不用动。统一 Key 的好处在这里体现得很明显你不需要为每个模型维护一套环境变量也不用在代码里写 provider 分支。所有模型请求都从同一个入口出去切换成本几乎为零。如果你在接入过程中遇到通道报错先去 https://taotoken.net/api-keys 核对 Key 状态再对照 https://taotoken.net/doc 里的接入说明检查 base_url 和请求格式。想先确认某个模型在当前 Key 下是否可用可以直接在 https://taotoken.net/models 里发一条对话测试排除是模型侧还是代码侧的问题。长期用 nanobot 做编码或 Agent 实验的话https://taotoken.net/coding-plan 里的额度方案比按次调用更划算适合高频调试场景。