opencode/picoclaw
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

docs: add configuration guide for CLI providers and multi-bot Telegram

Browse source 
- Add PR #1633 (gemini-cli provider) to contributions table
- Add configuration guide section covering:
  - claude-cli, codex-cli, and gemini-cli providers with model_list examples
  - Multiple Telegram bots with bindings and per-agent config
  - Agent workspace and personality file notes

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
Eric Jacksch 2026-03-16 01:27:29 -04:00
parent 64b5b37b53
commit 2ac7864dc1
1 changed files with 125 additions and 0 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

125
README.md
View file

@ -12,6 +12,131 @@ The main project is maintained at [sipeed/picoclaw](https://github.com/sipeed/pi
| [#1479](https://github.com/sipeed/picoclaw/pull/1479) | fix(claude_cli): surface stdout in error when CLI exits non-zero | Open |
| [#1480](https://github.com/sipeed/picoclaw/pull/1480) | docs: document claude-cli and codex-cli providers in README | Open |
| [#1625](https://github.com/sipeed/picoclaw/pull/1625) | feat(channels): support multiple named Telegram bots | Open |
| [#1633](https://github.com/sipeed/picoclaw/pull/1633) | feat(providers): add gemini-cli provider | Open |
---
## Configuration Guide
Features in this fork that may not yet be merged upstream.
### CLI-based LLM Providers
PicoClaw supports three CLI-based providers that invoke local AI CLI tools as subprocesses.
All three read the prompt from stdin and return the response on stdout.
Add entries to `model_list` in your config:
```json
"model_list": [
{
"model_name": "claude-cli",
"model": "claude-cli/claude-code",
"request_timeout": 1200
},
{
"model_name": "codex-cli",
"model": "codex-cli/codex-cli",
"request_timeout": 1200
},
{
"model_name": "gemini-cli",
"model": "gemini-cli/gemini-2.5-pro",
"request_timeout": 1200
}
]
```
The model ID after the `/` is passed as `--model` to the CLI. Sentinel values (`claude-code`, `codex-cli`, `gemini-cli`) skip the `--model` flag and let the CLI use its own default model.
| Provider | Protocol prefix | Sentinel | CLI invoked |
|----------|----------------|----------|-------------|
| Claude Code | `claude-cli/` | `claude-code` | `claude -p --output-format json --dangerously-skip-permissions --no-chrome` |
| OpenAI Codex | `codex-cli/` | `codex-cli` | `codex exec --json --dangerously-bypass-approvals-and-sandbox` |
| Gemini CLI | `gemini-cli/` | `gemini-cli` | `gemini --yolo --output-format json --prompt ""` |
**Prerequisites:** Each CLI must be installed and authenticated with `claude`, `codex`, or `gemini` available in PATH.
---
### Multiple Telegram Bots
Run multiple Telegram bots from a single picoclaw instance, each connected to a separate AI agent. Each bot entry in `telegram_bots` creates a channel named `telegram-<id>`. Use `bindings` to route each channel to its agent.
#### Config
```json
"channels": {
"telegram_bots": [
{
"id": "amber",
"enabled": true,
"token": "AMBER_BOT_TOKEN",
"allow_from": ["YOUR_TELEGRAM_USER_ID"],
"typing": { "enabled": true },
"placeholder": { "enabled": true, "text": "Thinking... 💭" }
},
{
"id": "karen",
"enabled": true,
"token": "KAREN_BOT_TOKEN",
"allow_from": ["YOUR_TELEGRAM_USER_ID"],
"typing": { "enabled": true },
"placeholder": { "enabled": true, "text": "Thinking... 💭" }
}
]
},
"bindings": [
{
"agent_id": "amber",
"match": { "channel": "telegram-amber" }
},
{
"agent_id": "karen",
"match": { "channel": "telegram-karen" }
}
]
```
#### Agents
Define each agent in `agents.list` with its own workspace, model, and personality files:
```json
"agents": {
"list": [
{
"id": "amber",
"name": "Amber",
"default": true,
"workspace": "~/.picoclaw/agents/amber",
"model": {
"primary": "claude-cli",
"fallbacks": ["gemini-cli"]
},
"subagents": {
"allow_agents": ["karen"]
}
},
{
"id": "karen",
"name": "Karen",
"default": false,
"workspace": "~/.picoclaw/agents/karen",
"model": {
"primary": "claude-cli",
"fallbacks": ["gemini-cli"]
}
}
]
}
```
Each agent's workspace can contain `IDENTITY.md` and `AGENTS.md` files to define personality and behaviour. Picoclaw creates the workspace directories automatically on first run.
**Note:** The legacy single-bot `channels.telegram` config is still supported and is automatically normalized to a `telegram-default` channel for backward compatibility.
---
## Legal