py-xiaozhi Documentation Directory
This directory contains all documentation for the py-xiaozhi project, organized by functional modules for easy reference.
All MCP tools have been fully ported, including Bazi fortune-telling, marriage compatibility, system utilities, online music, and vision (official Xiaozhi vision, Zhipu, and Alibaba models). Other modules can be extended and enabled as needed.
The project now uses the v2 authorization protocol. WSS connections are returned via the OTA API, and both official Xiaozhi and open-source backends have aligned their authentication flows.
Role definition: prioritize external extension tools (MCP/IoT) — do not skip execution. This prevents the AI from ignoring MCP or IoT calls, though there is still a chance of triggering built-in tools with similar functionality, in which case a prompt may help.
Basic Docs
- System Dependencies - Platform-specific system dependencies and Python environment setup
- Configuration Guide - Config file structure, options, and modification guide
- Voice Interaction Modes - Project overview, basic usage, and run modes
- Wake Word - Wake word feature configuration and usage
- Device Activation - Device activation and registration flow
- Packaging Guide - Detailed guide for packaging with UnifyPy
Development Docs
- Development Guide - Secondary development guide covering plugin development, MCP tool development, UI page development, and more
Other Docs
- Troubleshooting - Common issues and solutions
Legacy Docs
For reference, we maintain the older documentation:
- Legacy Usage Guide - Earlier version usage documentation
Contributing
To contribute to the project or provide feedback, see:
- Contributing Guide - English contributing guide covering development workflow, PR requirements, and maintainer workflow
- 贡献指南 - Chinese contributing guide
- Team - Thanks to all contributors
- Sponsors - How to sponsor the project
Ecosystem
- Ecosystem - Related ecosystem and extension projects
Version Info
Documentation last updated: January 2026