Channel configuration reference
This page documents how TypeScript channels are registered in Desktop-managed and standalone deployments, and the fields and defaults of every adapter config file.
Registration modes
Desktop-managed built-in modules
Use this shape when DotCraft owns the bundled module process:
{
"ExternalChannels": {
"qq": {
"enabled": true,
"transport": "managedWebsocket",
"builtinModule": "channel-qq"
}
}
}Desktop writes this registration for bundled modules and injects the AppServer endpoint into the adapter config at runtime.
Standalone adapters
Use this shape when you run the adapter process yourself:
{
"AppServer": {
"Mode": "WebSocket",
"WebSocket": {
"Host": "127.0.0.1",
"Port": 9100,
"Token": ""
}
},
"ExternalChannels": {
"qq": {
"enabled": true,
"transport": "websocket"
}
}
}Standalone adapters read dotcraft.wsUrl and dotcraft.token from their adapter config file.
Built-in module names
| Channel | Built-in module | Adapter config |
|---|---|---|
channel-qq | .craft/qq.json | |
| WeCom | channel-wecom | .craft/wecom.json |
| Feishu / Lark | channel-feishu | .craft/feishu.json |
| Telegram | channel-telegram | .craft/telegram.json |
| Weixin | channel-weixin | .craft/weixin.json |
Adapter config files
Every TypeScript channel config has a dotcraft section and a platform section. Desktop hides dotcraft.* fields in the UI and supplies them automatically for managed modules.
QQ
{
"dotcraft": {
"wsUrl": "ws://127.0.0.1:9100/ws",
"token": ""
},
"qq": {
"host": "127.0.0.1",
"port": 6700,
"accessToken": "",
"adminUsers": [123456789],
"whitelistedUsers": [],
"whitelistedGroups": [],
"approvalTimeoutMs": 60000,
"requireMentionInGroups": true
}
}| Field | Description | Default |
|---|---|---|
dotcraft.wsUrl | AppServer WebSocket endpoint for standalone adapters. Desktop-managed runtime overrides this value. | ws://127.0.0.1:9100/ws |
dotcraft.token | AppServer WebSocket token for standalone adapters. Desktop-managed runtime overrides this value. | Empty |
qq.host | OneBot reverse WebSocket listen host. | 127.0.0.1 |
qq.port | OneBot reverse WebSocket listen port. | 6700 |
qq.accessToken | Optional OneBot access token. Must match NapCat when set. | Empty |
qq.adminUsers | QQ user IDs with admin permission. | [] |
qq.whitelistedUsers | QQ user IDs allowed to chat with DotCraft. | [] |
qq.whitelistedGroups | QQ group IDs whose members may chat with DotCraft. | [] |
qq.approvalTimeoutMs | Approval timeout in milliseconds. | 60000 |
qq.requireMentionInGroups | Require @mention in QQ groups. | true |
WeCom
{
"dotcraft": {
"wsUrl": "ws://127.0.0.1:9100/ws",
"token": ""
},
"wecom": {
"host": "0.0.0.0",
"port": 9000,
"scheme": "http",
"robots": [
{
"path": "/dotcraft",
"token": "wecom-token",
"aesKey": "wecom-encoding-aes-key"
}
],
"adminUsers": ["zhangsan"],
"whitelistedUsers": [],
"whitelistedChats": [],
"approvalTimeoutMs": 60000
}
}| Field | Description | Default |
|---|---|---|
dotcraft.wsUrl | AppServer WebSocket endpoint for standalone adapters. Desktop-managed runtime overrides this value. | ws://127.0.0.1:9100/ws |
dotcraft.token | AppServer WebSocket token for standalone adapters. Desktop-managed runtime overrides this value. | Empty |
wecom.host | Callback server listen host. | 0.0.0.0 |
wecom.port | Callback server listen port. | 9000 |
wecom.scheme | Callback server scheme. Use https only when TLS cert and key paths are configured. | http |
wecom.tls.certPath | TLS certificate path for direct HTTPS callback serving. | Empty |
wecom.tls.keyPath | TLS private key path for direct HTTPS callback serving. | Empty |
wecom.robots | Robot callback credentials: path, token, and aesKey. | [] |
wecom.defaultRobot | Default Token and EncodingAESKey used when a robot-specific entry omits them. | Empty |
wecom.adminUsers | WeCom UserIds with admin permission. | [] |
wecom.whitelistedUsers | WeCom UserIds allowed to chat with DotCraft. | [] |
wecom.whitelistedChats | WeCom ChatIds allowed to chat with DotCraft. | [] |
wecom.approvalTimeoutMs | Approval timeout in milliseconds. | 60000 |
Feishu
{
"dotcraft": {
"wsUrl": "ws://127.0.0.1:9100/ws",
"token": ""
},
"feishu": {
"appId": "cli_your_app_id",
"appSecret": "your_app_secret",
"brand": "feishu",
"cardTitle": "DotCraft",
"approvalTimeoutMs": 120000,
"groupMentionRequired": true,
"ackReactionEmoji": "GLANCE",
"streaming": {
"enabled": true
},
"cli": {
"enabled": false
}
}
}| Field | Description | Default |
|---|---|---|
dotcraft.wsUrl | AppServer WebSocket endpoint for standalone adapters. Desktop-managed runtime overrides this value. | ws://127.0.0.1:9100/ws |
dotcraft.token | AppServer WebSocket token for standalone adapters. Desktop-managed runtime overrides this value. | Empty |
feishu.appId | Feishu / Lark app ID. | Required |
feishu.appSecret | Feishu / Lark app secret. | Required |
feishu.verificationToken | Optional verification token for event payloads that require it. | Empty |
feishu.encryptKey | Optional encrypt key for encrypted event payloads. | Empty |
feishu.brand | Service environment: feishu or lark. | feishu |
feishu.cardTitle | Title shown on reply, progress, and approval cards. | DotCraft |
feishu.approvalTimeoutMs | Approval timeout in milliseconds. | 120000 |
feishu.groupMentionRequired | Require @mention in Feishu groups. | true |
feishu.ackReactionEmoji | Emoji type used to acknowledge handled messages. | GLANCE |
feishu.downloadDir | Local directory for downloaded attachments. | Workspace temp directory |
feishu.cli.enabled | Expose the bundled official Feishu CLI to Threads created by this Channel. | false |
feishu.cli.userScopes | Feishu user scopes requested when authorizing an account for read-only personal access. Empty keeps every command on the bot identity. | Empty |
feishu.debug.adapterStream | Enable adapter stream debug logs. | false |
feishu.debug.textMerge | Enable text merge debug logs. | false |
When feishu.cli.enabled is true, Feishu-origin Threads receive the FeishuCli tool. Every invocation requests approval. The adapter exchanges its configured app credentials for a cached tenant access token and runs the bundled CLI as the bot. The CLI child receives the App ID and an access token, never the App Secret.
The adapter injects a usage policy into the Feishu Thread context. Read a known Skill directly, and call skills list only when you do not know which Skill applies. When a Skill links a reference, load it with skills read <skill-name> <relative-path> before running the business command. Identity comes from the tool's identity input rather than --as, which the adapter rejects. whoami reports the effective identity and token status.
feishu.cli.userScopes lists the Feishu user scopes to request, and stays empty until an operator opts in; only scopes already enabled for the app can be granted. DotCraft appends offline_access and runs the device authorization itself, so the CLI's own auth and config commands stay unavailable. One authorized account serves the whole Channel, which is why identity: "user" is accepted only for read-only commands. The authorization is stored in the Channel's module state directory in plain text, alongside the App Secret already kept there. Personal access covers the operator's side.
The bundled CLI runs only through FeishuCli, never from a shell. CLI file arguments must stay inside the workspace. Document, wiki, file, media, and page tokens are business resource identifiers and are allowed. Raw api, CLI auth/config/profile management, --profile, caller-supplied --yes, runtime installation, and self-update are unavailable. The adapter appends --yes only after DotCraft approval and the pinned CLI's risk classification identify a high-risk-write operation. --help returns plain-text help without requesting a tenant token. Business commands still return structured JSON.
Telegram
{
"dotcraft": {
"wsUrl": "ws://127.0.0.1:9100/ws",
"token": ""
},
"telegram": {
"botToken": "123456:telegram-bot-token",
"httpsProxy": "",
"approvalTimeoutMs": 120000,
"pollTimeoutMs": 30000
}
}| Field | Description | Default |
|---|---|---|
dotcraft.wsUrl | AppServer WebSocket endpoint for standalone adapters. Desktop-managed runtime overrides this value. | ws://127.0.0.1:9100/ws |
dotcraft.token | AppServer WebSocket token for standalone adapters. Desktop-managed runtime overrides this value. | Empty |
telegram.botToken | Bot token issued by BotFather. | Required |
telegram.httpsProxy | Optional HTTPS proxy for Telegram Bot API requests. | Empty |
telegram.approvalTimeoutMs | Approval timeout in milliseconds. | 120000 |
telegram.pollTimeoutMs | Telegram long-poll timeout in milliseconds. | 30000 |
Weixin
{
"dotcraft": {
"wsUrl": "ws://127.0.0.1:9100/ws",
"token": ""
},
"weixin": {
"apiBaseUrl": "https://ilinkai.weixin.qq.com",
"pollIntervalMs": 3000,
"pollTimeoutMs": 30000,
"approvalTimeoutMs": 120000,
"botType": "3"
}
}| Field | Description | Default |
|---|---|---|
dotcraft.wsUrl | AppServer WebSocket endpoint for standalone adapters. Desktop-managed runtime overrides this value. | ws://127.0.0.1:9100/ws |
dotcraft.token | AppServer WebSocket token for standalone adapters. Desktop-managed runtime overrides this value. | Empty |
weixin.apiBaseUrl | Tencent iLink API base URL. | https://ilinkai.weixin.qq.com |
weixin.pollIntervalMs | Delay between polling cycles in milliseconds. | 3000 |
weixin.pollTimeoutMs | Long-poll timeout in milliseconds. | 30000 |
weixin.approvalTimeoutMs | Approval timeout in milliseconds. | 120000 |
weixin.botType | Bot type value passed to the QR login API. | 3 |
Related docs
- DotCraft Full Configuration Reference — the workspace config file that holds
ExternalChannels, plus every other setting. - Channel adapters — the adapter base class, its message flow, and the handler contract.
- Channel Module integration — embed a TypeScript channel module in your own host process.