NanoClaw智能体 安装与配置保姆级教程

从零环境到跑起来，一步一步讲清楚如何搭建 AI 编程 Agent 环境。

目录

• 一、NanoClaw 是什么
• 二、环境准备
• 三、安装 Git
• 四、创建 Python 虚拟环境
• 五、下载 NanoClaw
• 六、安装依赖
• 七、配置大模型 API
• 八、配置环境变量
• 九、配置模型
• 十、启动 NanoClaw
• 十一、运行第一个 Agent 任务
• 十二、Skills 能力扩展
• 十三、常见问题
• 十四、进阶玩法

一、NanoClaw 是什么

NanoClaw 是 OpenClaw 生态里的轻量版 Agent 运行器。它把大语言模型变成可执行任务的智能体，能自动完成多种开发相关任务。

能做什么

核心特点

• 轻量：资源占用小，适合本地或边缘部署
• 本地运行：数据与任务可在本机完成，隐私可控
• 配置简单：环境变量 + 配置文件即可接入大模型
• 多模型支持：OpenAI、DeepSeek、OpenRouter 等兼容接口均可使用

适合想快速搭建 AI 编程 Agent 的开发者，无需从零造轮子。

二、环境准备

安装前请确保具备以下基础环境。

建议版本

检查 Python

python3 --version

应看到类似 Python 3.10.x 或更高。

未安装时的安装方式

macOS（推荐 Homebrew）：

brew install python

Ubuntu / Debian：

sudo apt update
sudo apt install python3 python3-pip python3-venv

Windows：

1. 打开 python.org 下载安装包
2. 安装时务必勾选「Add Python to PATH」
3. 安装完成后在终端执行 python --version 验证

三、安装 Git

NanoClaw 源码托管在 GitHub，需要 Git 进行克隆与更新。

检查是否已安装

git --version

未安装时

macOS：

brew install git

Ubuntu / Debian：

sudo apt install git

Windows：
从 https://git-scm.com 下载并安装，安装过程中可保留默认选项。

四、创建 Python 虚拟环境

使用虚拟环境可以避免与系统 Python 或其他项目依赖冲突，强烈建议为 NanoClaw 单独建一个环境。

创建环境

进入你打算放置项目的目录，执行：

python3 -m venv nanoclaw-env

激活环境

macOS / Linux：

source nanoclaw-env/bin/activate

Windows（CMD）：

nanoclaw-env\Scripts\activate.bat

Windows（PowerShell）：

nanoclaw-env\Scripts\Activate.ps1

确认激活成功

激活后，命令行前会出现 (nanoclaw-env)，例如：

(nanoclaw-env) user@host:~/projects$

之后所有 pip install 都会安装到这个环境中。

五、下载 NanoClaw

克隆仓库

确保已激活虚拟环境，然后执行：

git clone https://github.com/openclaw/nanoclaw.git
cd nanoclaw

项目结构概览

ls

常见目录与文件：

六、安装依赖

在项目根目录（即 nanoclaw 目录）下执行：

pip install -r requirements.txt

国内加速（可选）

若从 PyPI 下载较慢，可使用清华源：

pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple

其他常用镜像：

• 阿里云：https://mirrors.aliyun.com/pypi/simple/
• 中科大：https://pypi.mirrors.ustc.edu.cn/simple/

依赖安装完成后，NanoClaw 的运行环境即就绪。

七、配置大模型 API

NanoClaw 不内置模型，需要接入外部大模型 API。只要兼容 OpenAI 风格接口，一般都可使用。

常见可选模型/平台

下文以 DeepSeek 为例说明配置步骤。

获取 DeepSeek API Key

1. 打开 platform.deepseek.com
2. 注册/登录账号
3. 进入 API 或密钥管理页面，创建 API Key
4. 复制并妥善保存 Key（仅显示一次）

八、配置环境变量

在 NanoClaw 项目根目录 下创建 .env 文件（与 main.py 同级），用于存放 API 密钥和 Base URL。

使用 DeepSeek

在 .env 中写入（将 你的key 替换为实际 Key）：

OPENAI_API_KEY=你的key
OPENAI_BASE_URL=https://api.deepseek.com

很多基于 OpenAI 接口的客户端通过 OPENAI_BASE_URL 切换后端，因此即使不用 OpenAI，变量名也常保持为 OPENAI_*。

使用原生 OpenAI

若直接使用 OpenAI 官方接口，可只配置 Key（不设 OPENAI_BASE_URL 则默认为 OpenAI）：

OPENAI_API_KEY=sk-xxxx

使用 OpenRouter

若通过 OpenRouter 调用多种模型：

OPENAI_API_KEY=你的_openrouter_key
OPENAI_BASE_URL=https://openrouter.ai/api/v1

