纳米机器人AI助手

📦 Install

[!IMPORTANT] If you want the newest features and experiments, install from source. If you want the most stable day-to-day experience, install from PyPI or with uv.

Pick one install method:

Prerequisites: Python 3.11 or newer. Git is only needed for a source install; Node.js/Bun are only needed if you are developing the WebUI itself.

If terminals, API keys, or config files are new to you, use the guided zero-background walkthrough in Start Without Technical Background instead of this compact README path.

One-command setup

macOS / Linux:

curl -fsSL https://raw.githubusercontent.com/HKUDS/nanobot/main/scripts/install.sh | sh

Windows PowerShell:

irm https://raw.githubusercontent.com/HKUDS/nanobot/main/scripts/install.ps1 | iex

The default command installs or upgrades nanobot-ai from PyPI, then starts nanobot onboard --wizard. It avoids system-wide pip installs by using an active virtual environment, uv, pipx, or a managed venv under ~/.nanobot/venv. If Quick Start finishes and you enabled the WebSocket channel, skip the manual initialize/configure steps below and go straight to Open the WebUI.

To preview the plan without changing your environment, pass --dry-run; combine it with --dev when you want to preview the main-branch install.

curl -fsSL https://raw.githubusercontent.com/HKUDS/nanobot/main/scripts/install.sh | sh -s -- --dry-run

& ([scriptblock]::Create((irm https://raw.githubusercontent.com/HKUDS/nanobot/main/scripts/install.ps1))) --dry-run

To install the current main branch instead, pass --dev:

curl -fsSL https://raw.githubusercontent.com/HKUDS/nanobot/main/scripts/install.sh | sh -s -- --dev

& ([scriptblock]::Create((irm https://raw.githubusercontent.com/HKUDS/nanobot/main/scripts/install.ps1))) --dev

If you prefer to inspect the script first, open scripts/install.sh or scripts/install.ps1.

Install with uv

uv tool install nanobot-ai

Install from PyPI with pip

python -m pip install nanobot-ai

If pip reports externally-managed-environment on macOS or Linux, use the one-command installer, uv tool install nanobot-ai, pipx install nanobot-ai, or install inside a virtual environment.

Install from source

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

Verify the install:

nanobot --version

🚀 Quick Start

1. Initialize

Skip this step if the one-command setup already started the wizard and Quick Start finished there.

nanobot onboard

Use nanobot onboard --wizard if you prefer an interactive setup.

2. Configure (~/.nanobot/config.json)

Skip this step if you already configured provider and model settings in the wizard.

nanobot onboard creates ~/.nanobot/config.json and ~/.nanobot/workspace/. Configure these two parts in the config file. Add or merge the following blocks into the existing file instead of replacing the whole file.

The example below uses a generic OpenAI-compatible custom provider so the compact path does not recommend one hosted service. Provider examples are recipes, not rankings or endorsements. For copyable provider-specific setup, see Provider Cookbook.

Set your API key:

{
  "providers": {
    "custom": {
      "apiKey": "your-api-key",
      "apiBase": "https://api.example.com/v1"
    }
  }
}

Set a model preset and make it active:

{
  "modelPresets": {
    "primary": {
      "label": "Primary",
      "provider": "custom",
      "model": "model-id-from-your-provider",
      "maxTokens": 8192,
      "contextWindowTokens": 200000,
      "temperature": 0.1
    }
  },
  "agents": {
    "defaults": {
      "modelPreset": "primary"
    }
  }
}

Direct agents.defaults.provider and agents.defaults.model still work for existing configs, but named presets are the recommended path because they also power /model switching and fallbackModels.

For another provider, the same config shape still applies:

3. Open the WebUI

If Quick Start enabled the WebSocket channel, start the gateway:

nanobot gateway

Leave that terminal open, then open http://127.0.0.1:8765 in your browser. Enter the WebUI password you set in the wizard, then send your first message there. Prefer not to keep a terminal open? Use nanobot gateway --background, then manage it with nanobot gateway status, logs, restart, and stop.

For manual or terminal-only setup, test one CLI message:

nanobot status
nanobot agent -m "Hello!"

In nanobot status, it is normal for most providers to say not set. The active preset's provider should be configured, and Config plus Workspace should show check marks.

If that works, start an interactive chat:

nanobot agent

Need help with PATH, API keys, provider/model matching, or JSON errors? See the fuller Install and Quick Start and Troubleshooting.

• Want a pasteable provider setup? See Provider Cookbook
• Want to understand provider/model matching? See Providers and Models
• Want web search, MCP, security settings, or more config options? See Configuration
• Want to run locally? See Ollama, vLLM or another local OpenAI-compatible server, and the full provider reference.
• Want to run nanobot in chat apps like Telegram, Discord, WeChat or Feishu? See Chat Apps
• Want Docker or Linux service deployment? See Deployment