diff --git a/Cargo.lock b/Cargo.lock
index 566ef8c89..1baf77fc5 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -3812,7 +3812,7 @@ dependencies = [
 
 [[package]]
 name = "openfang-api"
-version = "0.4.9"
+version = "0.5.1"
 dependencies = [
  "async-trait",
  "axum",
@@ -3833,6 +3833,7 @@ dependencies = [
  "openfang-skills",
  "openfang-types",
  "openfang-wire",
+ "qrcode",
  "reqwest 0.12.28",
  "serde",
  "serde_json",
@@ -3852,7 +3853,7 @@ dependencies = [
 
 [[package]]
 name = "openfang-channels"
-version = "0.4.9"
+version = "0.5.1"
 dependencies = [
  "aes",
  "async-trait",
@@ -3870,6 +3871,7 @@ dependencies = [
  "mailparse",
  "native-tls",
  "openfang-types",
+ "qrcode",
  "regex-lite",
  "reqwest 0.12.28",
  "roxmltree",
@@ -3889,7 +3891,7 @@ dependencies = [
 
 [[package]]
 name = "openfang-cli"
-version = "0.4.9"
+version = "0.5.1"
 dependencies = [
  "clap",
  "clap_complete",
@@ -3916,7 +3918,7 @@ dependencies = [
 
 [[package]]
 name = "openfang-desktop"
-version = "0.4.9"
+version = "0.5.1"
 dependencies = [
  "axum",
  "open",
@@ -3942,7 +3944,7 @@ dependencies = [
 
 [[package]]
 name = "openfang-extensions"
-version = "0.4.9"
+version = "0.5.1"
 dependencies = [
  "aes-gcm",
  "argon2",
@@ -3970,7 +3972,7 @@ dependencies = [
 
 [[package]]
 name = "openfang-hands"
-version = "0.4.9"
+version = "0.5.1"
 dependencies = [
  "chrono",
  "dashmap",
@@ -3987,7 +3989,7 @@ dependencies = [
 
 [[package]]
 name = "openfang-kernel"
-version = "0.4.9"
+version = "0.5.1"
 dependencies = [
  "async-trait",
  "chrono",
@@ -4025,7 +4027,7 @@ dependencies = [
 
 [[package]]
 name = "openfang-memory"
-version = "0.4.9"
+version = "0.5.1"
 dependencies = [
  "async-trait",
  "chrono",
@@ -4044,7 +4046,7 @@ dependencies = [
 
 [[package]]
 name = "openfang-migrate"
-version = "0.4.9"
+version = "0.5.1"
 dependencies = [
  "chrono",
  "dirs 6.0.0",
@@ -4063,7 +4065,7 @@ dependencies = [
 
 [[package]]
 name = "openfang-runtime"
-version = "0.4.9"
+version = "0.5.1"
 dependencies = [
  "anyhow",
  "async-trait",
@@ -4097,7 +4099,7 @@ dependencies = [
 
 [[package]]
 name = "openfang-skills"
-version = "0.4.9"
+version = "0.5.1"
 dependencies = [
  "chrono",
  "hex",
@@ -4120,7 +4122,7 @@ dependencies = [
 
 [[package]]
 name = "openfang-types"
-version = "0.4.9"
+version = "0.5.1"
 dependencies = [
  "async-trait",
  "chrono",
@@ -4139,7 +4141,7 @@ dependencies = [
 
 [[package]]
 name = "openfang-wire"
-version = "0.4.9"
+version = "0.5.1"
 dependencies = [
  "async-trait",
  "chrono",
@@ -4806,6 +4808,15 @@ version = "0.1.28"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "b5a041e753da8b807c9255f28de81879c78c876392ff2469cde94799b2896b9d"
 
+[[package]]
+name = "qrcode"
+version = "0.14.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d68782463e408eb1e668cf6152704bd856c78c5b6417adaee3203d8f4c1fc9ec"
+dependencies = [
+ "image",
+]
+
 [[package]]
 name = "quanta"
 version = "0.12.6"
@@ -8818,7 +8829,7 @@ checksum = "b9cc00251562a284751c9973bace760d86c0276c471b4be569fe6b068ee97a56"
 
 [[package]]
 name = "xtask"
-version = "0.4.9"
+version = "0.5.1"
 
 [[package]]
 name = "yoke"
diff --git a/crates/openfang-api/Cargo.toml b/crates/openfang-api/Cargo.toml
index 6d4e582f9..b87aba637 100644
--- a/crates/openfang-api/Cargo.toml
+++ b/crates/openfang-api/Cargo.toml
@@ -38,6 +38,7 @@ hmac = { workspace = true }
 hex = { workspace = true }
 socket2 = { workspace = true }
 reqwest = { workspace = true }
+qrcode = "0.14"
 
 [dev-dependencies]
 tokio-test = { workspace = true }
diff --git a/crates/openfang-api/src/channel_bridge.rs b/crates/openfang-api/src/channel_bridge.rs
index 7ae5f8416..42e38f697 100644
--- a/crates/openfang-api/src/channel_bridge.rs
+++ b/crates/openfang-api/src/channel_bridge.rs
@@ -30,6 +30,7 @@ use openfang_channels::messenger::MessengerAdapter;
 use openfang_channels::reddit::RedditAdapter;
 use openfang_channels::revolt::RevoltAdapter;
 use openfang_channels::viber::ViberAdapter;
+use openfang_channels::wechat::WeChatAdapter;
 // Wave 4
 use openfang_channels::flock::FlockAdapter;
 use openfang_channels::guilded::GuildedAdapter;
@@ -784,6 +785,7 @@ impl ChannelBridgeHandle for KernelBridgeAdapter {
             "mastodon" => channels.mastodon.as_ref().map(|c| c.overrides.clone()),
             "bluesky" => channels.bluesky.as_ref().map(|c| c.overrides.clone()),
             "feishu" => channels.feishu.as_ref().map(|c| c.overrides.clone()),
+            "wechat" => channels.wechat.as_ref().map(|c| c.overrides.clone()),
             "revolt" => channels.revolt.as_ref().map(|c| c.overrides.clone()),
             // Wave 4
             "nextcloud" => channels.nextcloud.as_ref().map(|c| c.overrides.clone()),
@@ -1093,6 +1095,7 @@ pub async fn start_channel_bridge_with_config(
         || config.mastodon.is_some()
         || config.bluesky.is_some()
         || config.feishu.is_some()
+        || config.wechat.is_some()
         || config.revolt.is_some()
         // Wave 4
         || config.nextcloud.is_some()
@@ -1445,6 +1448,20 @@ pub async fn start_channel_bridge_with_config(
         }
     }
 
+    // WeChat iLink
+    if let Some(ref wc_config) = config.wechat {
+        let adapter = Arc::new(WeChatAdapter::new(
+            wc_config.bot_token_env.clone(),
+            wc_config.account_id_env.clone(),
+            wc_config.user_id_env.clone(),
+            wc_config.allowed_users.clone(),
+            wc_config.api_base_url.clone(),
+            wc_config.cdn_base_url.clone(),
+            wc_config.state_dir.clone(),
+        ));
+        adapters.push((adapter, wc_config.default_agent.clone()));
+    }
+
     // Revolt
     if let Some(ref rv_config) = config.revolt {
         if let Some(token) = read_token(&rv_config.bot_token_env, "Revolt") {
@@ -1854,6 +1871,7 @@ mod tests {
         assert!(config.channels.mastodon.is_none());
         assert!(config.channels.bluesky.is_none());
         assert!(config.channels.feishu.is_none());
+        assert!(config.channels.wechat.is_none());
         assert!(config.channels.revolt.is_none());
         // Wave 4
         assert!(config.channels.nextcloud.is_none());
diff --git a/crates/openfang-api/src/routes.rs b/crates/openfang-api/src/routes.rs
index 5a383d81d..86ab7f1db 100644
--- a/crates/openfang-api/src/routes.rs
+++ b/crates/openfang-api/src/routes.rs
@@ -14,9 +14,10 @@ use openfang_kernel::OpenFangKernel;
 use openfang_runtime::kernel_handle::KernelHandle;
 use openfang_runtime::tool_runner::builtin_tool_definitions;
 use openfang_types::agent::{AgentId, AgentIdentity, AgentManifest};
+use qrcode::{render::svg, QrCode};
 use std::collections::HashMap;
 use std::sync::{Arc, LazyLock};
-use std::time::Instant;
+use std::time::{Duration, Instant};
 
 /// Shared application state.
 ///
@@ -1891,6 +1892,22 @@ const CHANNEL_REGISTRY: &[ChannelMeta] = &[
         setup_steps: &["Create an app at open.feishu.cn (CN) or open.larksuite.com (International)", "Copy App ID and Secret", "Set region: cn (Feishu) or intl (Lark)"],
         config_template: "[channels.feishu]\napp_id = \"\"\napp_secret_env = \"FEISHU_APP_SECRET\"\nregion = \"cn\"",
     },
+    ChannelMeta {
+        name: "wechat", display_name: "WeChat", icon: "WX",
+        description: "WeChat iLink bot adapter with QR-code login",
+        category: "messaging", difficulty: "Easy", setup_time: "~1 min",
+        quick_setup: "Save your default agent, then scan the QR code with WeChat",
+        setup_type: "qr",
+        fields: &[
+            ChannelField { key: "default_agent", label: "Default Agent", field_type: FieldType::Text, env_var: None, required: false, placeholder: "assistant", advanced: false },
+            ChannelField { key: "allowed_users", label: "Allowed User IDs", field_type: FieldType::List, env_var: None, required: false, placeholder: "wxid_xxx, wxid_yyy", advanced: true },
+            ChannelField { key: "state_dir", label: "State Directory", field_type: FieldType::Text, env_var: None, required: false, placeholder: "~/.openfang/wechat", advanced: true },
+            ChannelField { key: "api_base_url", label: "API Base URL", field_type: FieldType::Text, env_var: None, required: false, placeholder: "https://ilinkai.weixin.qq.com", advanced: true },
+            ChannelField { key: "cdn_base_url", label: "CDN Base URL", field_type: FieldType::Text, env_var: None, required: false, placeholder: "https://novac2c.cdn.weixin.qq.com/c2c", advanced: true },
+        ],
+        setup_steps: &["Save the WeChat channel settings", "Open WeChat on your phone and scan the QR code", "Confirm the login on your phone to finish linking"],
+        config_template: "[channels.wechat]\nbot_token_env = \"WECHAT_BOT_TOKEN\"\naccount_id_env = \"WECHAT_ACCOUNT_ID\"\nuser_id_env = \"WECHAT_USER_ID\"",
+    },
     ChannelMeta {
         name: "dingtalk", display_name: "DingTalk", icon: "DT",
         description: "DingTalk Robot API adapter",
@@ -2220,6 +2237,7 @@ fn is_channel_configured(config: &openfang_types::config::ChannelsConfig, name:
         "reddit" => config.reddit.is_some(),
         "mastodon" => config.mastodon.is_some(),
         "bluesky" => config.bluesky.is_some(),
+        "wechat" => config.wechat.is_some(),
         "linkedin" => config.linkedin.is_some(),
         "nostr" => config.nostr.is_some(),
         "teams" => config.teams.is_some(),
@@ -2404,6 +2422,10 @@ fn channel_config_values(
             .feishu
             .as_ref()
             .and_then(|c| serde_json::to_value(c).ok()),
+        "wechat" => config
+            .wechat
+            .as_ref()
+            .and_then(|c| serde_json::to_value(c).ok()),
         "revolt" => config
             .revolt
             .as_ref()
@@ -2488,6 +2510,61 @@ fn channel_config_values(
     }
 }
 
+fn wechat_state_dir(config: &openfang_types::config::WeChatConfig) -> std::path::PathBuf {
+    config
+        .state_dir
+        .as_ref()
+        .map(std::path::PathBuf::from)
+        .unwrap_or_else(|| openfang_kernel::config::openfang_home().join("wechat"))
+}
+
+fn wechat_has_saved_credentials(config: &openfang_types::config::WeChatConfig) -> bool {
+    if std::env::var(&config.bot_token_env)
+        .map(|v| !v.trim().is_empty())
+        .unwrap_or(false)
+    {
+        return true;
+    }
+
+    let account_path = wechat_state_dir(config).join("account.json");
+    if !account_path.exists() {
+        return false;
+    }
+
+    std::fs::read_to_string(account_path)
+        .ok()
+        .and_then(|content| serde_json::from_str::<serde_json::Value>(&content).ok())
+        .and_then(|json| {
+            json.get("token")
+                .and_then(serde_json::Value::as_str)
+                .map(str::to_string)
+        })
+        .map(|token| !token.trim().is_empty())
+        .unwrap_or(false)
+}
+
+fn channel_has_token(
+    config: &openfang_types::config::ChannelsConfig,
+    meta: &ChannelMeta,
+) -> bool {
+    if meta.name == "wechat" {
+        return config
+            .wechat
+            .as_ref()
+            .map(wechat_has_saved_credentials)
+            .unwrap_or(false);
+    }
+
+    meta.fields
+        .iter()
+        .filter(|f| f.required && f.env_var.is_some())
+        .all(|f| {
+            f.env_var
+                .map(|ev| std::env::var(ev).map(|v| !v.is_empty()).unwrap_or(false))
+                .unwrap_or(true)
+        })
+}
+
 /// GET /api/channels — List all 40 channel adapters with status and field metadata.
 pub async fn list_channels(State(state): State<Arc<AppState>>) -> impl IntoResponse {
     // Read the live channels config (updated on every hot-reload) instead of the
@@ -2502,16 +2579,13 @@ pub async fn list_channels(State(state): State<Arc<AppState>>) -> impl IntoRespo
             configured_count += 1;
         }
 
-        // Check if all required secret env vars are set
-        let has_token = meta
-            .fields
-            .iter()
-            .filter(|f| f.required && f.env_var.is_some())
-            .all(|f| {
-                f.env_var
-                    .map(|ev| std::env::var(ev).map(|v| !v.is_empty()).unwrap_or(false))
-                    .unwrap_or(true)
-            });
+        let has_token = channel_has_token(&live_channels, meta);
+        let connected = state
+            .kernel
+            .channel_adapters
+            .get(meta.name)
+            .map(|adapter| adapter.status().connected)
+            .unwrap_or(false);
 
         let config_vals = channel_config_values(&live_channels, meta.name);
         let fields: Vec<serde_json::Value> = meta
@@ -2532,6 +2606,7 @@ pub async fn list_channels(State(state): State<Arc<AppState>>) -> impl IntoRespo
             "setup_type": meta.setup_type,
             "configured": configured,
             "has_token": has_token,
+            "connected": connected,
             "fields": fields,
             "setup_steps": meta.setup_steps,
             "config_template": meta.config_template,
@@ -2620,6 +2695,29 @@ pub async fn configure_channel(
         );
     }
 
+    let fresh_config = openfang_kernel::config::load_config(Some(&config_path));
+    *state.channels_config.write().await = fresh_config.channels.clone();
+
+    if name == "wechat"
+        && fresh_config
+            .channels
+            .wechat
+            .as_ref()
+            .map(|cfg| !wechat_has_saved_credentials(cfg))
+            .unwrap_or(true)
+    {
+        return (
+            StatusCode::OK,
+            Json(serde_json::json!({
+                "status": "configured",
+                "channel": name,
+                "activated": false,
+                "requires_qr": true,
+                "note": "WeChat configuration saved. Scan the QR code to complete login."
+            })),
+        );
+    }
+
     // Hot-reload: activate the channel immediately
     match crate::channel_bridge::reload_channels_from_disk(&state).await {
         Ok(started) => {
@@ -2669,7 +2767,7 @@ pub async fn remove_channel(
         }
     };
 
-    let home = openfang_kernel::config::openfang_home();
+    let home = state.kernel.config.home_dir.clone();
     let secrets_path = home.join("secrets.env");
     let config_path = home.join("config.toml");
 
@@ -2684,6 +2782,30 @@ pub async fn remove_channel(
         }
     }
 
+    if name == "wechat" {
+        let wechat_config = {
+            let channels = state.channels_config.read().await;
+            channels.wechat.clone()
+        };
+
+        if let Some(config) = wechat_config {
+            for env_var in [
+                config.bot_token_env.as_str(),
+                config.account_id_env.as_str(),
+                config.user_id_env.as_str(),
+            ] {
+                let _ = remove_secret_env(&secrets_path, env_var);
+                // SAFETY: Single-threaded config operation
+                unsafe {
+                    std::env::remove_var(env_var);
+                }
+            }
+
+            let account_path = wechat_state_dir(&config).join("account.json");
+            let _ = std::fs::remove_file(account_path);
+        }
+    }
+
     // Remove config section
     if let Err(e) = remove_channel_config(&config_path, &name) {
         return (
@@ -2864,6 +2986,19 @@ async fn send_channel_test_message(channel_name: &str, target_id: &str) -> Resul
     Ok(())
 }
 
+#[derive(Clone)]
+struct WeChatQrFlowState {
+    qrcode: String,
+    api_base_url: String,
+    state_dir: std::path::PathBuf,
+    bot_token_env: String,
+    account_id_env: String,
+    user_id_env: String,
+    expires_at: Instant,
+}
+
+static WECHAT_QR_FLOWS: LazyLock<DashMap<String, WeChatQrFlowState>> = LazyLock::new(DashMap::new);
+
 /// POST /api/channels/reload — Manually trigger a channel hot-reload from disk config.
 pub async fn reload_channels(State(state): State<Arc<AppState>>) -> impl IntoResponse {
     match crate::channel_bridge::reload_channels_from_disk(&state).await {
@@ -2888,6 +3023,371 @@ pub async fn reload_channels(State(state): State<Arc<AppState>>) -> impl IntoRes
 // WhatsApp QR login flow (OpenClaw-style)
 // ---------------------------------------------------------------------------
 
+fn persist_wechat_account_state(
+    state_dir: &std::path::Path,
+    token: &str,
+    account_id: &str,
+    user_id: Option<&str>,
+) -> Result<(), String> {
+    std::fs::create_dir_all(state_dir).map_err(|e| e.to_string())?;
+    let payload = serde_json::json!({
+        "token": token,
+        "account_id": account_id,
+        "user_id": user_id,
+        "saved_at": chrono::Utc::now().to_rfc3339(),
+    });
+    std::fs::write(
+        state_dir.join("account.json"),
+        serde_json::to_string_pretty(&payload).map_err(|e| e.to_string())?,
+    )
+    .map_err(|e| e.to_string())
+}
+
+fn render_qr_data_url(data: &str) -> Option<String> {
+    use base64::Engine as _;
+
+    let qr = QrCode::new(data.as_bytes()).ok()?;
+    let svg = qr
+        .render::<svg::Color<'_>>()
+        .min_dimensions(256, 256)
+        .dark_color(svg::Color("#000000"))
+        .light_color(svg::Color("#ffffff"))
+        .build();
+    Some(format!(
+        "data:image/svg+xml;base64,{}",
+        base64::engine::general_purpose::STANDARD.encode(svg)
+    ))
+}
+
+/// POST /api/channels/wechat/qr/start — Start a WeChat QR login session.
+pub async fn wechat_qr_start(State(state): State<Arc<AppState>>) -> impl IntoResponse {
+    WECHAT_QR_FLOWS.retain(|_, flow| flow.expires_at > Instant::now());
+
+    let config = {
+        let channels = state.channels_config.read().await;
+        channels.wechat.clone()
+    };
+
+    let Some(config) = config else {
+        return Json(serde_json::json!({
+            "available": false,
+            "message": "WeChat is not configured yet. Save the channel settings first.",
+            "help": "Create a [channels.wechat] section in config.toml or save the WeChat form in the dashboard before starting QR login."
+        }));
+    };
+
+    if wechat_has_saved_credentials(&config) {
+        return Json(serde_json::json!({
+            "available": true,
+            "connected": true,
+            "message": "WeChat credentials already exist. Reload the channel if needed."
+        }));
+    }
+
+    let api_base_url = config
+        .api_base_url
+        .clone()
+        .unwrap_or_else(|| "https://ilinkai.weixin.qq.com".to_string());
+    let url = format!(
+        "{}/ilink/bot/get_bot_qrcode?bot_type=3",
+        api_base_url.trim_end_matches('/')
+    );
+
+    let client = reqwest::Client::new();
+    let response = match client
+        .get(url)
+        .timeout(Duration::from_secs(15))
+        .send()
+        .await
+    {
+        Ok(resp) => resp,
+        Err(e) => {
+            return Json(serde_json::json!({
+                "available": false,
+                "message": format!("Could not reach WeChat QR endpoint: {e}"),
+            }))
+        }
+    };
+
+    if !response.status().is_success() {
+        let status = response.status();
+        let body = response.text().await.unwrap_or_default();
+        return Json(serde_json::json!({
+            "available": false,
+            "message": format!("WeChat QR request failed {status}: {body}"),
+        }));
+    }
+
+    let body: serde_json::Value = match response.json().await {
+        Ok(json) => json,
+        Err(e) => {
+            return Json(serde_json::json!({
+                "available": false,
+                "message": format!("Invalid WeChat QR response: {e}"),
+            }))
+        }
+    };
+
+    let qrcode = body
+        .get("qrcode")
+        .and_then(serde_json::Value::as_str)
+        .unwrap_or("")
+        .to_string();
+    let qr_image_url = body
+        .get("qrcode_img_content")
+        .and_then(serde_json::Value::as_str)
+        .unwrap_or("")
+        .to_string();
+
+    if qrcode.is_empty() {
+        return Json(serde_json::json!({
+            "available": false,
+            "message": "WeChat QR response did not include a qrcode value."
+        }));
+    }
+
+    let qr_render_source = if qr_image_url.is_empty() {
+        qrcode.clone()
+    } else {
+        qr_image_url.clone()
+    };
+    let session_id = uuid::Uuid::new_v4().to_string();
+    WECHAT_QR_FLOWS.insert(
+        session_id.clone(),
+        WeChatQrFlowState {
+            qrcode,
+            api_base_url,
+            state_dir: wechat_state_dir(&config),
+            bot_token_env: config.bot_token_env,
+            account_id_env: config.account_id_env,
+            user_id_env: config.user_id_env,
+            expires_at: Instant::now() + Duration::from_secs(8 * 60),
+        },
+    );
+
+    Json(serde_json::json!({
+        "available": true,
+        "qr_data_url": render_qr_data_url(&qr_render_source).unwrap_or(qr_image_url),
+        "session_id": session_id,
+        "message": "Scan this QR code with WeChat, then confirm login on your phone.",
+        "connected": false
+    }))
+}
+
+/// GET /api/channels/wechat/qr/status — Poll for WeChat QR scan completion.
+pub async fn wechat_qr_status(
+    State(state): State<Arc<AppState>>,
+    axum::extract::Query(params): axum::extract::Query<std::collections::HashMap<String, String>>,
+) -> impl IntoResponse {
+    WECHAT_QR_FLOWS.retain(|_, flow| flow.expires_at > Instant::now());
+
+    let session_id = params.get("session_id").cloned().unwrap_or_default();
+    let Some(flow) = WECHAT_QR_FLOWS.get(&session_id).map(|entry| entry.clone()) else {
+        return Json(serde_json::json!({
+            "connected": false,
+            "expired": true,
+            "message": "QR login session not found or already expired."
+        }));
+    };
+
+    if flow.expires_at <= Instant::now() {
+        WECHAT_QR_FLOWS.remove(&session_id);
+        return Json(serde_json::json!({
+            "connected": false,
+            "expired": true,
+            "message": "QR code expired. Generate a new one."
+        }));
+    }
+
+    let status_url = format!(
+        "{}/ilink/bot/get_qrcode_status",
+        flow.api_base_url.trim_end_matches('/')
+    );
+    let client = reqwest::Client::new();
+    let response = match client
+        .get(status_url)
+        .query(&[("qrcode", flow.qrcode.as_str())])
+        .timeout(Duration::from_secs(12))
+        .send()
+        .await
+    {
+        Ok(resp) => resp,
+        Err(err) => {
+            if err.is_timeout() {
+                return Json(serde_json::json!({
+                    "connected": false,
+                    "expired": false,
+                    "message": "Waiting for scan..."
+                }));
+            }
+            return Json(serde_json::json!({
+                "connected": false,
+                "expired": false,
+                "message": format!("WeChat status check failed: {err}")
+            }));
+        }
+    };
+
+    if !response.status().is_success() {
+        let status = response.status();
+        let body = response.text().await.unwrap_or_default();
+        return Json(serde_json::json!({
+            "connected": false,
+            "expired": false,
+            "message": format!("WeChat status failed {status}: {body}")
+        }));
+    }
+
+    let payload: serde_json::Value = match response.json().await {
+        Ok(json) => json,
+        Err(e) => {
+            return Json(serde_json::json!({
+                "connected": false,
+                "expired": false,
+                "message": format!("Invalid WeChat status response: {e}")
+            }))
+        }
+    };
+
+    let status = payload
+        .get("status")
+        .and_then(serde_json::Value::as_str)
+        .unwrap_or("wait");
+
+    match status {
+        "wait" => Json(serde_json::json!({
+            "connected": false,
+            "expired": false,
+            "message": "Waiting for scan..."
+        })),
+        "scaned" => Json(serde_json::json!({
+            "connected": false,
+            "expired": false,
+            "message": "QR scanned. Confirm the login in WeChat on your phone."
+        })),
+        "expired" => {
+            WECHAT_QR_FLOWS.remove(&session_id);
+            Json(serde_json::json!({
+                "connected": false,
+                "expired": true,
+                "message": "QR code expired. Generate a new one."
+            }))
+        }
+        "confirmed" => {
+            let bot_token = match payload.get("bot_token").and_then(serde_json::Value::as_str) {
+                Some(value) if !value.is_empty() => value.to_string(),
+                _ => {
+                    return Json(serde_json::json!({
+                        "connected": false,
+                        "expired": false,
+                        "message": "WeChat login completed but bot_token was missing."
+                    }))
+                }
+            };
+            let account_id =
+                match payload.get("ilink_bot_id").and_then(serde_json::Value::as_str) {
+                Some(value) if !value.is_empty() => value.to_string(),
+                _ => {
+                    return Json(serde_json::json!({
+                        "connected": false,
+                        "expired": false,
+                        "message": "WeChat login completed but account_id was missing."
+                    }))
+                }
+            };
+            let user_id = payload
+                .get("ilink_user_id")
+                .and_then(serde_json::Value::as_str)
+                .map(str::to_string);
+
+            if let Err(e) = write_secret_env(
+                &state.kernel.config.home_dir.join("secrets.env"),
+                &flow.bot_token_env,
+                &bot_token,
+            ) {
+                return Json(serde_json::json!({
+                    "connected": false,
+                    "expired": false,
+                    "message": format!("Failed to save WeChat bot token: {e}")
+                }));
+            }
+            let _ = write_secret_env(
+                &state.kernel.config.home_dir.join("secrets.env"),
+                &flow.account_id_env,
+                &account_id,
+            );
+            if let Some(ref user_id) = user_id {
+                let _ = write_secret_env(
+                    &state.kernel.config.home_dir.join("secrets.env"),
+                    &flow.user_id_env,
+                    user_id,
+                );
+            }
+
+            std::env::set_var(&flow.bot_token_env, &bot_token);
+            std::env::set_var(&flow.account_id_env, &account_id);
+            if let Some(ref user_id) = user_id {
+                std::env::set_var(&flow.user_id_env, user_id);
+            }
+
+            let _ = persist_wechat_account_state(
+                &flow.state_dir,
+                &bot_token,
+                &account_id,
+                user_id.as_deref(),
+            );
+
+            WECHAT_QR_FLOWS.remove(&session_id);
+
+            let _ = crate::channel_bridge::reload_channels_from_disk(&state).await;
+
+            Json(serde_json::json!({
+                "connected": true,
+                "expired": false,
+                "message": "WeChat linked successfully."
+            }))
+        }
+        other => Json(serde_json::json!({
+            "connected": false,
+            "expired": false,
+            "message": format!("Unexpected WeChat QR status: {other}")
+        })),
+    }
+}
+
+/// POST /api/channels/{name}/qr/start — Start QR login for supported channels.
+pub async fn channel_qr_start(
+    State(state): State<Arc<AppState>>,
+    Path(name): Path<String>,
+) -> impl IntoResponse {
+    match name.as_str() {
+        "whatsapp" => whatsapp_qr_start().await.into_response(),
+        "wechat" => wechat_qr_start(State(state)).await.into_response(),
+        _ => (
+            StatusCode::NOT_FOUND,
+            Json(serde_json::json!({"error": "QR login not supported for this channel"})),
+        )
+            .into_response(),
+    }
+}
+
+/// GET /api/channels/{name}/qr/status — Poll QR login status for supported channels.
+pub async fn channel_qr_status(
+    State(state): State<Arc<AppState>>,
+    Path(name): Path<String>,
+    query: axum::extract::Query<std::collections::HashMap<String, String>>,
+) -> impl IntoResponse {
+    match name.as_str() {
+        "whatsapp" => whatsapp_qr_status(query).await.into_response(),
+        "wechat" => wechat_qr_status(State(state), query).await.into_response(),
+        _ => (
+            StatusCode::NOT_FOUND,
+            Json(serde_json::json!({"error": "QR status not supported for this channel"})),
+        )
+            .into_response(),
+    }
+}
+
 /// POST /api/channels/whatsapp/qr/start — Start a WhatsApp Web QR login session.
 ///
 /// If a WhatsApp Web gateway is available (e.g. a Baileys-based bridge process),
diff --git a/crates/openfang-api/src/server.rs b/crates/openfang-api/src/server.rs
index b6980928c..5ee016275 100644
--- a/crates/openfang-api/src/server.rs
+++ b/crates/openfang-api/src/server.rs
@@ -258,14 +258,14 @@ pub async fn build_router(
             "/api/channels/reload",
             axum::routing::post(routes::reload_channels),
         )
-        // WhatsApp QR login flow
+        // QR login flow (WhatsApp / WeChat)
         .route(
-            "/api/channels/whatsapp/qr/start",
-            axum::routing::post(routes::whatsapp_qr_start),
+            "/api/channels/{name}/qr/start",
+            axum::routing::post(routes::channel_qr_start),
         )
         .route(
-            "/api/channels/whatsapp/qr/status",
-            axum::routing::get(routes::whatsapp_qr_status),
+            "/api/channels/{name}/qr/status",
+            axum::routing::get(routes::channel_qr_status),
         )
         // Template endpoints
         .route("/api/templates", axum::routing::get(routes::list_templates))
diff --git a/crates/openfang-api/static/index_body.html b/crates/openfang-api/static/index_body.html
index f9e5dffbf..4f84ad858 100644
--- a/crates/openfang-api/static/index_body.html
+++ b/crates/openfang-api/static/index_body.html
@@ -2029,18 +2029,18 @@ <h3 style="display:flex;align-items:center;gap:0.5rem">
                 </div>
 
                 <!-- ═══ QR CODE FLOW (WhatsApp Web style) ═══ -->
-                <template x-if="isQrChannel() && !showBusinessApi">
+                <template x-if="showQrPanel()">
                   <div>
                     <!-- QR: Loading -->
                     <div x-show="qr.loading" style="text-align:center;padding:2rem 0">
                       <div class="spinner"></div>
-                      <p class="text-sm text-dim mt-2">Connecting to WhatsApp Web gateway...</p>
+                      <p class="text-sm text-dim mt-2" x-text="qrLoadingText()"></p>
                     </div>
 
                     <!-- QR: Gateway available — show QR code -->
                     <div x-show="!qr.loading && qr.available && qr.dataUrl && !qr.connected" style="text-align:center">
                       <div style="background:#fff;display:inline-block;padding:1rem;border-radius:12px;margin:0.5rem 0">
-                        <img :src="qr.dataUrl" alt="WhatsApp QR Code" style="width:256px;height:256px;image-rendering:pixelated">
+                        <img :src="qr.dataUrl" :alt="qrDisplayName() + ' QR Code'" style="width:256px;height:256px;image-rendering:pixelated">
                       </div>
                       <ol style="text-align:left;font-size:0.85rem;margin:1rem 0;padding-left:1.5rem;opacity:0.8">
                         <template x-for="(step, i) in setupModal.setup_steps || []" :key="i">
@@ -2054,7 +2054,7 @@ <h3 style="display:flex;align-items:center;gap:0.5rem">
                     <!-- QR: Connected! -->
                     <div x-show="!qr.loading && qr.connected" style="text-align:center;padding:2rem 0">
                       <div style="font-size:3rem;margin-bottom:0.5rem">&#10003;</div>
-                      <p class="text-sm" style="font-weight:600" x-text="qr.message || 'WhatsApp linked successfully!'"></p>
+                      <p class="text-sm" style="font-weight:600" x-text="qr.message || qrConnectedText()"></p>
                       <p class="text-xs text-dim mt-1">Channel will activate automatically.</p>
                     </div>
 
@@ -2062,17 +2062,17 @@ <h3 style="display:flex;align-items:center;gap:0.5rem">
                     <div x-show="!qr.loading && !qr.available" style="padding:1rem 0">
                       <div style="background:var(--bg-secondary,#1a1a2e);border-radius:8px;padding:1.25rem;text-align:center">
                         <div style="font-size:2rem;margin-bottom:0.5rem;opacity:0.5">&#128241;</div>
-                        <p class="text-sm" x-text="qr.message || 'WhatsApp Web gateway not available'"></p>
+                        <p class="text-sm" x-text="qr.message || qrUnavailableText()"></p>
                         <p class="text-xs text-dim mt-2" x-show="qr.help" x-text="qr.help"></p>
                         <p class="text-xs text-dim mt-1" x-show="qr.error" style="color:var(--red,#ef4444)" x-text="qr.error"></p>
                       </div>
-                      <p class="text-xs text-dim mt-3" style="text-align:center">
+                      <p class="text-xs text-dim mt-3" style="text-align:center" x-show="isWhatsAppChannel()">
                         Or use the <button class="btn-link" @click="showBusinessApi = true" style="font-size:inherit;text-decoration:underline;cursor:pointer;background:none;border:none;color:var(--accent,#818cf8);padding:0">Business API</button> with a Meta developer account.
                       </p>
                     </div>
 
                     <!-- QR: Switch to Business API link (always visible when gateway is available) -->
-                    <div x-show="!qr.loading && qr.available" class="text-xs text-dim mt-2" style="text-align:center">
+                    <div x-show="isWhatsAppChannel() && !qr.loading && qr.available" class="text-xs text-dim mt-2" style="text-align:center">
                       Have a Meta Business account? <button class="btn-link" @click="showBusinessApi = true" style="font-size:inherit;text-decoration:underline;cursor:pointer;background:none;border:none;color:var(--accent,#818cf8);padding:0">Use Business API instead</button>
                     </div>
 
@@ -2089,7 +2089,7 @@ <h3 style="display:flex;align-items:center;gap:0.5rem">
                 </template>
 
                 <!-- ═══ STANDARD FORM FLOW (for non-QR channels, or Business API fallback) ═══ -->
-                <template x-if="(!isQrChannel() || showBusinessApi) && !(setupStep === 3 && testPassed && !isQrChannel())">
+                <template x-if="showConfigForm() && !(setupStep === 3 && testPassed && !isQrChannel())">
                   <div>
                     <!-- Back to QR link (only for QR channels in Business API mode) -->
                     <div x-show="isQrChannel() && showBusinessApi" class="mb-3">
diff --git a/crates/openfang-api/static/js/pages/channels.js b/crates/openfang-api/static/js/pages/channels.js
index 84568e7e5..fabc890c9 100644
--- a/crates/openfang-api/static/js/pages/channels.js
+++ b/crates/openfang-api/static/js/pages/channels.js
@@ -85,13 +85,59 @@ function channelsPage() {
       return this.setupModal && this.setupModal.setup_type === 'qr';
     },
 
+    isWhatsAppChannel() {
+      return this.setupModal && this.setupModal.name === 'whatsapp';
+    },
+
+    isConfiguredQrChannel() {
+      return this.isQrChannel() && this.setupModal && this.setupModal.configured;
+    },
+
+    needsQrLink() {
+      return this.isQrChannel() &&
+             !this.isWhatsAppChannel() &&
+             this.setupModal &&
+             this.setupModal.configured &&
+             !this.setupModal.has_token;
+    },
+
+    showQrPanel() {
+      if (!this.isQrChannel()) return false;
+      if (this.isWhatsAppChannel()) return !this.showBusinessApi;
+      return this.qr.connected || this.needsQrLink();
+    },
+
+    showConfigForm() {
+      if (!this.isQrChannel()) return true;
+      if (this.isWhatsAppChannel()) return this.showBusinessApi;
+      if (!this.setupModal) return false;
+      return !this.setupModal.configured || (this.setupModal.has_token && !this.qr.connected);
+    },
+
+    qrDisplayName() {
+      return this.setupModal ? this.setupModal.display_name : 'QR channel';
+    },
+
+    qrLoadingText() {
+      return 'Requesting a ' + this.qrDisplayName() + ' QR code...';
+    },
+
+    qrConnectedText() {
+      return this.qrDisplayName() + ' linked successfully!';
+    },
+
+    qrUnavailableText() {
+      if (this.isWhatsAppChannel()) return 'WhatsApp Web gateway not available';
+      return this.qrDisplayName() + ' QR login not available yet';
+    },
+
     async loadChannels() {
       this.loading = true;
       this.loadError = '';
       try {
         var data = await OpenFangAPI.get('/api/channels');
         this.allChannels = (data.channels || []).map(function(ch) {
-          ch.connected = ch.configured && ch.has_token;
+          ch.connected = !!ch.connected;
           return ch;
         });
       } catch(e) {
@@ -119,7 +165,7 @@ function channelsPage() {
           if (fresh) {
             c.configured = fresh.configured;
             c.has_token = fresh.has_token;
-            c.connected = fresh.configured && fresh.has_token;
+            c.connected = !!fresh.connected;
             c.fields = fresh.fields;
           }
         });
@@ -128,6 +174,7 @@ function channelsPage() {
 
     statusBadge(ch) {
       if (!ch.configured) return { text: 'Not Configured', cls: 'badge-muted' };
+      if (ch.name === 'wechat' && !ch.has_token) return { text: 'Needs Scan', cls: 'badge-warn' };
       if (!ch.has_token) return { text: 'Missing Token', cls: 'badge-warn' };
       if (ch.connected) return { text: 'Ready', cls: 'badge-success' };
       return { text: 'Configured', cls: 'badge-info' };
@@ -153,11 +200,11 @@ function channelsPage() {
       this.formValues = vals;
       this.showAdvanced = false;
       this.showBusinessApi = false;
-      this.setupStep = ch.configured ? 3 : 1;
-      this.testPassed = !!ch.configured;
+      this.setupStep = ch.configured ? (ch.has_token ? 3 : 2) : 1;
+      this.testPassed = !!(ch.configured && ch.has_token);
       this.resetQR();
       // Auto-start QR flow for QR-type channels
-      if (ch.setup_type === 'qr') {
+      if (ch.setup_type === 'qr' && (ch.name === 'whatsapp' || (ch.configured && !ch.has_token))) {
         this.startQR();
       }
     },
@@ -173,12 +220,13 @@ function channelsPage() {
     },
 
     async startQR() {
+      if (!this.setupModal) return;
       this.qr.loading = true;
       this.qr.error = '';
       this.qr.connected = false;
       this.qr.expired = false;
       try {
-        var result = await OpenFangAPI.post('/api/channels/whatsapp/qr/start', {});
+        var result = await OpenFangAPI.post('/api/channels/' + this.setupModal.name + '/qr/start', {});
         this.qr.available = result.available || false;
         this.qr.dataUrl = result.qr_data_url || '';
         this.qr.sessionId = result.session_id || '';
@@ -189,7 +237,7 @@ function channelsPage() {
           this.pollQR();
         }
         if (this.qr.connected) {
-          OpenFangToast.success('WhatsApp connected!');
+          OpenFangToast.success(this.qrDisplayName() + ' connected!');
           await this.refreshStatus();
         }
       } catch(e) {
@@ -203,13 +251,13 @@ function channelsPage() {
       if (this.qrPollTimer) clearInterval(this.qrPollTimer);
       this.qrPollTimer = setInterval(async function() {
         try {
-          var result = await OpenFangAPI.get('/api/channels/whatsapp/qr/status?session_id=' + encodeURIComponent(self.qr.sessionId));
+          var result = await OpenFangAPI.get('/api/channels/' + self.setupModal.name + '/qr/status?session_id=' + encodeURIComponent(self.qr.sessionId));
           if (result.connected) {
             clearInterval(self.qrPollTimer);
             self.qrPollTimer = null;
             self.qr.connected = true;
             self.qr.message = result.message || 'Connected!';
-            OpenFangToast.success('WhatsApp linked successfully!');
+            OpenFangToast.success(self.qrDisplayName() + ' linked successfully!');
             await self.refreshStatus();
           } else if (result.expired) {
             clearInterval(self.qrPollTimer);
@@ -230,9 +278,27 @@ function channelsPage() {
       var name = this.setupModal.name;
       this.configuring = true;
       try {
-        await OpenFangAPI.post('/api/channels/' + name + '/configure', {
+        var configureResult = await OpenFangAPI.post('/api/channels/' + name + '/configure', {
           fields: this.formValues
         });
+        await this.refreshStatus();
+        if (this.setupModal.setup_type === 'qr' && name !== 'whatsapp' && configureResult.requires_qr) {
+          this.setupModal.configured = true;
+          this.setupModal.has_token = false;
+          this.setupStep = 2;
+          this.testPassed = false;
+          OpenFangToast.success(configureResult.note || (this.setupModal.display_name + ' saved. Scan the QR code to finish linking.'));
+          await this.startQR();
+          this.configuring = false;
+          return;
+        }
+        if (this.setupModal.setup_type === 'qr' && name !== 'whatsapp') {
+          this.setupStep = 3;
+          this.testPassed = true;
+          OpenFangToast.success(configureResult.note || (this.setupModal.display_name + ' saved and activated.'));
+          this.configuring = false;
+          return;
+        }
         this.setupStep = 2;
         // Auto-test after save
         try {
diff --git a/crates/openfang-channels/Cargo.toml b/crates/openfang-channels/Cargo.toml
index b67b91c99..3b26828d1 100644
--- a/crates/openfang-channels/Cargo.toml
+++ b/crates/openfang-channels/Cargo.toml
@@ -32,6 +32,7 @@ hex = { workspace = true }
 html-escape = { workspace = true }
 regex-lite = "0.1"
 roxmltree = "0.21"
+qrcode = "0.14"
 
 lettre = { workspace = true }
 imap = { workspace = true }
diff --git a/crates/openfang-channels/src/lib.rs b/crates/openfang-channels/src/lib.rs
index 086280176..eccd1f075 100644
--- a/crates/openfang-channels/src/lib.rs
+++ b/crates/openfang-channels/src/lib.rs
@@ -52,3 +52,4 @@ pub mod mumble;
 pub mod ntfy;
 pub mod webhook;
 pub mod wecom;
+pub mod wechat;
diff --git a/crates/openfang-channels/src/wechat.rs b/crates/openfang-channels/src/wechat.rs
new file mode 100644
index 000000000..aec93d1dd
--- /dev/null
+++ b/crates/openfang-channels/src/wechat.rs
@@ -0,0 +1,809 @@
+//! WeChat iLink Bot channel adapter.
+//!
+//! Uses the iLink Bot API with QR-code login and long polling. The bot token
+//! and sync cursor are stored under `state_dir` so the daemon can resume
+//! without re-scanning after the first successful login.
+
+use crate::types::{
+    ChannelAdapter, ChannelContent, ChannelMessage, ChannelStatus, ChannelType, ChannelUser,
+};
+use async_trait::async_trait;
+use chrono::Utc;
+use futures::Stream;
+use qrcode::{render::unicode, QrCode};
+use std::collections::HashMap;
+use std::path::{Path, PathBuf};
+use std::pin::Pin;
+use std::sync::{Arc, Mutex, RwLock};
+use std::time::{Duration, Instant};
+use tokio::sync::{mpsc, watch};
+use tracing::{debug, info, warn};
+
+const DEFAULT_API_BASE_URL: &str = "https://ilinkai.weixin.qq.com";
+const DEFAULT_CDN_BASE_URL: &str = "https://novac2c.cdn.weixin.qq.com/c2c";
+const LONG_POLL_TIMEOUT_MS: u64 = 35_000;
+const API_TIMEOUT_SECS: u64 = 15;
+const QR_STATUS_TIMEOUT_SECS: u64 = 45;
+const INITIAL_BACKOFF_SECS: u64 = 2;
+const MAX_BACKOFF_SECS: u64 = 30;
+const SESSION_EXPIRED_ERRCODE: i64 = -14;
+
+#[derive(Debug, Clone, serde::Serialize, serde::Deserialize, Default)]
+struct AccountData {
+    #[serde(default)]
+    token: Option<String>,
+    #[serde(default)]
+    account_id: Option<String>,
+    #[serde(default)]
+    user_id: Option<String>,
+    #[serde(default)]
+    saved_at: Option<String>,
+}
+
+#[derive(Debug, Clone, serde::Serialize, serde::Deserialize, Default)]
+struct SyncData {
+    #[serde(default)]
+    get_updates_buf: String,
+}
+
+#[derive(Debug, Default)]
+struct AdapterRuntimeState {
+    connected: bool,
+    started_at: Option<chrono::DateTime<Utc>>,
+    last_message_at: Option<chrono::DateTime<Utc>>,
+    messages_received: u64,
+    messages_sent: u64,
+    last_error: Option<String>,
+}
+
+/// WeChat iLink adapter with QR login and long polling.
+pub struct WeChatAdapter {
+    bot_token_env: String,
+    account_id_env: String,
+    user_id_env: String,
+    api_base_url: String,
+    _cdn_base_url: String,
+    state_dir: PathBuf,
+    allowed_users: Vec<String>,
+    client: reqwest::Client,
+    bot_token: Arc<RwLock<Option<String>>>,
+    account_id: Arc<RwLock<Option<String>>>,
+    context_tokens: Arc<Mutex<HashMap<String, String>>>,
+    cursor: Arc<Mutex<String>>,
+    runtime: Arc<Mutex<AdapterRuntimeState>>,
+    shutdown_tx: Arc<watch::Sender<bool>>,
+    shutdown_rx: watch::Receiver<bool>,
+}
+
+impl WeChatAdapter {
+    pub fn new(
+        bot_token_env: String,
+        account_id_env: String,
+        user_id_env: String,
+        allowed_users: Vec<String>,
+        api_base_url: Option<String>,
+        cdn_base_url: Option<String>,
+        state_dir: Option<String>,
+    ) -> Self {
+        let (shutdown_tx, shutdown_rx) = watch::channel(false);
+        let adapter = Self {
+            bot_token_env,
+            account_id_env,
+            user_id_env,
+            api_base_url: api_base_url.unwrap_or_else(|| DEFAULT_API_BASE_URL.to_string()),
+            _cdn_base_url: cdn_base_url.unwrap_or_else(|| DEFAULT_CDN_BASE_URL.to_string()),
+            state_dir: state_dir
+                .map(PathBuf::from)
+                .unwrap_or_else(default_state_dir),
+            allowed_users,
+            client: reqwest::Client::new(),
+            bot_token: Arc::new(RwLock::new(None)),
+            account_id: Arc::new(RwLock::new(None)),
+            context_tokens: Arc::new(Mutex::new(HashMap::new())),
+            cursor: Arc::new(Mutex::new(String::new())),
+            runtime: Arc::new(Mutex::new(AdapterRuntimeState::default())),
+            shutdown_tx: Arc::new(shutdown_tx),
+            shutdown_rx,
+        };
+        adapter.load_persisted_state();
+        adapter
+    }
+
+    fn clone_for_task(&self) -> Self {
+        Self {
+            bot_token_env: self.bot_token_env.clone(),
+            account_id_env: self.account_id_env.clone(),
+            user_id_env: self.user_id_env.clone(),
+            api_base_url: self.api_base_url.clone(),
+            _cdn_base_url: self._cdn_base_url.clone(),
+            state_dir: self.state_dir.clone(),
+            allowed_users: self.allowed_users.clone(),
+            client: self.client.clone(),
+            bot_token: Arc::clone(&self.bot_token),
+            account_id: Arc::clone(&self.account_id),
+            context_tokens: Arc::clone(&self.context_tokens),
+            cursor: Arc::clone(&self.cursor),
+            runtime: Arc::clone(&self.runtime),
+            shutdown_tx: Arc::clone(&self.shutdown_tx),
+            shutdown_rx: self.shutdown_rx.clone(),
+        }
+    }
+
+    fn load_persisted_state(&self) {
+        if let Ok(token) = std::env::var(&self.bot_token_env).map(|value| value.trim().to_string()) {
+            if !token.is_empty() {
+                if let Ok(mut guard) = self.bot_token.write() {
+                    *guard = Some(token);
+                }
+            }
+        }
+        if let Ok(account_id) =
+            std::env::var(&self.account_id_env).map(|value| value.trim().to_string())
+        {
+            if !account_id.is_empty() {
+                if let Ok(mut guard) = self.account_id.write() {
+                    *guard = Some(account_id);
+                }
+            }
+        }
+
+        let account_path = self.state_dir.join("account.json");
+        if let Ok(content) = std::fs::read_to_string(&account_path) {
+            if let Ok(account) = serde_json::from_str::<AccountData>(&content) {
+                if self.get_token().is_none() {
+                    if let Some(token) = account.token.filter(|value| !value.is_empty()) {
+                        if let Ok(mut guard) = self.bot_token.write() {
+                            *guard = Some(token);
+                        }
+                    }
+                }
+                if self.account_id.read().ok().and_then(|guard| guard.clone()).is_none() {
+                    if let Some(account_id) = account.account_id {
+                        if let Ok(mut account_guard) = self.account_id.write() {
+                            *account_guard = Some(account_id);
+                        }
+                    }
+                }
+            }
+        }
+
+        let sync_path = self.state_dir.join("sync.json");
+        if let Ok(content) = std::fs::read_to_string(&sync_path) {
+            if let Ok(sync) = serde_json::from_str::<SyncData>(&content) {
+                if let Ok(mut guard) = self.cursor.lock() {
+                    *guard = sync.get_updates_buf;
+                }
+            }
+        }
+    }
+
+    fn save_account_data(&self, token: &str, account_id: &str, user_id: Option<&str>) {
+        if std::fs::create_dir_all(&self.state_dir).is_err() {
+            return;
+        }
+        let data = AccountData {
+            token: Some(token.to_string()),
+            account_id: Some(account_id.to_string()),
+            user_id: user_id.map(str::to_string),
+            saved_at: Some(Utc::now().to_rfc3339()),
+        };
+        if let Ok(serialized) = serde_json::to_string_pretty(&data) {
+            let _ = std::fs::write(self.state_dir.join("account.json"), serialized);
+        }
+    }
+
+    pub fn bot_token_env(&self) -> &str {
+        &self.bot_token_env
+    }
+
+    pub fn account_id_env(&self) -> &str {
+        &self.account_id_env
+    }
+
+    pub fn user_id_env(&self) -> &str {
+        &self.user_id_env
+    }
+
+    fn save_cursor(&self, cursor: &str) {
+        if std::fs::create_dir_all(&self.state_dir).is_err() {
+            return;
+        }
+        let data = SyncData {
+            get_updates_buf: cursor.to_string(),
+        };
+        if let Ok(serialized) = serde_json::to_string(&data) {
+            let _ = std::fs::write(self.state_dir.join("sync.json"), serialized);
+        }
+    }
+
+    fn api_url(&self, endpoint: &str) -> String {
+        format!(
+            "{}/ilink/bot/{endpoint}",
+            self.api_base_url.trim_end_matches('/')
+        )
+    }
+
+    fn get_token(&self) -> Option<String> {
+        self.bot_token.read().ok().and_then(|guard| guard.clone())
+    }
+
+    fn set_runtime_error(&self, message: impl Into<String>) {
+        if let Ok(mut runtime) = self.runtime.lock() {
+            runtime.last_error = Some(message.into());
+        }
+    }
+
+    fn is_allowed(&self, user_id: &str) -> bool {
+        self.allowed_users.is_empty()
+            || self
+                .allowed_users
+                .iter()
+                .any(|entry| entry == "*" || entry == user_id)
+    }
+
+    fn update_context_token(&self, user_id: &str, token: &str) {
+        if let Ok(mut tokens) = self.context_tokens.lock() {
+            tokens.insert(user_id.to_string(), token.to_string());
+        }
+    }
+
+    fn get_context_token(&self, user_id: &str) -> Option<String> {
+        self.context_tokens
+            .lock()
+            .ok()
+            .and_then(|tokens| tokens.get(user_id).cloned())
+    }
+
+    async fn ensure_logged_in(&self) -> Result<(), String> {
+        if self.get_token().is_some() {
+            return Ok(());
+        }
+
+        let (token, account_id, user_id) = self.qr_login().await?;
+        if let Ok(mut guard) = self.bot_token.write() {
+            *guard = Some(token.clone());
+        }
+        if let Ok(mut guard) = self.account_id.write() {
+            *guard = Some(account_id.clone());
+        }
+        self.save_account_data(&token, &account_id, user_id.as_deref());
+        if let Ok(mut runtime) = self.runtime.lock() {
+            runtime.connected = true;
+            runtime.started_at.get_or_insert_with(Utc::now);
+            runtime.last_error = None;
+        }
+        Ok(())
+    }
+
+    async fn qr_login(&self) -> Result<(String, String, Option<String>), String> {
+        let response = self
+            .client
+            .get(format!("{}?bot_type=3", self.api_url("get_bot_qrcode")))
+            .timeout(Duration::from_secs(API_TIMEOUT_SECS))
+            .send()
+            .await
+            .map_err(|err| err.to_string())?;
+
+        if !response.status().is_success() {
+            let status = response.status();
+            let body = response.text().await.unwrap_or_default();
+            return Err(format!("WeChat QR code fetch failed {status}: {body}"));
+        }
+
+        let payload: serde_json::Value = response.json().await.map_err(|err| err.to_string())?;
+        let qrcode = payload
+            .get("qrcode")
+            .and_then(|value| value.as_str())
+            .ok_or_else(|| "WeChat QR response missing qrcode".to_string())?
+            .to_string();
+        let qr_image_url = payload
+            .get("qrcode_img_content")
+            .and_then(|value| value.as_str())
+            .unwrap_or("");
+
+        println!("\nWeChat QR login required.");
+        if qr_image_url.is_empty() {
+            println!("Scan payload: {qrcode}");
+        } else {
+            println!("Scan URL: {qr_image_url}");
+            if let Some(qr) = render_terminal_qr(qr_image_url) {
+                println!("\n{qr}\n");
+            }
+        }
+
+        let deadline = Instant::now() + Duration::from_secs(8 * 60);
+        while Instant::now() < deadline {
+            let status_response = match self
+                .client
+                .get(self.api_url("get_qrcode_status"))
+                .query(&[("qrcode", qrcode.as_str())])
+                .timeout(Duration::from_secs(QR_STATUS_TIMEOUT_SECS))
+                .send()
+                .await
+            {
+                Ok(response) => response,
+                Err(err) => {
+                    // The QR-status endpoint behaves like a long poll: timeouts are normal
+                    // while the user hasn't scanned yet, so we keep waiting instead of
+                    // aborting adapter startup.
+                    if err.is_timeout() {
+                        continue;
+                    }
+                    return Err(err.to_string());
+                }
+            };
+
+            if !status_response.status().is_success() {
+                let status = status_response.status();
+                let body = status_response.text().await.unwrap_or_default();
+                return Err(format!("WeChat QR status failed {status}: {body}"));
+            }
+
+            let status_payload: serde_json::Value = status_response
+                .json()
+                .await
+                .map_err(|err| err.to_string())?;
+            match status_payload
+                .get("status")
+                .and_then(|value| value.as_str())
+                .unwrap_or("wait")
+            {
+                "wait" => {}
+                "scaned" => println!("WeChat QR 已扫码，等待手机确认..."),
+                "expired" => return Err("WeChat QR code expired before confirmation".to_string()),
+                "confirmed" => {
+                    let bot_token = status_payload
+                        .get("bot_token")
+                        .and_then(|value| value.as_str())
+                        .ok_or_else(|| "WeChat login missing bot_token".to_string())?
+                        .to_string();
+                    let account_id = status_payload
+                        .get("ilink_bot_id")
+                        .and_then(|value| value.as_str())
+                        .ok_or_else(|| "WeChat login missing ilink_bot_id".to_string())?
+                        .to_string();
+                    let user_id = status_payload
+                        .get("ilink_user_id")
+                        .and_then(|value| value.as_str())
+                        .map(str::to_string);
+                    println!("WeChat connected.");
+                    return Ok((bot_token, account_id, user_id));
+                }
+                other => debug!("Unhandled WeChat QR status: {other}"),
+            }
+
+            tokio::time::sleep(Duration::from_secs(1)).await;
+        }
+
+        Err("Timed out waiting for WeChat QR confirmation".to_string())
+    }
+
+    async fn send_text(&self, user_id: &str, text: &str) -> Result<(), Box<dyn std::error::Error>> {
+        let token = self
+            .get_token()
+            .ok_or_else(|| io_error("WeChat is not logged in"))?;
+        let body = serde_json::json!({
+            "msg": {
+                "from_user_id": "",
+                "to_user_id": user_id,
+                "client_id": format!("openfang-{}", uuid::Uuid::new_v4()),
+                "message_type": 2,
+                "message_state": 2,
+                "item_list": [{
+                    "type": 1,
+                    "text_item": {
+                        "text": text
+                    }
+                }],
+                "context_token": self.get_context_token(user_id).unwrap_or_default()
+            },
+            "base_info": build_base_info()
+        });
+
+        let response = self
+            .client
+            .post(self.api_url("sendmessage"))
+            .headers(build_headers(Some(&token)))
+            .json(&body)
+            .timeout(Duration::from_secs(API_TIMEOUT_SECS))
+            .send()
+            .await?;
+
+        if !response.status().is_success() {
+            let status = response.status();
+            let body = response.text().await.unwrap_or_default();
+            return Err(io_error(format!(
+                "WeChat sendMessage failed {status}: {body}"
+            )));
+        }
+
+        if let Ok(mut runtime) = self.runtime.lock() {
+            runtime.messages_sent += 1;
+        }
+        Ok(())
+    }
+
+    async fn poll_once(&self, tx: &mpsc::Sender<ChannelMessage>) -> Result<(), String> {
+        self.ensure_logged_in().await?;
+        let token = self
+            .get_token()
+            .ok_or_else(|| "WeChat token missing after login".to_string())?;
+        let cursor = self
+            .cursor
+            .lock()
+            .ok()
+            .map(|guard| guard.clone())
+            .unwrap_or_default();
+
+        let response = self
+            .client
+            .post(self.api_url("getupdates"))
+            .headers(build_headers(Some(&token)))
+            .json(&serde_json::json!({
+                "get_updates_buf": cursor,
+                "base_info": build_base_info()
+            }))
+            .timeout(Duration::from_millis(LONG_POLL_TIMEOUT_MS))
+            .send()
+            .await
+            .map_err(|err| err.to_string())?;
+
+        if !response.status().is_success() {
+            let status = response.status();
+            let body = response.text().await.unwrap_or_default();
+            return Err(format!("WeChat getUpdates failed {status}: {body}"));
+        }
+
+        let payload: serde_json::Value = response.json().await.map_err(|err| err.to_string())?;
+        let ret = payload
+            .get("ret")
+            .and_then(|value| value.as_i64())
+            .unwrap_or(0);
+        let errcode = payload
+            .get("errcode")
+            .and_then(|value| value.as_i64())
+            .unwrap_or(0);
+        if ret != 0 || errcode != 0 {
+            let errmsg = payload
+                .get("errmsg")
+                .and_then(|value| value.as_str())
+                .unwrap_or("unknown");
+            return Err(format!(
+                "WeChat getUpdates API error ret={ret} errcode={errcode} errmsg={errmsg}"
+            ));
+        }
+
+        if let Some(next_cursor) = payload
+            .get("get_updates_buf")
+            .and_then(|value| value.as_str())
+            .filter(|value| !value.is_empty())
+        {
+            if let Ok(mut guard) = self.cursor.lock() {
+                *guard = next_cursor.to_string();
+            }
+            self.save_cursor(next_cursor);
+        }
+
+        let messages = payload
+            .get("msgs")
+            .and_then(|value| value.as_array())
+            .cloned()
+            .unwrap_or_default();
+
+        for message in messages {
+            let from_user_id = match message.get("from_user_id").and_then(|value| value.as_str()) {
+                Some(value) if !value.is_empty() => value,
+                _ => continue,
+            };
+
+            if !self.is_allowed(from_user_id) {
+                debug!("Ignoring unauthorized WeChat sender: {from_user_id}");
+                continue;
+            }
+
+            if let Some(context_token) = message
+                .get("context_token")
+                .and_then(|value| value.as_str())
+                .filter(|value| !value.is_empty())
+            {
+                self.update_context_token(from_user_id, context_token);
+            }
+
+            let items = message
+                .get("item_list")
+                .and_then(|value| value.as_array())
+                .cloned()
+                .unwrap_or_default();
+            let text = extract_text_from_items(&items);
+            if text.is_empty() {
+                continue;
+            }
+
+            let platform_message_id = message
+                .get("message_id")
+                .and_then(|value| value.as_u64())
+                .map(|value| value.to_string())
+                .unwrap_or_else(|| format!("wechat-{}", uuid::Uuid::new_v4()));
+            let timestamp_ms = message
+                .get("create_time_ms")
+                .and_then(|value| value.as_i64())
+                .unwrap_or_else(|| Utc::now().timestamp_millis());
+
+            let channel_message = ChannelMessage {
+                channel: ChannelType::Custom("wechat".to_string()),
+                platform_message_id,
+                sender: ChannelUser {
+                    platform_id: from_user_id.to_string(),
+                    display_name: from_user_id.to_string(),
+                    openfang_user: None,
+                },
+                content: ChannelContent::Text(text),
+                target_agent: None,
+                timestamp: chrono::DateTime::<Utc>::from_timestamp_millis(timestamp_ms)
+                    .unwrap_or_else(Utc::now),
+                is_group: false,
+                thread_id: None,
+                metadata: HashMap::new(),
+            };
+
+            if tx.send(channel_message).await.is_err() {
+                break;
+            }
+
+            if let Ok(mut runtime) = self.runtime.lock() {
+                runtime.messages_received += 1;
+                runtime.last_message_at = Some(Utc::now());
+            }
+        }
+
+        Ok(())
+    }
+
+    async fn poll_updates(
+        &self,
+        tx: mpsc::Sender<ChannelMessage>,
+        mut shutdown_rx: watch::Receiver<bool>,
+    ) {
+        let mut backoff_secs = INITIAL_BACKOFF_SECS;
+
+        loop {
+            tokio::select! {
+                _ = shutdown_rx.changed() => {
+                    if *shutdown_rx.borrow() {
+                        break;
+                    }
+                }
+                result = self.poll_once(&tx) => {
+                    match result {
+                        Ok(()) => {
+                            backoff_secs = INITIAL_BACKOFF_SECS;
+                        }
+                        Err(err) => {
+                            let msg = {
+                                let message = err.to_string();
+                                drop(err);
+                                message
+                            };
+                            warn!("WeChat polling error: {msg}");
+                            self.set_runtime_error(msg.clone());
+                            if msg.contains(&SESSION_EXPIRED_ERRCODE.to_string()) {
+                                if let Ok(mut guard) = self.bot_token.write() {
+                                    *guard = None;
+                                }
+                            }
+                            tokio::time::sleep(Duration::from_secs(backoff_secs)).await;
+                            backoff_secs = (backoff_secs * 2).min(MAX_BACKOFF_SECS);
+                        }
+                    }
+                }
+            }
+        }
+    }
+}
+
+#[async_trait]
+impl ChannelAdapter for WeChatAdapter {
+    fn name(&self) -> &str {
+        "wechat"
+    }
+
+    fn channel_type(&self) -> ChannelType {
+        ChannelType::Custom("wechat".to_string())
+    }
+
+    async fn start(
+        &self,
+    ) -> Result<Pin<Box<dyn Stream<Item = ChannelMessage> + Send>>, Box<dyn std::error::Error>>
+    {
+        if let Ok(mut runtime) = self.runtime.lock() {
+            runtime.connected = self.get_token().is_some();
+            runtime.started_at.get_or_insert_with(Utc::now);
+            runtime.last_error = None;
+        }
+
+        let (tx, rx) = mpsc::channel::<ChannelMessage>(256);
+        let adapter = self.clone_for_task();
+        let shutdown_rx = self.shutdown_rx.clone();
+
+        tokio::spawn(async move {
+            info!("WeChat adapter started");
+            adapter.poll_updates(tx, shutdown_rx).await;
+        });
+
+        Ok(Box::pin(tokio_stream::wrappers::ReceiverStream::new(rx)))
+    }
+
+    async fn send(
+        &self,
+        user: &ChannelUser,
+        content: ChannelContent,
+    ) -> Result<(), Box<dyn std::error::Error>> {
+        let text = match content {
+            ChannelContent::Text(text) => text,
+            ChannelContent::Image { url, caption } => match caption {
+                Some(caption) => format!("[image] {caption}\n{url}"),
+                None => format!("[image] {url}"),
+            },
+            ChannelContent::File { url, filename } => format!("[file] {filename}\n{url}"),
+            ChannelContent::FileData { filename, .. } => format!("[file] {filename}"),
+            ChannelContent::Voice {
+                url,
+                duration_seconds,
+            } => format!("[voice {duration_seconds}s] {url}"),
+            ChannelContent::Location { lat, lon } => format!("[location] {lat}, {lon}"),
+            ChannelContent::Command { name, args } => {
+                let suffix = if args.is_empty() {
+                    String::new()
+                } else {
+                    format!(" {}", args.join(" "))
+                };
+                format!("/{name}{suffix}")
+            }
+        };
+
+        self.send_text(&user.platform_id, &text).await
+    }
+
+    async fn stop(&self) -> Result<(), Box<dyn std::error::Error>> {
+        let _ = self.shutdown_tx.send(true);
+        if let Ok(mut runtime) = self.runtime.lock() {
+            runtime.connected = false;
+        }
+        Ok(())
+    }
+
+    fn status(&self) -> ChannelStatus {
+        if let Ok(runtime) = self.runtime.lock() {
+            ChannelStatus {
+                connected: runtime.connected,
+                started_at: runtime.started_at,
+                last_message_at: runtime.last_message_at,
+                messages_received: runtime.messages_received,
+                messages_sent: runtime.messages_sent,
+                last_error: runtime.last_error.clone(),
+            }
+        } else {
+            ChannelStatus::default()
+        }
+    }
+}
+
+fn default_state_dir() -> PathBuf {
+    std::env::var_os("HOME")
+        .map(PathBuf::from)
+        .unwrap_or_else(|| Path::new(".").to_path_buf())
+        .join(".openfang")
+        .join("wechat")
+}
+
+fn build_base_info() -> serde_json::Value {
+    serde_json::json!({
+        "channel_version": env!("CARGO_PKG_VERSION")
+    })
+}
+
+fn render_terminal_qr(data: &str) -> Option<String> {
+    let code = QrCode::new(data.as_bytes()).ok()?;
+    Some(
+        code.render::<unicode::Dense1x2>()
+            .dark_color(unicode::Dense1x2::Dark)
+            .light_color(unicode::Dense1x2::Light)
+            .quiet_zone(true)
+            .build(),
+    )
+}
+
+fn build_headers(token: Option<&str>) -> reqwest::header::HeaderMap {
+    let mut headers = reqwest::header::HeaderMap::new();
+    headers.insert(
+        reqwest::header::CONTENT_TYPE,
+        reqwest::header::HeaderValue::from_static("application/json"),
+    );
+    headers.insert(
+        "AuthorizationType",
+        reqwest::header::HeaderValue::from_static("ilink_bot_token"),
+    );
+    if let Some(token) = token.filter(|value| !value.is_empty()) {
+        if let Ok(value) = reqwest::header::HeaderValue::from_str(&format!("Bearer {token}")) {
+            headers.insert(reqwest::header::AUTHORIZATION, value);
+        }
+    }
+    headers
+}
+
+fn extract_text_from_items(items: &[serde_json::Value]) -> String {
+    for item in items {
+        let item_type = item
+            .get("type")
+            .and_then(|value| value.as_u64())
+            .unwrap_or_default();
+
+        if item_type == 1 {
+            if let Some(text) = item
+                .get("text_item")
+                .and_then(|value| value.get("text"))
+                .and_then(|value| value.as_str())
+            {
+                return text.trim().to_string();
+            }
+        }
+
+        if item_type == 3 {
+            if let Some(text) = item
+                .get("voice_item")
+                .and_then(|value| value.get("text"))
+                .and_then(|value| value.as_str())
+            {
+                let trimmed = text.trim();
+                if !trimmed.is_empty() {
+                    return trimmed.to_string();
+                }
+            }
+        }
+    }
+    String::new()
+}
+
+fn io_error(message: impl Into<String>) -> Box<dyn std::error::Error> {
+    Box::new(std::io::Error::other(message.into()))
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn wechat_extracts_text_from_text_item() {
+        let items = vec![serde_json::json!({
+            "type": 1,
+            "text_item": { "text": "hello wechat" }
+        })];
+        assert_eq!(extract_text_from_items(&items), "hello wechat");
+    }
+
+    #[test]
+    fn wechat_extracts_transcribed_voice_text() {
+        let items = vec![serde_json::json!({
+            "type": 3,
+            "voice_item": { "text": "voice text" }
+        })];
+        assert_eq!(extract_text_from_items(&items), "voice text");
+    }
+
+    #[test]
+    fn wechat_defaults_to_custom_channel_type() {
+        let adapter = WeChatAdapter::new(
+            "WECHAT_BOT_TOKEN".to_string(),
+            "WECHAT_ACCOUNT_ID".to_string(),
+            "WECHAT_USER_ID".to_string(),
+            vec![],
+            None,
+            None,
+            None,
+        );
+        assert_eq!(
+            adapter.channel_type(),
+            ChannelType::Custom("wechat".to_string())
+        );
+    }
+}
diff --git a/crates/openfang-cli/src/main.rs b/crates/openfang-cli/src/main.rs
index a09e012de..4c8b6e0d2 100644
--- a/crates/openfang-cli/src/main.rs
+++ b/crates/openfang-cli/src/main.rs
@@ -2115,18 +2115,14 @@ fn cmd_doctor(json: bool, repair: bool) {
                             ui::check_ok(".env file (permissions fixed to 0600)");
                         }
                         repaired = true;
-                    } else {
-                        if !json {
-                            ui::check_warn(&format!(
-                                ".env file has loose permissions ({:o}), should be 0600",
-                                mode
-                            ));
-                        }
-                    }
-                } else {
-                    if !json {
-                        ui::check_ok(".env file");
+                    } else if !json {
+                        ui::check_warn(&format!(
+                            ".env file has loose permissions ({:o}), should be 0600",
+                            mode
+                        ));
                     }
+                } else if !json {
+                    ui::check_ok(".env file");
                 }
             }
             #[cfg(not(unix))]
diff --git a/crates/openfang-runtime/src/drivers/mod.rs b/crates/openfang-runtime/src/drivers/mod.rs
index b25c6aed5..5e01ea6a5 100644
--- a/crates/openfang-runtime/src/drivers/mod.rs
+++ b/crates/openfang-runtime/src/drivers/mod.rs
@@ -557,6 +557,9 @@ pub fn known_providers() -> &'static [&'static str] {
 #[cfg(test)]
 mod tests {
     use super::*;
+    use std::sync::{LazyLock, Mutex};
+
+    static DRIVER_ENV_TEST_LOCK: LazyLock<Mutex<()>> = LazyLock::new(|| Mutex::new(()));
 
     #[test]
     fn test_provider_defaults_groq() {
@@ -698,6 +701,7 @@ mod tests {
 
     #[test]
     fn test_nvidia_provider_with_env_key() {
+        let _guard = DRIVER_ENV_TEST_LOCK.lock().unwrap();
         // NVIDIA NIM is a known provider — set API key and verify driver creation succeeds.
         let unique_key = "test-nvidia-key-12345";
         std::env::set_var("NVIDIA_API_KEY", unique_key);
@@ -717,7 +721,9 @@ mod tests {
 
     #[test]
     fn test_nvidia_provider_no_key_errors() {
+        let _guard = DRIVER_ENV_TEST_LOCK.lock().unwrap();
         // NVIDIA NIM provider with no API key should error.
+        std::env::remove_var("NVIDIA_API_KEY");
         let config = DriverConfig {
             provider: "nvidia".to_string(),
             api_key: None,
@@ -730,6 +736,7 @@ mod tests {
 
     #[test]
     fn test_custom_provider_key_no_url_helpful_error() {
+        let _guard = DRIVER_ENV_TEST_LOCK.lock().unwrap();
         // Custom provider with key set (via env) but no base_url should give helpful error.
         let unique_key = "test-custom-key-67890";
         std::env::set_var("MYCUSTOM_API_KEY", unique_key);
diff --git a/crates/openfang-types/src/config.rs b/crates/openfang-types/src/config.rs
index c43737211..915753762 100644
--- a/crates/openfang-types/src/config.rs
+++ b/crates/openfang-types/src/config.rs
@@ -1605,6 +1605,8 @@ pub struct ChannelsConfig {
     pub bluesky: Option<BlueskyConfig>,
     /// Feishu/Lark Open Platform configuration (None = disabled).
     pub feishu: Option<FeishuConfig>,
+    /// WeChat iLink Bot configuration (None = disabled).
+    pub wechat: Option<WeChatConfig>,
     /// Revolt (Discord-like) configuration (None = disabled).
     pub revolt: Option<RevoltConfig>,
     // Wave 4 — Enterprise & community channels
@@ -2462,6 +2464,48 @@ impl Default for WeComConfig {
     }
 }
 
+/// WeChat iLink Bot channel adapter configuration.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+#[serde(default)]
+pub struct WeChatConfig {
+    /// Env var name holding the bot token obtained from QR login.
+    pub bot_token_env: String,
+    /// Env var name holding the WeChat account ID obtained from QR login.
+    pub account_id_env: String,
+    /// Env var name holding the WeChat user ID obtained from QR login.
+    pub user_id_env: String,
+    /// WeChat user IDs allowed to interact (empty = allow all).
+    #[serde(default, deserialize_with = "deserialize_string_or_int_vec")]
+    pub allowed_users: Vec<String>,
+    /// Default agent name to route messages to.
+    pub default_agent: Option<String>,
+    /// Override the iLink API base URL.
+    pub api_base_url: Option<String>,
+    /// Override the iLink CDN base URL for future media support.
+    pub cdn_base_url: Option<String>,
+    /// Directory for persisted bot token and sync cursor.
+    pub state_dir: Option<String>,
+    /// Per-channel behavior overrides.
+    #[serde(default)]
+    pub overrides: ChannelOverrides,
+}
+
+impl Default for WeChatConfig {
+    fn default() -> Self {
+        Self {
+            bot_token_env: "WECHAT_BOT_TOKEN".to_string(),
+            account_id_env: "WECHAT_ACCOUNT_ID".to_string(),
+            user_id_env: "WECHAT_USER_ID".to_string(),
+            allowed_users: vec![],
+            default_agent: None,
+            api_base_url: None,
+            cdn_base_url: None,
+            state_dir: None,
+            overrides: ChannelOverrides::default(),
+        }
+    }
+}
+
 /// Revolt (Discord-like) channel adapter configuration.
 #[derive(Debug, Clone, Serialize, Deserialize)]
 #[serde(default)]
@@ -3235,6 +3279,12 @@ impl KernelConfig {
                 ));
             }
         }
+        if self.channels.wechat.is_some() {
+            warnings.push(
+                "WeChat configured: QR login is required on first startup; no env var is needed"
+                    .to_string(),
+            );
+        }
         if let Some(ref rv) = self.channels.revolt {
             if std::env::var(&rv.bot_token_env)
                 .unwrap_or_default()
@@ -3641,6 +3691,17 @@ mod tests {
         assert!(sig.phone_number.is_empty());
     }
 
+    #[test]
+    fn test_wechat_config_defaults() {
+        let wc = WeChatConfig::default();
+        assert_eq!(wc.bot_token_env, "WECHAT_BOT_TOKEN");
+        assert_eq!(wc.account_id_env, "WECHAT_ACCOUNT_ID");
+        assert_eq!(wc.user_id_env, "WECHAT_USER_ID");
+        assert!(wc.allowed_users.is_empty());
+        assert!(wc.default_agent.is_none());
+        assert!(wc.api_base_url.is_none());
+    }
+
     #[test]
     fn test_matrix_config_defaults() {
         let mx = MatrixConfig::default();
@@ -3685,6 +3746,7 @@ mod tests {
         let config = KernelConfig {
             channels: ChannelsConfig {
                 whatsapp: Some(WhatsAppConfig::default()),
+                wechat: Some(WeChatConfig::default()),
                 signal: Some(SignalConfig::default()),
                 matrix: Some(MatrixConfig::default()),
                 email: Some(EmailConfig::default()),
@@ -3693,6 +3755,7 @@ mod tests {
             ..Default::default()
         };
         assert!(config.channels.whatsapp.is_some());
+        assert!(config.channels.wechat.is_some());
         assert!(config.channels.signal.is_some());
         assert!(config.channels.matrix.is_some());
         assert!(config.channels.email.is_some());
diff --git a/openfang.toml.example b/openfang.toml.example
index e6d4c2b66..120020552 100644
--- a/openfang.toml.example
+++ b/openfang.toml.example
@@ -41,6 +41,12 @@ listen_addr = "127.0.0.1:4200"           # OFP listen address
 # bot_token_env = "SLACK_BOT_TOKEN"
 # app_token_env = "SLACK_APP_TOKEN"
 
+# [wechat]
+# allowed_users = []                      # Empty = allow all
+# default_agent = "assistant"
+# state_dir = "~/.openfang/wechat"        # Persist QR-login token and sync cursor
+# api_base_url = "https://ilinkai.weixin.qq.com"
+
 # MCP server connections
 # [[mcp_servers]]
 # name = "filesystem"