208 lines
4.9 KiB
Markdown
208 lines
4.9 KiB
Markdown
# @ynhcj/xiaoyichannel
|
|
|
|
XiaoYi channel plugin for OpenClaw with A2A protocol support.
|
|
|
|
## Features
|
|
|
|
- WebSocket-based connection to XiaoYi servers
|
|
- AK/SK authentication mechanism
|
|
- A2A (Agent-to-Agent) message protocol support
|
|
- Automatic reconnection with exponential backoff
|
|
- Heartbeat mechanism for connection health monitoring
|
|
- Full integration with OpenClaw's message routing and session management
|
|
|
|
## Installation
|
|
|
|
Install the plugin in your OpenClaw project:
|
|
|
|
```bash
|
|
openclaw plugins install @ynhcj/xiaoyichannel@1.0.0
|
|
```
|
|
|
|
## Configuration
|
|
|
|
After installation, add the XiaoYi channel configuration to your `openclaw.json` (or `.openclawd.json`):
|
|
|
|
```json
|
|
{
|
|
"channels": {
|
|
"xiaoyi": {
|
|
"enabled": true,
|
|
"accounts": {
|
|
"default": {
|
|
"enabled": true,
|
|
"wsUrl": "wss://hag.com/ws/link",
|
|
"ak": "your-access-key",
|
|
"sk": "your-secret-key",
|
|
"agentId": "your-agent-id"
|
|
}
|
|
}
|
|
}
|
|
},
|
|
"agents": {
|
|
"bindings": [
|
|
{
|
|
"agentId": "main",
|
|
"match": {
|
|
"channel": "xiaoyi",
|
|
"accountId": "default"
|
|
}
|
|
}
|
|
]
|
|
}
|
|
}
|
|
```
|
|
|
|
### Configuration Parameters
|
|
|
|
- `wsUrl`: WebSocket server URL (e.g., `wss://hag.com/ws/link`)
|
|
- `ak`: Access Key for authentication
|
|
- `sk`: Secret Key for authentication
|
|
- `agentId`: Your agent identifier
|
|
|
|
### Multiple Accounts
|
|
|
|
You can configure multiple XiaoYi accounts:
|
|
|
|
```json
|
|
{
|
|
"channels": {
|
|
"xiaoyi": {
|
|
"enabled": true,
|
|
"accounts": {
|
|
"account1": {
|
|
"enabled": true,
|
|
"wsUrl": "wss://hag.com/ws/link",
|
|
"ak": "ak1",
|
|
"sk": "sk1",
|
|
"agentId": "agent1"
|
|
},
|
|
"account2": {
|
|
"enabled": true,
|
|
"wsUrl": "wss://hag.com/ws/link",
|
|
"ak": "ak2",
|
|
"sk": "sk2",
|
|
"agentId": "agent2"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
## A2A Protocol
|
|
|
|
This plugin implements the A2A (Agent-to-Agent) message protocol as specified in the [Huawei Message Stream documentation](https://developer.huawei.com/consumer/cn/doc/service/message-stream-0000002505761434).
|
|
|
|
### Message Structure
|
|
|
|
**Incoming Request Message:**
|
|
```json
|
|
{
|
|
"sessionId": "session-123",
|
|
"messageId": "msg-456",
|
|
"timestamp": 1234567890,
|
|
"sender": {
|
|
"id": "user-id",
|
|
"name": "User Name",
|
|
"type": "user"
|
|
},
|
|
"content": {
|
|
"type": "text",
|
|
"text": "Hello, agent!"
|
|
}
|
|
}
|
|
```
|
|
|
|
**Outgoing Response Message:**
|
|
```json
|
|
{
|
|
"sessionId": "session-123",
|
|
"messageId": "msg-789",
|
|
"timestamp": 1234567891,
|
|
"agentId": "your-agent-id",
|
|
"sender": {
|
|
"id": "your-agent-id",
|
|
"name": "OpenClaw Agent",
|
|
"type": "agent"
|
|
},
|
|
"content": {
|
|
"type": "text",
|
|
"text": "Hello! How can I help you?"
|
|
},
|
|
"status": "success"
|
|
}
|
|
```
|
|
|
|
## Authentication
|
|
|
|
The plugin uses AK/SK authentication as specified in the [Huawei Push Message documentation](https://developer.huawei.com/consumer/cn/doc/service/pushmessage-0000002505761436).
|
|
|
|
The authentication signature is generated using HMAC-SHA256:
|
|
|
|
```
|
|
signature = HMAC-SHA256(SK, "ak={AK}×tamp={TIMESTAMP}")
|
|
```
|
|
|
|
## Connection Management
|
|
|
|
The plugin automatically manages WebSocket connections with the following features:
|
|
|
|
- **Automatic Reconnection**: Reconnects automatically on connection loss with exponential backoff
|
|
- **Heartbeat Monitoring**: Sends ping messages every 30 seconds to keep the connection alive
|
|
- **Connection Health**: Monitors connection status and reports health via OpenClaw's status system
|
|
- **Max Retry Limit**: Stops reconnection attempts after 10 failed attempts
|
|
|
|
## Session Management
|
|
|
|
The plugin integrates with OpenClaw's session management system:
|
|
|
|
- Sessions are scoped by `sessionId` from incoming A2A messages
|
|
- Each conversation maintains its own session context
|
|
- Session keys are automatically generated based on OpenClaw's configuration
|
|
|
|
## Usage
|
|
|
|
Once configured, the plugin will:
|
|
|
|
1. Automatically connect to the XiaoYi WebSocket server on startup
|
|
2. Authenticate using the provided AK/SK credentials
|
|
3. Receive incoming messages via WebSocket
|
|
4. Route messages to the appropriate OpenClaw agent
|
|
5. Send agent responses back through the WebSocket connection
|
|
|
|
## Troubleshooting
|
|
|
|
### Connection Issues
|
|
|
|
Check the OpenClaw logs for connection status:
|
|
|
|
```bash
|
|
openclaw logs
|
|
```
|
|
|
|
### Authentication Failures
|
|
|
|
Verify your AK/SK credentials are correct and have the necessary permissions.
|
|
|
|
### Message Delivery
|
|
|
|
Ensure your `agentId` is correctly configured and matches your XiaoYi account settings.
|
|
|
|
## Development
|
|
|
|
To build the plugin from source:
|
|
|
|
```bash
|
|
npm install
|
|
npm run build
|
|
```
|
|
|
|
## License
|
|
|
|
MIT
|
|
|
|
## Support
|
|
|
|
For issues and questions, please visit the [GitHub repository](https://github.com/ynhcj/xiaoyichannel).
|