Grayscale/nanobot
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: update serve api key requirement

Browse Source 
maintainer edit: Align OpenAI-compatible API docs and examples with the new fail-closed api.api_key requirement while keeping /health documented as unauthenticated.
This commit is contained in:
chengyongru
2026-07-08 12:16:12 +08:00
committed by Xubin Ren
parent 460c62c0b0
commit 28141ce20b
4 changed files with 22 additions and 12 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/openai-api.md
+18 -10
View File
@@ -5,33 +5,32 @@ nanobot can expose a minimal OpenAI-compatible endpoint for local integrations:
```bash
nanobot plugins enable api
nanobot agent -m "Hello!"
# Set api.apiKey first; see Authentication below.
nanobot serve
```
Run the CLI check first. If `nanobot agent -m "Hello!"` fails, fix provider or config setup before debugging the API server. By default, the API binds to `127.0.0.1:8900`. You can change this in `config.json`.
Run the CLI check first. If `nanobot agent -m "Hello!"` fails, fix provider or config setup before debugging the API server. By default, the API binds to `127.0.0.1:8900`. You can change this in `config.json`. `nanobot serve` requires `api.apiKey`; set it before starting the server.
For setup help, see [`quick-start.md`](./quick-start.md), [`providers.md`](./providers.md), and [`troubleshooting.md`](./troubleshooting.md).
## Authentication
Local-only `127.0.0.1` usage does not require an API key. If you bind the API
server to all interfaces with `api.host: "0.0.0.0"` or `"::"`, nanobot requires
`api.apiKey`; otherwise startup fails to avoid exposing an unauthenticated agent
endpoint on the network.
`nanobot serve` requires `api.apiKey` for all API binds. Without it, startup
fails before the agent is initialized. Keep the key secret and send it as a
Bearer token on API routes.
```json
{
"api": {
"host": "0.0.0.0",
"host": "127.0.0.1",
"port": 8900,
"apiKey": "${NANOBOT_API_KEY}"
}
}
```
When `api.apiKey` is set, send it as a Bearer token on API routes. The health
endpoint remains unauthenticated so local probes and load balancers can still
check process health.
The health endpoint remains unauthenticated so local probes and load balancers
can still check process health.
```bash
curl http://127.0.0.1:8900/v1/models \
@@ -70,6 +69,7 @@ If `channel` points to a channel that is not enabled in your config, nanobot wil
```bash
curl http://127.0.0.1:8900/v1/chat/completions \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $NANOBOT_API_KEY" \
-d '{
"messages": [{"role": "user", "content": "hi"}],
"session_id": "my-session"
@@ -83,6 +83,7 @@ Send images inline using the OpenAI multimodal content format:
```bash
curl http://127.0.0.1:8900/v1/chat/completions \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $NANOBOT_API_KEY" \
-d '{
"messages": [{"role": "user", "content": [
{"type": "text", "text": "Describe this image"},
@@ -98,11 +99,13 @@ Upload any supported file type (images, PDF, Word, Excel, PPT) via multipart:
```bash
# Single file
curl http://127.0.0.1:8900/v1/chat/completions \
-H "Authorization: Bearer $NANOBOT_API_KEY" \
-F "message=Summarize this report" \
-F "files=@report.docx"
# Multiple files with session isolation
curl http://127.0.0.1:8900/v1/chat/completions \
-H "Authorization: Bearer $NANOBOT_API_KEY" \
-F "message=Compare these files" \
-F "files=@chart.png" \
-F "files=@data.xlsx" \
@@ -117,10 +120,13 @@ Supported file types:
## Python (`requests`)
```python
import os
import requests
resp = requests.post(
"http://127.0.0.1:8900/v1/chat/completions",
headers={"Authorization": f"Bearer {os.environ['NANOBOT_API_KEY']}"},
json={
"messages": [{"role": "user", "content": "hi"}],
"session_id": "my-session", # optional: isolate conversation
@@ -134,11 +140,13 @@ print(resp.json()["choices"][0]["message"]["content"])
## Python (`openai`)
```python
import os
from openai import OpenAI
client = OpenAI(
base_url="http://127.0.0.1:8900/v1",
api_key="dummy",
api_key=os.environ["NANOBOT_API_KEY"],
)
resp = client.chat.completions.create(