Improve onboard wizard setup flow
This commit is contained in:
chengyongru
Xubin Ren
@@ -155,7 +155,7 @@ The key (`webhook`) becomes the config section name. The value points to your `B
|
||||
```bash
|
||||
python -m pip install -e .
|
||||
nanobot plugins list # verify "Webhook" shows as "plugin"
|
||||
nanobot onboard # auto-adds default config for detected plugins
|
||||
nanobot onboard --defaults # auto-adds default config for detected plugins
|
||||
```
|
||||
|
||||
Edit `~/.nanobot/config.json`:
|
||||
@@ -507,7 +507,7 @@ async def start(self) -> None:
|
||||
|
||||
`allowFrom` is handled automatically by `_handle_message()` — you don't need to check it yourself.
|
||||
|
||||
Override `default_config()` so `nanobot onboard` auto-populates `config.json`:
|
||||
Override `default_config()` so `nanobot onboard --defaults` auto-populates `config.json`:
|
||||
|
||||
```python
|
||||
@classmethod
|
||||
|
||||
@@ -7,8 +7,8 @@ Use this page when you know what you want to run and need the command shape. For
|
||||
| Goal | Command | Notes |
|
||||
|---|---|---|
|
||||
| Check the install | `nanobot --version` | If this fails, try `python -m nanobot --version` |
|
||||
| Create or refresh config | `nanobot onboard` | Creates `~/.nanobot/config.json` and `~/.nanobot/workspace/` |
|
||||
| Use guided setup | `nanobot onboard --wizard` | Best when you prefer prompts over hand-editing JSON |
|
||||
| Use guided setup | `nanobot onboard` | Best when you prefer prompts over hand-editing JSON |
|
||||
| Create or refresh defaults | `nanobot onboard --defaults` | Creates `~/.nanobot/config.json` and `~/.nanobot/workspace/` without prompts |
|
||||
| Check config without calling a model | `nanobot status` | Reads the default config and summarizes the active model/provider |
|
||||
| Send one test message | `nanobot agent -m "Hello!"` | First proof that install, config, provider, model, and workspace all work |
|
||||
| Chat in the terminal | `nanobot agent` | Interactive local chat; exit with `exit`, `/exit`, `:q`, or `Ctrl+D` |
|
||||
@@ -52,9 +52,11 @@ Long-running commands keep working until you stop them. Press `Ctrl+C` in that t
|
||||
|
||||
| Command | Description |
|
||||
|---|---|
|
||||
| `nanobot onboard` | Initialize or refresh the default config and workspace |
|
||||
| `nanobot onboard --wizard` | Use the interactive setup wizard |
|
||||
| `nanobot onboard --config <path> --workspace <path>` | Initialize or refresh a specific instance |
|
||||
| `nanobot onboard` | Use the interactive setup wizard |
|
||||
| `nanobot onboard --defaults` | Initialize or refresh the default config and workspace without prompts |
|
||||
| `nanobot onboard --defaults --config <path> --workspace <path>` | Initialize or refresh a specific instance without prompts |
|
||||
|
||||
Without `--defaults`, `nanobot onboard` opens the wizard only when stdin and stdout are attached to a terminal. In scripts, CI, and Docker non-TTY runs, it falls back to the defaults setup.
|
||||
|
||||
Default paths:
|
||||
|
||||
|
||||
+1
-1
@@ -31,7 +31,7 @@ The default instance lives under `~/.nanobot/`:
|
||||
You can override both with command flags:
|
||||
|
||||
```bash
|
||||
nanobot onboard --config ./bot-a/config.json --workspace ./bot-a/workspace
|
||||
nanobot onboard --defaults --config ./bot-a/config.json --workspace ./bot-a/workspace
|
||||
nanobot agent --config ./bot-a/config.json --workspace ./bot-a/workspace -m "Hello"
|
||||
nanobot gateway --config ./bot-a/config.json --workspace ./bot-a/workspace
|
||||
```
|
||||
|
||||
@@ -11,7 +11,7 @@ The generated `config.json` uses camelCase keys such as `apiKey` and `intervalS`
|
||||
For setup and runtime failures, follow the diagnosis order in [`troubleshooting.md`](./troubleshooting.md) before changing multiple config areas at once.
|
||||
|
||||
> [!NOTE]
|
||||
> If your config file is older than the current schema, you can refresh it without overwriting your existing values: run `nanobot onboard`, then answer `N` when asked whether to overwrite the config. nanobot will merge in missing default fields and keep your current settings.
|
||||
> If your config file is older than the current schema, you can refresh it without overwriting your existing values: run `nanobot onboard --defaults`, then answer `N` when asked whether to overwrite the config. nanobot will merge in missing default fields and keep your current settings.
|
||||
|
||||
## Quick Jump
|
||||
|
||||
|
||||
+4
-4
@@ -59,9 +59,9 @@ Restart the deployed process after editing `config.json`. Long-running processes
|
||||
### Docker Compose
|
||||
|
||||
```bash
|
||||
docker compose run --rm nanobot-cli onboard # first-time setup
|
||||
vim ~/.nanobot/config.json # add API keys
|
||||
docker compose up -d nanobot-gateway # start gateway
|
||||
docker compose run --rm nanobot-cli onboard --defaults # first-time setup
|
||||
vim ~/.nanobot/config.json # add API keys
|
||||
docker compose up -d nanobot-gateway # start gateway
|
||||
```
|
||||
|
||||
```bash
|
||||
@@ -77,7 +77,7 @@ docker compose down # stop
|
||||
docker build -t nanobot .
|
||||
|
||||
# Initialize config (first time only)
|
||||
docker run -v ~/.nanobot:/home/nanobot/.nanobot --rm nanobot onboard
|
||||
docker run -v ~/.nanobot:/home/nanobot/.nanobot --rm nanobot onboard --defaults
|
||||
|
||||
# Edit config on host to add API keys
|
||||
vim ~/.nanobot/config.json
|
||||
|
||||
@@ -10,9 +10,9 @@ If you want each instance to have its own dedicated workspace from the start, pa
|
||||
|
||||
```bash
|
||||
# Create separate instance configs and workspaces
|
||||
nanobot onboard --config ~/.nanobot-telegram/config.json --workspace ~/.nanobot-telegram/workspace
|
||||
nanobot onboard --config ~/.nanobot-discord/config.json --workspace ~/.nanobot-discord/workspace
|
||||
nanobot onboard --config ~/.nanobot-feishu/config.json --workspace ~/.nanobot-feishu/workspace
|
||||
nanobot onboard --defaults --config ~/.nanobot-telegram/config.json --workspace ~/.nanobot-telegram/workspace
|
||||
nanobot onboard --defaults --config ~/.nanobot-discord/config.json --workspace ~/.nanobot-discord/workspace
|
||||
nanobot onboard --defaults --config ~/.nanobot-feishu/config.json --workspace ~/.nanobot-feishu/workspace
|
||||
```
|
||||
|
||||
**Configure each instance:**
|
||||
|
||||
+1
-1
@@ -25,7 +25,7 @@ tools:
|
||||
|
||||
To allow the agent to set its configuration (e.g. switch models, adjust parameters), set `tools.my.allow_set: true`.
|
||||
|
||||
Legacy `tools.myEnabled` / `tools.mySet` keys are auto-migrated on load, and rewritten in-place the next time `nanobot onboard` refreshes the config.
|
||||
Legacy `tools.myEnabled` / `tools.mySet` keys are auto-migrated on load, and rewritten in-place the next time `nanobot onboard --defaults` refreshes the config.
|
||||
|
||||
All modifications are held in memory only — restart restores defaults.
|
||||
|
||||
|
||||
@@ -25,7 +25,7 @@ Match the recipe to the credential or endpoint you already have:
|
||||
|
||||
## How to Use a Recipe
|
||||
|
||||
1. Install nanobot and run `nanobot onboard` or `nanobot onboard --wizard` once so `~/.nanobot/config.json` exists.
|
||||
1. Install nanobot and run `nanobot onboard` once so `~/.nanobot/config.json` exists. Use `nanobot onboard --defaults` if you prefer editing JSON by hand.
|
||||
2. Put secrets in environment variables when possible.
|
||||
3. Merge the recipe snippet into `~/.nanobot/config.json`.
|
||||
4. Run `nanobot status`.
|
||||
|
||||
+4
-4
@@ -32,7 +32,7 @@ On 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 you finish the wizard and save the config, skip the manual initialize/configure steps and go straight to [Check the Setup](#4-check-the-setup).
|
||||
The default command installs or upgrades `nanobot-ai` from PyPI, then starts `nanobot onboard`. It avoids system-wide pip installs by using an active virtual environment, `uv`, `pipx`, or a managed venv under `~/.nanobot/venv`. If you finish the wizard and save the config, skip the manual initialize/configure steps and go straight to [Check the Setup](#4-check-the-setup).
|
||||
|
||||
To preview the plan without changing your environment, pass `--dry-run`; combine it with `--dev` when you want to preview the main-branch install.
|
||||
|
||||
@@ -102,10 +102,10 @@ Skip this section if the one-command setup already started the wizard and you sa
|
||||
nanobot onboard
|
||||
```
|
||||
|
||||
Use the wizard if you prefer prompts instead of editing JSON by hand:
|
||||
Use the old non-interactive defaults path if you prefer editing JSON by hand:
|
||||
|
||||
```bash
|
||||
nanobot onboard --wizard
|
||||
nanobot onboard --defaults
|
||||
```
|
||||
|
||||
Initialization creates:
|
||||
@@ -115,7 +115,7 @@ Initialization creates:
|
||||
| `~/.nanobot/config.json` | Main settings file for providers, models, channels, tools, gateway, and API |
|
||||
| `~/.nanobot/workspace/` | Agent workspace for memory, sessions, heartbeat tasks, skills, and artifacts |
|
||||
|
||||
If you already have a config, `nanobot onboard` can refresh missing default fields without overwriting your existing values.
|
||||
If you already have a config, `nanobot onboard --defaults` can refresh missing default fields without overwriting your existing values.
|
||||
|
||||
## 3. Configure a Provider
|
||||
|
||||
|
||||
@@ -145,16 +145,16 @@ Use `python3 -m nanobot --version` or `py -m nanobot --version` if that is the P
|
||||
The one-command installer starts this for you after installation. If you installed manually, run:
|
||||
|
||||
```bash
|
||||
nanobot onboard --wizard
|
||||
nanobot onboard
|
||||
```
|
||||
|
||||
If `nanobot` is not found, run:
|
||||
|
||||
```bash
|
||||
python -m nanobot onboard --wizard
|
||||
python -m nanobot onboard
|
||||
```
|
||||
|
||||
Use `python3 -m nanobot onboard --wizard` or `py -m nanobot onboard --wizard` if that is the Python command that worked in step 2.
|
||||
Use `python3 -m nanobot onboard` or `py -m nanobot onboard` if that is the Python command that worked in step 2.
|
||||
|
||||
The wizard is a terminal menu. It is not a graphical app, but it lets you choose options instead of hand-editing every JSON field.
|
||||
|
||||
@@ -162,6 +162,7 @@ You will see a menu like this:
|
||||
|
||||
```text
|
||||
> What would you like to configure?
|
||||
[Q] Quick Start (recommended)
|
||||
[P] LLM Provider
|
||||
[M] Model Presets
|
||||
[C] Chat Channel
|
||||
@@ -184,27 +185,17 @@ Move through the wizard like this:
|
||||
| A field you do not need | Keep the shown default or leave it blank, then press `Enter`. |
|
||||
| A back option | Choose it to return to the previous menu. |
|
||||
|
||||
For the first setup, only configure the model provider and one model preset.
|
||||
For the first setup, choose `[Q] Quick Start (recommended)`. It asks for the model provider, API key, model ID, and optionally one chat channel. The other menu items are advanced settings.
|
||||
|
||||
If you are following the OpenRouter example:
|
||||
|
||||
1. Choose `[P] LLM Provider`.
|
||||
2. Select OpenRouter.
|
||||
3. Paste your OpenRouter API key.
|
||||
4. Keep the default `apiBase`, or leave it blank if the wizard shows no default. Only change it if OpenRouter or your deployment guide explicitly tells you to set one.
|
||||
5. Return to the main menu.
|
||||
6. Choose `[M] Model Presets`.
|
||||
7. Add or edit a preset named `primary`.
|
||||
8. Set:
|
||||
|
||||
```text
|
||||
label: Primary
|
||||
provider: openrouter
|
||||
model: anthropic/claude-sonnet-4.5
|
||||
maxTokens: 4096
|
||||
contextWindowTokens: 65536
|
||||
temperature: 0.1
|
||||
```
|
||||
1. Choose `[Q] Quick Start (recommended)`.
|
||||
2. Choose `WebUI only (recommended)` unless you already have a Telegram, Feishu/Lark, Slack, or Discord bot token ready.
|
||||
3. Select OpenRouter.
|
||||
4. Paste your OpenRouter API key.
|
||||
5. Enter a model ID, for example `anthropic/claude-sonnet-4.5`.
|
||||
6. Review the Quick Start summary.
|
||||
7. Choose `[S] Save and Exit`.
|
||||
|
||||
If OpenRouter says your account cannot use that model, use another OpenRouter model ID that your account can access.
|
||||
|
||||
@@ -215,9 +206,7 @@ If you are using another provider, use the same wizard choices but substitute th
|
||||
| Provider menu | The provider that owns your API key or endpoint. |
|
||||
| API key | The key from that provider, or leave it blank only if the provider does not use one. |
|
||||
| `apiBase` | Leave blank unless the provider docs, proxy docs, or local server docs give you a URL. |
|
||||
| Preset `provider` | The nanobot provider name, such as the one shown in [`provider-cookbook.md`](./provider-cookbook.md). |
|
||||
| Preset `model` | A model ID that provider can actually serve. |
|
||||
| Preset name | `primary` is fine for the first setup. |
|
||||
| Model ID | A model ID that provider can actually serve. |
|
||||
|
||||
Then choose `[S] Save and Exit`.
|
||||
|
||||
@@ -260,12 +249,14 @@ Merge them into one object:
|
||||
}
|
||||
```
|
||||
|
||||
Notice the comma after the `providers` block. JSON needs commas between sibling sections, but not after the last section. If this feels hard, use `nanobot onboard --wizard` whenever possible.
|
||||
Notice the comma after the `providers` block. JSON needs commas between sibling sections, but not after the last section. If this feels hard, use `nanobot onboard` whenever possible.
|
||||
|
||||
## 6. Manual Config Fallback
|
||||
|
||||
Use this only if the wizard is unavailable or you prefer opening the file yourself.
|
||||
|
||||
Run `nanobot onboard --defaults` first if `~/.nanobot/config.json` does not exist yet.
|
||||
|
||||
Use one of these commands:
|
||||
|
||||
**Windows PowerShell**
|
||||
|
||||
Reference in New Issue
Block a user