nanobot 接入 MoxAI 教程：配置轻量级 AI 智能体

本文整理自 MoxAI 帮助中心，并改写为博客教程，适合希望把 AI Agent、AI 编程助手或桌面客户端接入 MoxAI 的用户参考。

项目介绍

nanobot 是一个轻量级 AI 智能体，支持接入常用聊天工具，通过单个 config.json 配置文件自定义 API 端点。依赖 uv 管理 Python 环境，安装和启动都非常简单。

📦 接入前准备

准备信息

• 已安装 uv
• 一个可用的 MoxAI 地址（必须以 /v1 结尾）
• 一个可用的 MoxAI API Key（在控制台生成）
• 想使用的模型名称（如 claude-sonnet-4-6、gemini-2.5-flash 等，需与 MoxAI 控制台中的模型 ID 完全一致）

🚀 第一步：安装 nanobot

uv tool install nanobot-ai

Windows 额外步骤

Windows 用户需将 .local/bin 添加到环境变量，以便直接调用 nanobot 命令：

$env:PATH = "$env:USERPROFILE\.local\bin;$env:PATH"

建议将其写入 PowerShell Profile 以便持久化。

验证安装

nanobot --version

🔧 第二步：初始化并编辑配置

1. 生成默认配置

nanobot onboard

该命令会在用户目录下创建配置文件：

• Windows：%USERPROFILE%\.nanobot\config.json
• Linux / macOS：~/.nanobot/config.json

2. 修改 config.json

将 providers 和 agents.defaults 配置为指向 MoxAI：

{
  "agents": {
    "defaults": {
      "model": "claude-sonnet-4-6",
      "provider": "moxai"
    }
  },
  "providers": {
    "moxai": {
      "apiKey": "your-moxai-api-key",
      "apiBase": "https://api.moxai.ai"
    }
  }
}

字段要点

• apiBase 必须以 /v1 结尾
• model 必须是 MoxAI 控制台中实际暴露的模型 ID
• 多个 provider 可并列配置，agents.defaults.provider 指定默认使用哪个

✅ 第三步：启动并验证

nanobot agent

启动后输入任意问题（例如 "你好，告诉我今天是星期几"），模型正常响应即配置成功。

🔄 切换模型

直接修改 config.json 中的 agents.defaults.model，保存后重启 nanobot agent 即可切换模型。

❓ 常见问题

问题解决方案nanobot 命令找不到Windows 用户需把 .local/bin 加入 PATH401 Unauthorized确认 apiKey 已正确填入 config.json模型不存在核对 model 字段与 MoxAI 控制台完全一致修改配置后没生效配置修改需重启 nanobot agent 才能加载

更多配置细节可参考 MoxAI 帮助中心原文。