运维手册

安装

从源码安装（推荐用于开发）

git clone https://github.com/HKUDS/nanobot.git
cd nanobot
pip install -e .

从 PyPI 安装

pip install nanobot-ai

使用 uv 安装

uv tool install nanobot-ai

安装 Matrix 支持

pip install nanobot-ai[matrix]

首次配置

# 1. 初始化配置和工作区
nanobot onboard

# 2. 编辑配置文件，添加 API 密钥
# macOS/Linux:
vim ~/.nanobot/config.json
# 或使用任意编辑器

# 3. 验证配置
nanobot status

# 4. 发送一条消息测试
nanobot agent -m "Hello!"

最小可用配置

{
  "providers": {
    "openrouter": {
      "apiKey": "sk-or-v1-your-key-here"
    }
  }
}

运行

CLI 模式（交互式）

nanobot agent              # 交互式 REPL
nanobot agent -m "Hello"   # 单条消息
nanobot agent --no-markdown # 纯文本输出
nanobot agent --logs       # 显示调试日志

Gateway 模式（守护进程）

nanobot gateway            # 前台运行

Docker

# 构建镜像
docker build -t nanobot .

# 首次配置
docker run -v ~/.nanobot:/root/.nanobot --rm nanobot onboard

# 运行 gateway
docker run -v ~/.nanobot:/root/.nanobot -p 18790:18790 nanobot gateway

# 执行单条命令
docker run -v ~/.nanobot:/root/.nanobot --rm nanobot agent -m "Hello!"

Docker Compose

docker compose run --rm nanobot-cli onboard   # 首次配置
docker compose up -d nanobot-gateway           # 启动 gateway
docker compose logs -f nanobot-gateway         # 查看日志
docker compose down                            # 停止服务

systemd 用户服务（Linux）

创建 ~/.config/systemd/user/nanobot-gateway.service：

[Unit]
Description=Nanobot Gateway
After=network.target

[Service]
Type=simple
ExecStart=%h/.local/bin/nanobot gateway
Restart=always
RestartSec=10
NoNewPrivileges=yes
ProtectSystem=strict
ReadWritePaths=%h

[Install]
WantedBy=default.target

systemctl --user daemon-reload
systemctl --user enable --now nanobot-gateway
loginctl enable-linger $USER   # 注销后保持服务运行

常用操作

查看状态

nanobot status

显示内容包括：已配置的 provider、已启用的 channel、工作区路径、模型选择。

重置会话

删除对应的会话文件：

rm ~/.nanobot/workspace/sessions/telegram_12345.jsonl

或清除所有会话：

