nanobot 自托管 AI Agent 部署指南：从本地网关到生产级服务

nanobot 自托管 AI Agent 部署指南从本地网关到生产级服务【免费下载链接】nanobotUltra-lightweight, open-source, self-hosted personal AI agent framework in Python with WebUI, tools, memory, MCP, multi-agent workflows, automation, and chat apps项目地址: https://gitcode.com/gh_mirrors/nanob/nanobotnanobot 是一个基于 Python 的轻量级、开源、可自托管的个人 AI Agent 框架。本文以官方指南 self-hosted-ai-agent.md 为主线完整讲解如何在自有机器或服务器上把 nanobot 运行成一个长期在线的网关进程它将统一承载 WebUI 浏览器工作台、聊天应用chat apps、自动化任务与 OpenAI 兼容 API 集成。读完本文你将掌握从pip安装、config.json模型配置到 Docker / systemd / macOS LaunchAgent 生产部署、健康检查与安全加固的完整自托管方案。自托管路径解决什么问题选择自托管路径意味着对 Agent 的进程、工作区文件、记忆文件与模型密钥拥有完全的所有权。它与临时运行一个 CLI 命令的本质区别在于Agent 必须在某条终端命令结束后继续运行——网关进程需要把聊天应用、定时自动化、WebSocket 消息投递等服务长期维持在线上。从源码结构看整个自托管能力围绕gateway这一核心命令展开CLI 入口位于 nanobot/cli/gateway.py进程生命周期管理前台/后台、按需启动/常驻实现在 nanobot/gateway/runtime.py而网关真正拉起 WebUI、聊天频道、cron 系统任务与健康端点的共享运行时则位于 nanobot/cli/gateway_runtime.py。安装与最小可用验证1. 安装 nanobot官方指南推荐使用 pip 安装稳定版python -m pip install nanobot-ai随后通过向导初始化配置nanobot onboard --wizard该命令会创建~/.nanobot/config.json和~/.nanobot/workspace/。如果配置已存在但版本较旧可用nanobot onboard --refresh在保留既有值的前提下补充新增的默认字段。2. CLI 连通性检查部署网关之前务必先完成 CLI 检查nanobot agent -m Hello!这一步同时验证了安装、配置、Provider、模型与工作区写入五个环节。指南明确强调部署问题在 Provider 和模型已被证明可用之后要容易调试得多——如果连 CLI 单次对话都不通就不应继续排查网关或频道问题。nanobot status可在不调用模型的前提下检查配置与工作区是否就绪、活动模型与 Provider 是否已配置是部署前最常用的预检命令。最小可用示例两个启动入口的选择nanobot gateway面向聊天应用与自动化的常驻进程nanobot gateway这是聊天应用Telegram、Discord、Slack、Feishu 等、自动化任务与 WebSocket 投递的入口。启动后它会加载启用状态的聊天频道、WebUI/WebSocket 通道、cron 系统任务、Dream、心跳与健康端点。默认以前台方式运行CtrlC可停止需要脱离终端常驻时使用nanobot gateway --background配合nanobot gateway status、logs、restart、stop管理后台进程。nanobot webui浏览器工作台的启动器nanobot webui浏览器表面使用 WebUI 启动器它会为你准备本地 WebUI 设置、启动网关并打开浏览器通常监听http://127.0.0.1:8765。WebUI 启动器可以替你把本地网关管理起来关闭最后一个交互式启动器时按需网关才会停止若希望持久后台运行可改用nanobot gateway --background。通过 config.json 接入聊天频道在~/.nanobot/config.json中启用一个频道后保持同一个网关进程即可持续接收消息。例如接入 Telegram{ agents: { defaults: { workspace: ~/.nanobot/workspace } }, channels: { telegram: { enabled: true, token: YOUR_TELEGRAM_BOT_TOKEN } }, gateway: { host: 127.0.0.1, port: 18790 } }注意config.json使用 camelCase 键如apiKey、intervalSsnake_case 键仅为兼容而保留编辑配置后需重启部署的进程长驻进程只在启动时读取配置。启动频道前可用nanobot channels status预检用nanobot gateway --verbose观察频道启动日志。配置模型 Providerconfig.json 的连接方式自托管的关键一步是把模型 Provider 接入config.json。一个通用的 OpenAI 兼容 Provider 配置形如{ providers: { custom: { apiKey: ${PROVIDER_API_KEY}, apiBase: https://api.example.com/v1 } }, modelPresets: { primary: { provider: custom, model: model-id-from-your-provider } }, agents: { defaults: { modelPreset: primary } } }三个层次各司其职providers.name定义凭证与端点。apiKey可写apiKey字段apiBase仅在端点与默认值不同时需要设置modelPresets.preset给模型组合命名Provider 模型 ID便于切换与回退agents.defaults.modelPreset指定活动预设决定 Agent 默认调用哪个模型。配置提示若配置文件中缺少当前 schema 的字段运行nanobot onboard --refresh即可补齐默认值。完整的字段参考见 configuration.md模型与 Provider 匹配问题可先查 providers.md。生产部署让进程在终端退出后继续存活指南强调当进程需要在终端退出后依然存活时应使用 Docker、systemd 或 macOS LaunchAgent。以下按官方部署文档 deployment.md 展开三种主流运行时。部署前的检查清单检查项为什么重要nanobot status显示预期的 config 与 workspace确认进程读取的是你打算运行的实例nanobot agent -m Hello!可用在叠加服务层之前证明安装、配置、Provider、模型、工作区写入全部正常密钥存放在环境变量或受保护的配置文件中API 密钥、机器人 token、OAuth 状态不应被世界可读活动配置目录含sessions/与 workspace 持久化会话跟随--config记忆、生成产物与工作区身份标记跟随 workspace频道访问控制是刻意的暴露机器人前使用allowFrom、配对、WebSockettoken/tokenIssueSecret或私有测试频道端口规划明确网关健康默认仅本机127.0.0.1:18790WebUI/WebSocket 默认8765nanobot serve默认8900日志便于获取使用docker compose logs、journalctl、LaunchAgent 日志文件或nanobot gateway --verboseDocker Compose 部署仓库自带 docker-compose.yml 与 Dockerfile。典型流程docker compose run --rm nanobot-cli onboard # 首次初始化 vim ~/.nanobot/config.json # 添加 API 密钥 docker compose up -d nanobot-gateway # 启动网关常用运维命令docker compose run --rm nanobot-cli agent -m Hello! # 运行 CLI docker compose logs -f nanobot-gateway # 查看日志 docker compose down # 停止容器以非 root 用户nanobotUID 1000运行读取/home/nanobot/.nanobot下的配置。务必把宿主配置目录挂载到该路径-v ~/.nanobot:/home/nanobot/.nanobot而非/root/.nanobot。遇到Permission denied时先在宿主机修正所有权sudo chown -R 1000:1000 ~/.nanobot或传入--user $(id -u):$(id -g)匹配宿主 UID。关键限制网关与 WebSocket 通道默认绑定host: 127.0.0.1默认值定义于 nanobot/config/schema.py。Docker 的-p端口转发无法到达容器的 loopback 接口因此要让宿主机或局域网访问暴露的端口必须在容器启动前把两个绑定都改为0.0.0.0{ gateway: { host: 0.0.0.0 }, channels: { websocket: { host: 0.0.0.0, port: 8765, tokenIssueSecret: your-secret-here } } }当 WebSockethost为0.0.0.0时频道会拒绝启动除非同时配置了token、tokenIssueSecret或完整的trustedProxyAuth。健康路由本身刻意保持极简且未认证容器将其绑定到0.0.0.0时应只把端口18790发布到宿主 loopback并把任何远程监控所需的健康端点置于防火墙或反向代理之后。systemd 用户服务Linux先预览生成的 unitnanobot gateway install-service --manager systemd --dry-run安装、启用并启动nanobot gateway install-service --manager systemd为自定义实例传递与网关运行一致的配置/工作区选择器nanobot gateway install-service \ --manager systemd \ --name nanobot-telegram \ --config ~/.nanobot-telegram/config.json \ --workspace ~/.nanobot-telegram/workspace日常操作systemctl --user status nanobot-gateway # 查看状态 systemctl --user restart nanobot-gateway # 修改配置后重启 journalctl --user -u nanobot-gateway -f # 跟踪日志 nanobot gateway uninstall-service --manager systemd安装器会写入~/.config/systemd/user/nanobot-gateway.service以当前 Python 解释器执行python -m nanobot gateway --foreground因此服务运行在你安装 nanobot 的同一环境中。注意用户服务只在登录期间运行若要在注销后继续存活启用 lingeringloginctl enable-linger $USERmacOS LaunchAgentnanobot gateway install-service --manager launchd --dry-run # 预览 plist nanobot gateway install-service --manager launchd # 安装并启动自定义实例与 systemd 用法一致--name、--config、--workspace。安装器写入~/Library/LaunchAgents/ai.nanobot.gateway.plist日志落在~/.nanobot/logs/。若启动报 address already in use先停止手动启动的nanobot gateway进程。多实例隔离给每个部署独立的 config、workspace 与端口指南生产注意事项中强调给每个部署实例独立的配置路径、工作区路径与端口集合这正是 multiple-instances.md 的主题--config是主要入口--workspace在需要初始化或更新某个实例的已存工作区时可选传入。初始化多个实例nanobot onboard --config ~/.nanobot-telegram/config.json --workspace ~/.nanobot-telegram/workspace nanobot onboard --config ~/.nanobot-discord/config.json --workspace ~/.nanobot-discord/workspace分别运行nanobot status --config ~/.nanobot-telegram/config.json nanobot gateway --config ~/.nanobot-telegram/config.json nanobot gateway --config ~/.nanobot-discord/config.json --port 18792各组件解析来源组件解析自示例配置--config路径~/.nanobot-A/config.json工作区--workspace或配置~/.nanobot-A/workspace/会话配置目录 workspace ID~/.nanobot-A/sessions/workspace-id/Cron 任务工作区目录~/.nanobot-A/workspace/cron/媒体/运行时状态配置目录~/.nanobot-A/media/同一时刻运行的每个实例必须使用不同端口会话数据跟随活动配置目录每个实例使用独立 workspace 可隔离记忆、技能与稳定的会话命名空间 ID。健康检查只探测进程与 WebSocket 通道指南要求对网关或 API 进程做健康检查而不是把聊天应用投递作为唯一信号。健康检查的实现可以从源码确认_health_server在 nanobot/cli/gateway_runtime.py 中作为极简 HTTP 端点实现GET /health的响应载荷由_gateway_readiness_payload生成{status:ok,process:alive,ready:true,websocket:disabled}语义明确当 WebSocket 通道禁用或运行中返回200 OK当 WebSocket 通道已启用但未运行返回503 Service Unavailable其他路径返回404ready目前只反映 WebSocket 通道200响应不验证其他聊天频道、MCP 服务器或模型 Provider 的连通性。该检查逻辑在 nanobot/gateway/runtime.py 的_gateway_health_ready中用于后台网关就绪诊断要求响应status ok且ready不为false。默认健康端点http://127.0.0.1:18790/health由--port覆盖而 OpenAI 兼容 API 的/health在 nanobot/api/server.py 中返回{status: ok}且明确放行未认证访问。健康端点刻意保持未认证与最小化需要远程监控时务必用防火墙或反向代理保护。安全加固暴露前的必备检查指南的安全注意事项可以展开为四组可落地的配置。1. 工作区限制与 shell 沙箱{ tools: { restrictToWorkspace: true, exec: { enable: true, sandbox: bwrap } } }restrictToWorkspace是应用层防护不是操作系统沙箱它会将工具的文件读写约束在工作区内bwrap仅限 Linux需要安装 bubblewrapmacOS 或 Windows 上应保持restrictToWorkspace开启并谨慎审查 shell 访问tools.exec.enable: false可彻底移除 shell 执行能力在 Docker 中启用bwrap需要额外的能力CAP_SYS_ADMIN并关闭 AppArmor/seccomp 限制否则bwrap可能报clone3: Operation not permitted详见 deployment.md 中的 bwrap override 方案。2. 网络与密钥除非刻意暴露否则把仅本地的服务绑定到127.0.0.1在把 OpenAI 兼容 API 绑定到公网接口之前必须设置 API 密钥公开绑定要求api.apiKey以 Bearer token 形式发送密钥使用${VAR_NAME}占位符从环境变量解析解析仅在启动时于内存中进行永不写回磁盘{ channels: { telegram: { token: ${TELEGRAM_TOKEN} } }, providers: { groq: { apiKey: ${GROQ_API_KEY} } } }若引用的环境变量未设置nanobot 会快速失败并报告具体配置字段与变量名不回显字段值。systemd 可用EnvironmentFile、Docker 可用--env-file、本地可用 direnv 或op run/pass等密钥管理器加载变量HTTP web fetch 与 HTTP MCP 默认启用 SSRF 防护放宽tools.ssrfWhitelist会增大暴露面。3. 聊天应用访问控制支持私聊DM的聊天应用优先使用**配对pairing**机制必须使用静态白名单时保持allowFrom严格如[alice, bob]allowFrom: [*]会绕过配对意味着任何能触达该频道的人都能与机器人对话群组策略优先设为仅提及mention-only暴露 WebSocket 通道时websocketRequiresToken默认true生产环境优先用短时签发 tokentokenIssuePathtokenIssueSecret而非把静态密钥嵌入客户端详见 websocket.md。4. 每信任边界一个 workspace保持每个信任边界一个 workspace不同团队、不同租户或测试/生产环境之间用独立 workspace 隔离记忆、技能与会话。安全主题的完整清单见 secure-local-ai-agent.md 与 configuration.md 的 Security、Pairing 章节。故障排查指南给出的三个诊断手段可以进一步结合 CLI 参考 cli-reference.md 展开用服务相同的选择器检查状态使用服务启动时相同的--config与--workspace标志运行nanobot status确认进程读取的是你预期的那份配置调试频道启动运行nanobot gateway --verbose观察详细日志-v会把日志级别提升到 DEBUGnanobot channels status可在启动前预检频道配置检查端口冲突WebUI、WebSocket 通道或 API 端点绑定失败时优先确认端口占用。默认端口为网关健康18790、WebUI/WebSocket8765、nanobot serveAPI8900。相关文档导航DeploymentRender、Docker、systemd、LaunchAgent 全量部署手册Multiple Instances多实例路径解析与端口规划Configuration完整配置参考与安全/配对章节Chat Apps各聊天平台接入前置条件OpenAI-Compatible APInanobot serve的 API 集成方式Quick Start首次安装与浏览器工作台路径CLI Reference全部命令的精确参数与形态【免费下载链接】nanobotUltra-lightweight, open-source, self-hosted personal AI agent framework in Python with WebUI, tools, memory, MCP, multi-agent workflows, automation, and chat apps项目地址: https://gitcode.com/gh_mirrors/nanob/nanobot创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考