From a813343aa7bdb9f976c6e8e204411111b1d7a54f Mon Sep 17 00:00:00 2001 From: Peter Steinberger Date: Sat, 17 Jan 2026 17:16:20 +0000 Subject: [PATCH] docs: clarify model refs and runtime notes Co-authored-by: Yuri Chukhlib --- docs/channels/slack.md | 1 + docs/cli/doctor.md | 3 +++ docs/cli/gateway.md | 1 + docs/cli/models.md | 5 +++++ docs/concepts/agent.md | 8 ++++++++ docs/concepts/models.md | 3 +++ 6 files changed, 21 insertions(+) diff --git a/docs/channels/slack.md b/docs/channels/slack.md index aabe7ac6b..9f85b706b 100644 --- a/docs/channels/slack.md +++ b/docs/channels/slack.md @@ -335,6 +335,7 @@ For fine-grained control, use these tags in agent responses: - DMs share the `main` session (like WhatsApp/Telegram). - Channels map to `agent::slack:channel:` sessions. - Slash commands use `agent::slack:slash:` sessions (prefix configurable via `channels.slack.slashCommand.sessionPrefix`). +- If Slack doesn’t provide `channel_type`, Clawdbot infers it from the channel ID prefix (`D`, `C`, `G`) and defaults to `channel` to keep session keys stable. - Native command registration uses `commands.native` (global default `"auto"` → Slack off) and can be overridden per-workspace with `channels.slack.commands.native`. Text commands require standalone `/...` messages and can be disabled with `commands.text: false`. Slack slash commands are managed in the Slack app and are not removed automatically. Use `commands.useAccessGroups: false` to bypass access-group checks for commands. - Full command list + config: [Slash commands](/tools/slash-commands) diff --git a/docs/cli/doctor.md b/docs/cli/doctor.md index 51fef8d22..0f91b60bf 100644 --- a/docs/cli/doctor.md +++ b/docs/cli/doctor.md @@ -21,6 +21,9 @@ clawdbot doctor --repair clawdbot doctor --deep ``` +Notes: +- Interactive prompts (like keychain/OAuth fixes) only run when stdin is a TTY and `--non-interactive` is **not** set. Headless runs (cron, Telegram, no terminal) will skip prompts. + ## macOS: `launchctl` env overrides If you previously ran `launchctl setenv CLAWDBOT_GATEWAY_TOKEN ...` (or `...PASSWORD`), that value overrides your config file and can cause persistent “unauthorized” errors. diff --git a/docs/cli/gateway.md b/docs/cli/gateway.md index 5971491e7..c5627c854 100644 --- a/docs/cli/gateway.md +++ b/docs/cli/gateway.md @@ -29,6 +29,7 @@ Notes: - By default, the Gateway refuses to start unless `gateway.mode=local` is set in `~/.clawdbot/clawdbot.json`. Use `--allow-unconfigured` for ad-hoc/dev runs. - Binding beyond loopback without auth is blocked (safety guardrail). - `SIGUSR1` triggers an in-process restart (useful without a supervisor). +- `SIGINT`/`SIGTERM` handlers stop the gateway process, but they don’t restore any custom terminal state. If you wrap the CLI with a TUI or raw-mode input, restore the terminal before exit. ### Options diff --git a/docs/cli/models.md b/docs/cli/models.md index ab36c91ed..f394a44f9 100644 --- a/docs/cli/models.md +++ b/docs/cli/models.md @@ -26,6 +26,11 @@ clawdbot models scan When provider usage snapshots are available, the OAuth/token status section includes provider usage headers. +Notes: +- `models set ` accepts `provider/model` or an alias. +- Model refs are parsed by splitting on the **first** `/`. If the model ID includes `/` (OpenRouter-style), include the provider prefix (example: `openrouter/moonshotai/kimi-k2`). +- If you omit the provider, Clawdbot treats the input as an alias or a model for the **default provider** (only works when there is no `/` in the model ID). + ## Aliases + fallbacks ```bash diff --git a/docs/concepts/agent.md b/docs/concepts/agent.md index f68aa1bf9..7f8c4d306 100644 --- a/docs/concepts/agent.md +++ b/docs/concepts/agent.md @@ -98,6 +98,14 @@ Verbose tool summaries are emitted at tool start (no debounce); Control UI streams tool output via agent events when available. More details: [Streaming + chunking](/concepts/streaming). +## Model refs + +Model refs in config (for example `agents.defaults.model` and `agents.defaults.models`) are parsed by splitting on the **first** `/`. + +- Use `provider/model` when configuring models. +- If the model ID itself contains `/` (OpenRouter-style), include the provider prefix (example: `openrouter/moonshotai/kimi-k2`). +- If you omit the provider, Clawdbot treats the input as an alias or a model for the **default provider** (only works when there is no `/` in the model ID). + ## Configuration (minimal) At minimum, set: diff --git a/docs/concepts/models.md b/docs/concepts/models.md index 0e8f1cb66..2b8bde126 100644 --- a/docs/concepts/models.md +++ b/docs/concepts/models.md @@ -102,6 +102,9 @@ Notes: - `/model` (and `/model list`) is a compact, numbered picker (model family + available providers). - `/model <#>` selects from that picker. - `/model status` is the detailed view (auth candidates and, when configured, provider endpoint `baseUrl` + `api` mode). +- Model refs are parsed by splitting on the **first** `/`. Use `provider/model` when typing `/model `. +- If the model ID itself contains `/` (OpenRouter-style), you must include the provider prefix (example: `/model openrouter/moonshotai/kimi-k2`). +- If you omit the provider, Clawdbot treats the input as an alias or a model for the **default provider** (only works when there is no `/` in the model ID). Full command behavior/config: [Slash commands](/tools/slash-commands).