保存 .env 后，不要把该文件提交到 Git；建议在 .gitignore 中已有 .env。

九、配置模型

模型名称、温度、最大 token 等可在配置文件中修改。

配置文件位置

configs/model.yaml

示例配置（DeepSeek）

model:
  provider: openai
  name: deepseek-chat
  temperature: 0.2
  max_tokens: 4096

• provider：与代码中的调用方式一致，多数兼容接口都填 openai
• name：模型 ID，DeepSeek 聊天模型为 deepseek-chat
• temperature：越低越稳定，编程任务常用 0.1～0.3
• max_tokens：单次回复最大 token，按需调整

其他模型示例

使用 GPT-4o mini：

model:
  provider: openai
  name: gpt-4o-mini
  temperature: 0.2
  max_tokens: 4096

使用 DeepSeek：

model:
  provider: openai
  name: deepseek-chat
  temperature: 0.2
  max_tokens: 4096

保存 configs/model.yaml 后，重启 NanoClaw 即可生效。

十、启动 NanoClaw

在项目根目录、且已激活虚拟环境的前提下执行：

python main.py

启动成功的表现

若配置正确，终端中会出现类似输出：

NanoClaw Agent initialized
Model loaded
Ready for tasks

表示 Agent 已就绪，可以接收任务。

十一、运行第一个 Agent 任务

启动后，可按提示输入自然语言任务，由 Agent 调用模型与 Skills 执行。

示例任务

分析当前仓库：

Analyze this repository and explain the architecture.

让 Agent 写一个脚本：

Write a Python script that downloads images from a URL list.

其他可尝试的指令：

• 「在当前目录创建一个 README，简要说明项目用途」
• 「找出所有 TODO 注释并列成清单」
• 「给 main.py 里某某函数加一段单元测试」

NanoClaw 会结合上下文、Skills（文件编辑、Shell、Git 等）完成操作，并在终端输出过程与结果。

十二、Skills 能力扩展

Skills 是 NanoClaw 的能力插件，决定 Agent 能执行哪些具体操作。

常见内置 Skills

存放位置

skills/

目录下通常能看到类似 file_editor、shell_executor、git_tools、repo_analyzer 等模块。Agent 会根据任务描述自动选择要调用的 Skills，无需手动指定。

自定义 Skill（进阶）

若项目支持，可在 skills/ 下按既有规范新增自定义 Skill，扩展例如「调用内部 API」「跑特定脚本」等能力。具体可参考仓库文档或现有 Skill 实现。

十三、常见问题

1. 模型无法调用 / 一直超时

排查顺序：

• API Key：确认 .env 中 OPENAI_API_KEY 正确、无多余空格、未过期
• BASE_URL：使用 DeepSeek、OpenRouter 等时，确认 OPENAI_BASE_URL 与文档一致
• 模型名称：configs/model.yaml 里的 name 必须与平台提供的模型 ID 一致（如 deepseek-chat、gpt-4o-mini）
• 网络：若用国外 API，检查代理或防火墙是否拦截

2. Token 超限或报错

若报错与 token 长度、超限相关：

• 在 configs/model.yaml 中把 max_tokens 调小，例如改为 2048
• 若任务上下文很长，可适当提高（在模型允许范围内），或精简输入

3. 依赖安装失败

先升级 pip，再重装依赖：

pip install --upgrade pip
pip install -r requirements.txt

若某包仍失败，可查看报错中的包名与版本，尝试单独安装或使用兼容版本。

4. 虚拟环境未激活

若执行 python main.py 时提示找不到依赖，多半是未激活虚拟环境。请先执行：

• macOS/Linux：source nanoclaw-env/bin/activate
• Windows：nanoclaw-env\Scripts\activate

确认命令行前有 (nanoclaw-env) 后再运行。

十四、进阶玩法

在熟悉基础安装与配置后，可以进一步把 NanoClaw 集成到工作流中。

更多任务类型

• 自动生成 PR：根据分支改动生成 PR 描述或初版说明
• 自动修复代码：根据 linter/测试错误尝试补丁
• 编写测试：为指定模块生成单元测试或用例
• 分析大型仓库：总结模块划分、依赖关系与潜在风险
• 串联多步任务：如「先分析 → 再改代码 → 再跑测试」

与现有工具集成

许多开发者会把 NanoClaw 接到自动化流水线中，例如：

这样就能把 NanoClaw 当成团队内的 自动化 AI 工程助手 使用。

延伸阅读

若你希望有一份更贴近实战的编排示例，可以继续查阅：

• NanoClaw + DeepSeek + GitHub 的完整 AI Coding Agent 工作流教程
• OpenClaw 官方文档与示例仓库中的进阶配置说明

祝你把 NanoClaw 用得顺手，开发效率更上一层楼。