Frequently Asked Questions

If you’re behind the GFW (China), use the mirror-accelerated installer:

curl -fsSL https://ghfast.top/https://raw.githubusercontent.com/ai-pivot/xbot/master/scripts/install-cn.sh | bash

You can also set GH_MIRROR=gh-proxy.com or GH_MIRROR=ghfast.top manually.

• Standalone: solo developer, quick test drive. CLI only, stops when you close the terminal.
• Server: teams, multi-channel (Feishu/QQ/Web), shared LLM, always-on. Most teams should choose Server mode.

git clone https://github.com/ai-pivot/xbot.git && cd xbot
make build

Requires Go 1.26+. The Web UI bundles are committed, so Node.js is not needed for Go builds.

Set provider: "openai" and change the base_url:

{
  "subscriptions": [
    {
      "name": "DeepSeek",
      "provider": "openai",
      "api_key": "your-key",
      "base_url": "https://api.deepseek.com/v1",
      "model": "deepseek-chat"
    }
  ]
}

Yes. Create multiple subscriptions in config.json (or via /setup), then switch between them with Ctrl+P or /models. In Server mode, the admin creates subscriptions once and the whole team shares them.

Model tiers let SubAgents use different models for different complexity levels. Configure via /settings:

• Vanguard — strongest reasoning (complex tasks)
• Balance — balanced (general work)
• Swift — fast/small (quick lookups)

Unconfigured tiers fall back: vanguard → balance → swift.

The model list loads asynchronously from the provider. If your provider’s /models endpoint is slow or blocked, you can type the model name manually. Use /setup → select the subscription → enter the model name.

1. Create an app on the Feishu Open Platform
2. Enable the bot capability and event subscriptions
3. Add the required permissions (im:message, im:message.receive_v1, im:message:send_as_bot, contact:user.base:readonly)
4. Add credentials to ~/.xbot/config.json:

{
  "feishu": {
    "enabled": true,
    "app_id": "cli_xxx",
    "app_secret": "xxx"
  }
}

See the Feishu channel guide for details.

Yes. Use the allow_from field to whitelist user IDs:

{
  "feishu": {
    "enabled": true,
    "app_id": "cli_xxx",
    "app_secret": "xxx",
    "allow_from": ["ou_xxx", "ou_yyy"]
  }
}

This works for all channels (Feishu, QQ, NapCat).

• Use /compress regularly to keep context small
• Switch to a faster model for simple tasks (Ctrl+L)
• Use SubAgents for parallel work (each has its own context)
• Increase max_concurrency for parallel tool execution
• Use background mode for long-running commands

Open the sidebar (it’s always visible by default). Click any session to switch. Or use /sessions to list, /su to switch, /new to create.

• Complex reasoning (architecture, debugging): GPT-4o, Claude Sonnet/Opus
• General work (writing, editing): GPT-4o-mini, Claude Haiku, DeepSeek
• Quick lookups (simple Q&A): Any fast model works
• Budget-conscious: DeepSeek, Qwen, or local models via Ollama

Switch models per-session with Ctrl+L, or globally with Ctrl+N.

Ctrl+K → Theme, or type /palette theme. You can also create custom themes — see the ai-config skill.

Type /context to see current prompt token usage and context bar. Use /clear to reset the conversation, or /compress to manually compress.

If the agent runs untrusted commands or works in a shared environment, yes. Docker sandboxing isolates shell execution. For personal development, mode: "none" (the default) is fine.

See the Sandbox guide for Docker setup.

• Use allow_from to restrict who can talk to the agent
• Enable Docker sandboxing on shared servers
• Use permission control for privileged operations
• Keep API keys in subscriptions (never in environment variables for production)
• Regularly review /context to monitor what the agent is doing

Make sure the server is running: xbot-cli serve. Check that ~/.xbot/config.json has the correct cli.server_url and cli.token matching the server’s admin.token.

The agent discovers MCP tools dynamically. Use the ManageTools tool to list and manage MCP servers. MCP servers connect via stdio or HTTP — check that the executable path is correct and accessible from the xbot process PATH.

SubAgents run in their own context. If a SubAgent is stuck, you can interrupt it with Ctrl+C, or check its progress via the SubAgent panel (Ctrl+T).

The agent’s working directory is set via the work_dir config or inherited from where you launch xbot-cli. The agent can use the Cd tool to navigate. If files are outside the expected directory, tell the agent the full path.

Use /compress to summarize old messages and free up context space. For a fresh start, use /clear. Check token usage with /context. For long sessions, consider using SubAgents to delegate work — they have their own context windows.

Ask the agent: “Export this conversation as Markdown” — it will use the FileCreate tool to write the conversation to a file. You can also use /rewind to go back to a specific point in the conversation.

xbot is fully self-hosted — all data stays on your server. Conversations are stored in local SQLite databases. API keys are in your config file, never sent to third parties. No telemetry or analytics are collected.

If the agent gets stuck in a loop, use Ctrl+C to interrupt, then /clear to reset the conversation. You can also use context_edit to remove specific messages that might be causing the loop.

All xbot data is in ~/.xbot/:

• config.json — configuration
• *.db — SQLite databases (conversations, sessions, users)
• skills/, agents/ — custom skills and agent roles

# Backup everything
cp -r ~/.xbot ~/.xbot-backup-$(date +%Y%m%d)

# Restore
cp -r ~/.xbot-backup-YYYYMMDD/* ~/.xbot/

Note

Need more help? Check the full documentation or open an issue on GitHub.