nanobot 配置教程

更新于 2026-09-27

适用范围：当前 nanobot WebUI、custom 提供商与命名模型预设；消息频道仅说明接入顺序。

版本与验证：2026-09-28 按官方文档核对配置流程。配图为 apizt 原创配置示意图，接入地址统一使用 https://api.apizt.com/v1，聊天模型示例使用 gpt-6-sol。未使用真实 API Key 验证付费调用。

配置速查

配置项	填写内容	注意事项
provider	`custom`	使用通用兼容提供商。
apiBase	`https://api.apizt.com/v1`	custom 必须显式填写地址。
apiKey	`apizt API Key`	填写有效令牌。
modelPresets.apizt.model	`gpt-6-sol`	以实际模型权限为准。
agents.defaults.modelPreset	`apizt`	指向刚创建的预设。

还没有 API Key？注册获取免费体验额度 · 已注册：进入控制台创建 API Key

为此工具单独创建令牌，并设置合理额度和模型权限。截图中的模型仅作示例，以账号当前可用模型为准；不要公开密钥或上传含密钥的配置文件。

先通过 nanobot WebUI 配置 apizt 并验证聊天，再按需要接入消息平台或后台网关。本文同时提供命名模型预设的 JSON 示例。

一、安装并启动 WebUI

准备 Python 3.11 或更高版本，并安装 uv。运行官方安装命令：

uv tool install nanobot-ai
nanobot webui

首次运行按提示确认初始化配置与 WebSocket，浏览器通常打开 http://127.0.0.1:8765。WebUI 会启动或连接共享网关；若终端输出其他地址，以实际输出为准。

二、配置自定义提供商

进入 Settings → Models，添加自定义提供商及凭据。使用 custom 提供商，apiBase 填 apizt 基础地址，apiKey 填自己的令牌。custom 不会自动推断地址，必须填写 apiBase。

nanobot 自定义提供商的 apizt 参数；apizt 配置示意图，接入地址 https://api.apizt.com/v1，模型示例 gpt-6-sol — 图 1：nanobot 自定义提供商的 apizt 参数。原创配置示意图，界面以所装版本为准。图中 sk-demo-not-a-real-key 为无效演示密钥；模型以令牌实际权限为准。点击图片可在页内放大，支持关闭按钮、点击图片外区域和 Esc 关闭。

三、创建并选择模型预设

为模型建立名为 apizt 的预设，provider 设为 custom，model 设为 gpt-6-sol。在默认 Agent 中选中此预设。本文短消息测试使用 maxTokens 1024；上下文窗口按模型实际限制另行设置。

模型预设与默认 Agent 的对应关系；apizt 配置示意图，接入地址 https://api.apizt.com/v1，模型示例 gpt-6-sol — 图 2：模型预设与默认 Agent 的对应关系。原创配置示意图，界面以所装版本为准。图中 sk-demo-not-a-real-key 为无效演示密钥；模型以令牌实际权限为准。点击图片可在页内放大，支持关闭按钮、点击图片外区域和 Esc 关闭。

四、需要手动配置时使用 JSON

配置文件位于 ~/.nanobot/config.json。将下面字段合并到现有配置，保留原有工作区和频道设置；把无效演示密钥替换为自己的 apizt 令牌。已有同名提供商或预设时编辑原项，避免重复键。

{
  "providers": {
    "custom": {
      "apiKey": "sk-demo-not-a-real-key",
      "apiBase": "https://api.apizt.com/v1"
    }
  },
  "modelPresets": {
    "apizt": {
      "provider": "custom",
      "model": "gpt-6-sol",
      "maxTokens": 1024
    }
  },
  "agents": {
    "defaults": {
      "modelPreset": "apizt"
    }
  }
}

当前版本推荐使用 modelPresets 并通过 agents.defaults.modelPreset 选择预设。手动修改文件后重启正在运行的网关，使新配置生效。

五、验证聊天与后台运行

回到 WebUI 新建话题，确认当前模型预设为 apizt。
发送「请只回复：连接成功」，核对正文与 apizt 调用日志。
开始项目任务前，在界面中选择工作区和访问模式。
需要持续运行时，完成配置后启动后台网关，并查看状态与日志。

聊天验证与后台网关检查；apizt 配置示意图，接入地址 https://api.apizt.com/v1，模型示例 gpt-6-sol — 图 3：聊天验证与后台网关检查。原创配置示意图，界面以所装版本为准。图中 sk-demo-not-a-real-key 为无效演示密钥；模型以令牌实际权限为准。点击图片可在页内放大，支持关闭按钮、点击图片外区域和 Esc 关闭。

nanobot gateway --background
nanobot gateway status
nanobot gateway logs

手动调整配置后可运行 nanobot gateway restart；停止后台服务使用 nanobot gateway stop。

六、接入消息平台

模型聊天成功后，再按官方频道文档添加 Telegram、飞书、Discord 等平台。平台 Bot Token 或 App Secret 与 apizt API Key 是不同凭据，分别填入频道配置和模型提供商配置。定时任务与工具能力也应单独验证。

常见问题

已有配置文件可以直接覆盖吗？

将本文字段合并到现有文件，保留频道、工作区等配置；已有同名项应直接编辑。

必须先配置 Telegram 或飞书吗？

可以先在 WebUI 验证模型连接，成功后再接入需要的消息平台。

怎样确认配置已生效

WebUI 当前话题使用 apizt 预设。
短消息有回复，apizt 日志中可核对该次请求。
后台网关状态与日志正常，再继续配置频道。

接入失败时逐项检查

现象	检查与处理
401 / Unauthorized	重新复制有效的 apizt 令牌，检查空格、过期状态和额度。
404 / 接口路径错误	基础地址填写 https://api.apizt.com/v1，不要追加 /chat/completions 或重复 /v1。
模型不存在或无权限	核对完整模型 ID、令牌允许的模型与分组；gpt-6-sol 是本文示例。
429 / 限流或额度不足	按错误体区分余额、令牌额度、并发与速率限制，减少并发后重试。
仍请求旧地址或旧模型	核对当前话题选择的预设、默认 Agent 的 modelPreset，并重启网关。
JSON 无法读取	检查逗号与重复键，合并字段时保留原配置；不要把示意文本作为 JSON。
Agent 工具任务失败	检查模型工具调用支持、所选工作区与访问模式，查看网关错误日志。

资料与下一步

遇到问题时保留软件版本、请求时间、模型 ID、错误码和请求 ID，联系支持时先隐藏 API Key。