rm ~/.nanobot/workspace/sessions/*.jsonl

查看记忆

cat ~/.nanobot/workspace/memory/MEMORY.md    # 长期记忆
cat ~/.nanobot/workspace/memory/HISTORY.md   # 按时间排列的日志

编辑心跳任务

vim ~/.nanobot/workspace/HEARTBEAT.md

格式：

## Periodic Tasks
- [ ] Check weather forecast and send a summary
- [ ] Scan inbox for urgent emails

添加/更新 Provider 凭据

编辑 ~/.nanobot/config.json 并重启服务：

vim ~/.nanobot/config.json
# 如果以 systemd 服务运行：
systemctl --user restart nanobot-gateway

OAuth Provider 登录

nanobot provider login openai-codex
nanobot provider login github-copilot

WhatsApp 二维码配置

# 终端 1：启动 WhatsApp 桥接
nanobot channels login

# 终端 2：启动 gateway
nanobot gateway

故障排查

问题：”No provider configured”

症状：nanobot agent 返回缺少 API 密钥的错误。

解决方案：

  1. 运行 nanobot status 检查 provider 配置

  2. 确保 ~/.nanobot/config.json 中至少有一个 provider 配置了有效的 apiKey

  3. 检查模型名称是否与已配置的 provider 匹配

问题：”Access denied for sender”

症状：Bot 忽略来自聊天平台的消息。

解决方案：

  1. 检查 channel 配置中的 allowFrom 列表

  2. 将发送者的 ID 添加到 allowFrom

  3. 使用 ["*"] 允许所有发送者（仅用于测试）

  4. 查看日志，确认被拒绝的实际发送者 ID

问题：Channel 连接失败

症状：日志中出现 “Channel not available”。

解决方案：

  1. 检查对应的 channel SDK 是否已安装（部分为可选依赖）

  2. 验证凭据（bot token、app secret 等）

  3. 检查网络连接和代理设置

  4. 对于 WebSocket 类型的 channel（飞书、钉钉、Slack）：确保防火墙允许出站 WebSocket 连接

问题：工具执行失败

症状：Agent 报告工具错误。

解决方案：

  1. 如果启用了工作区限制（restrictToWorkspace: true），确保文件/命令在 ~/.nanobot/workspace/ 范围内

  2. 对于 shell 命令：检查 tools.exec.timeout（默认：60 秒）

  3. 对于 MCP 工具：检查 MCP server 配置中的 toolTimeout（默认：30 秒）

  4. 检查文件权限

问题：记忆/会话数据损坏

症状：回复内容混乱、上下文重复，或出现 “tool_call_id not found” 错误。

解决方案：

  1. 删除受影响的会话文件：rm ~/.nanobot/workspace/sessions/{key}.jsonl

  2. 记忆文件可以手动编辑：~/.nanobot/workspace/memory/MEMORY.md

  3. 重启 gateway

问题：内存占用过高

症状：Python 进程消耗过多 RAM。

解决方案：

  1. 降低 agents.defaults.memory_window（默认：100），使其更积极地进行上下文压缩

  2. 删除旧的会话文件

  3. 减小 agents.defaults.max_tool_iterations（默认：40）

配置参考

环境变量

配置支持通过环境变量覆盖，前缀为 NANOBOT_，嵌套分隔符为 __：

export NANOBOT_AGENTS__DEFAULTS__MODEL="openai/gpt-4o"
export NANOBOT_PROVIDERS__OPENAI__API_KEY="sk-xxx"

关键配置项

配置项

JSON 路径

默认值

说明

模型

agents.defaults.model

anthropic/claude-opus-4-5

LLM 模型标识符

Provider

agents.defaults.provider

auto

Provider 名称或 auto

最大 token 数

agents.defaults.maxTokens

8192

最大响应 token 数

温度

agents.defaults.temperature

0.1

采样温度

工作区

agents.defaults.workspace

~/.nanobot/workspace

工作目录

记忆窗口

agents.defaults.memoryWindow

100

触发上下文压缩的消息数

工具迭代次数

agents.defaults.maxToolIterations

40

最大工具调用轮数

工作区沙箱

tools.restrictToWorkspace

false

对所有工具启用沙箱限制

Shell 超时

tools.exec.timeout

60

Shell 命令超时时间（秒）

心跳间隔

gateway.heartbeat.intervalS

1800

心跳唤醒间隔（秒）

进度流式推送

channels.sendProgress

true

流式推送部分响应

监控

日志输出

  • CLI 模式：日志输出到 stderr（使用 --logs 参数可见）

  • Gateway 模式：日志输出到 stderr（可重定向到文件，或使用 journalctl 查看 systemd 日志）

  • Docker：docker compose logs -f nanobot-gateway

  • systemd：journalctl --user -u nanobot-gateway -f

健康指标

  • Gateway 进程正在运行

  • nanobot status 中 channel 显示为 “enabled”

  • 心跳每 30 分钟触发一次（可在日志中确认）

  • 会话文件持续更新（检查文件时间戳）

备份与恢复

需要备份的内容

路径

优先级

内容

~/.nanobot/config.json

关键

所有凭据和配置

~/.nanobot/workspace/memory/

高

长期记忆和历史记录

~/.nanobot/workspace/sessions/

中

对话历史

~/.nanobot/workspace/skills/

中

用户自定义 skill

~/.nanobot/workspace/HEARTBEAT.md

低

周期性任务定义

恢复步骤

  1. 重新安装 nanobot

  2. 恢复 ~/.nanobot/config.json

  3. 恢复 ~/.nanobot/workspace/ 目录

  4. 运行 nanobot status 验证配置

相关文档

最后更新：2026-03-15 版本：1.0