cc-connect/docs/wps-xiezuo.md

WPS Xiezuo Platform Setup Guide

This guide explains how to connect cc-connect to WPS Xiezuo (WPS 365 collaboration) so users can talk to an AI coding agent from WPS chats.

Prerequisites

• A WPS Open Platform application with app chat events enabled
• app_id and app_secret for the application
• A machine running cc-connect; no public IP is required
• An agent such as Claude Code, Codex, or Gemini CLI configured in cc-connect

Connection Model

The platform uses WPS event WebSocket delivery and WPS REST APIs:

• Incoming events: WebSocket at wss://openapi.wps.cn/v7/event/ws
• Authentication: KSO-1 HMAC-SHA256 headers
• Event payloads: encrypted with AES-256-CBC and verified with HMAC-SHA256 signatures
• Outgoing replies: REST API with a cached client_credentials access token

cc-connect sends ACK frames on the WebSocket writer loop, so no public callback URL is needed.

Configure WPS

In the WPS Open Platform console:

1. Create or select an application.
2. Enable app chat/message capabilities for the application.
3. Enable event WebSocket delivery.
4. Subscribe to message events:
   • kso.app_chat.message
   • kso.app_chat.message.recall if recall notifications are needed
5. Grant the permissions needed to send app chat messages and reactions.
6. Copy the application app_id and app_secret.

The exact console names may vary by WPS tenant and app type. If the connection fails with authorization errors, verify that the app is published/enabled for the target organization and has the required app chat permissions.

Configure cc-connect

Add wps-xiezuo to a project in config.toml:

[[projects]]
name = "my-project"

[projects.agent]
type = "claudecode"

[projects.agent.options]
work_dir = "/path/to/your/project"

[[projects.platforms]]
type = "wps-xiezuo"

[projects.platforms.options]
app_id = "your-wps-xiezuo-app-id"
app_secret = "your-wps-xiezuo-app-secret"
allow_from = "*"        # optional; set to WPS user IDs in production
clean_reply = false     # optional; strip thinking/tool progress lines

Options

Option	Required	Default	Description
app_id	yes	-	WPS Open Platform application ID
app_secret	yes	-	WPS Open Platform application secret
allow_from	no	all users	Comma-separated WPS user IDs allowed to use the bot; set this in production
clean_reply	no	false	Removes common thinking/tool progress lines from replies before sending
base_url	no	https://openapi.wps.cn	Override WPS REST API base URL for private or test environments

Start and Verify

Start cc-connect:

cc-connect -config /path/to/config.toml

Expected logs include:

level=INFO msg="wps-xiezuo: connecting" endpoint=wss://openapi.wps.cn/v7/event/ws
level=INFO msg="wps-xiezuo: connected"
level=INFO msg="platform started" project=my-project platform=wps-xiezuo

Send a message to the WPS app chat. cc-connect should receive the encrypted event, ACK it, forward the text to the configured agent, and send the reply back through the WPS message API.

Security Notes

• Always set allow_from for production deployments.
• Keep app_secret out of source control. Environment variable substitution is supported in config.toml, for example app_secret = "${WPS_XIEZUO_APP_SECRET}".
• Debug logs avoid printing decrypted WPS message payloads by default.

Troubleshooting

Connection fails immediately

• Confirm app_id and app_secret are correct.
• Confirm the app has WebSocket event delivery enabled.
• Confirm the app is available to the organization where you are testing.

Messages arrive but replies fail

• Confirm the app has message send permissions.
• Check whether the tenant requires the /oauth2/token or /openapi/oauth2/token token endpoint; cc-connect tries both.
• Verify the target chat allows app messages.

Bot responds to unexpected users

• Set allow_from to a comma-separated list of WPS user IDs.
• Users can send /whoami to discover the ID used by cc-connect.