foxclaw 0.1.0 → 0.1.2

package/python/foxclaw/channels/signing.py

@@ -0,0 +1,187 @@
+"""渠道出站签名 / 入站验签(HMAC-SHA256,时间窗 + nonce 防重放)。
+
+**为什么需要**:渠道消息目前是"明文 HTTPS + Bearer token"。TLS 只保护链路,保护不了
+两端之间被中间人代理/日志重放的**消息语义**:网关收到一条 `{"conversation":…, "text":
+"转账 5000"}` 无法判断它真是 Foxclaw 发的、还是别人照着抓包重放的。
+
+**为什么只在「我们两端都控制」的方向签**:Telegram/Discord/飞书/微信的 API 不验我们的
+签名 —— 给它们的请求加 `X-Foxclaw-Signature` 纯属表演(它们会忽略,攻击者也不需要
+伪造,拿 bot token 直连即可)。真正有威胁的是 Foxclaw ↔ 自建网关(OpenClaw 桥)这条
+链路:两端都是自己的代码,共享密钥可落地,签名才有验证方。
+
+**签名结构**(canonical string,避免"把 header 挪来挪去"各种拼接口径不一致):
+
+    v1 \n {timestamp} \n {nonce} \n {sha256(body) 的 hex}
+
+- `body` 摘要进签名 → 改正文即失效(不只是改 header 才算篡改);
+- `timestamp` 进签名 → 超出容差(默认 300s)直接拒,缩小重放窗口;
+- `nonce` 进签名 + 验方 `ReplayGuard` 记账 → 窗口内也不能重放同一请求;
+- `v1` 前缀 → 将来换算法可并存,不炸老客户端。
+
+配置:`FOXCLAW_CHANNEL_SIGNING_SECRET`(共享密钥)、可选
+`FOXCLAW_CHANNEL_SIGNING_KEY_ID`(轮换时对账用)。未配置 = 不签(opt-in);
+一旦配置,签名失败就**不发**(fail-closed,绝不静默降级成明文)。
+"""
+from __future__ import annotations
+
+import hashlib
+import hmac
+import os
+import secrets
+import threading
+import time
+from typing import Mapping, Optional, Tuple
+
+SIGN_VERSION = "v1"
+SIGNATURE_HEADER = "X-Foxclaw-Signature"
+TIMESTAMP_HEADER = "X-Foxclaw-Timestamp"
+NONCE_HEADER = "X-Foxclaw-Nonce"
+KEY_ID_HEADER = "X-Foxclaw-Key-Id"
+
+ENV_SECRET = "FOXCLAW_CHANNEL_SIGNING_SECRET"
+ENV_KEY_ID = "FOXCLAW_CHANNEL_SIGNING_KEY_ID"
+
+DEFAULT_TOLERANCE = 300.0     # 秒;超过即判过期(时钟漂移容忍)
+
+
+def body_digest(body: bytes) -> str:
+    """正文摘要(绑定进签名,防正文被改)。"""
+    return hashlib.sha256(body or b"").hexdigest()
+
+
+def canonical(ts: str, nonce: str, body: bytes) -> bytes:
+    """签名原文。字段顺序/分隔符改动 = 破坏兼容,测试里锁死。"""
+    return f"{SIGN_VERSION}\n{ts}\n{nonce}\n{body_digest(body)}".encode()
+
+
+def sign(secret: str, ts: str, nonce: str, body: bytes) -> str:
+    """计算签名值(hex)。"""
+    return hmac.new((secret or "").encode("utf-8"),
+                    canonical(ts, nonce, body), hashlib.sha256).hexdigest()
+
+
+class ReplayGuard:
+    """验方 nonce 记账:同一 nonce 在 TTL 内只接受一次。
+
+    线程安全 + 有界(超过上限丢最旧),避免被刷爆内存:nonce 是攻击者可控输入,
+    无界集合等于给了一个内存耗尽面。
+    """
+
+    def __init__(self, ttl: float = DEFAULT_TOLERANCE, max_entries: int = 4096):
+        self.ttl = float(ttl)
+        self.max_entries = max(16, int(max_entries))
+        self._seen: dict[str, float] = {}      # nonce -> 首次见到的时间
+        self._lock = threading.Lock()
+
+    def purge(self, now: float = None) -> int:
+        """清掉过期 nonce,返回清理条数。"""
+        cut = (now if now is not None else time.time()) - self.ttl
+        with self._lock:
+            dead = [k for k, t in self._seen.items() if t < cut]
+            for k in dead:
+                self._seen.pop(k, None)
+        return len(dead)
+
+    def seen(self, nonce: str, now: float = None) -> bool:
+        """见过 → True(**这是重放**);没见过则登记并返回 False。"""
+        if not nonce:
+            return True                        # 空 nonce 一律当重放/fail-closed
+        now = now if now is not None else time.time()
+        with self._lock:
+            cut = now - self.ttl
+            dead = [k for k, t in self._seen.items() if t < cut]
+            for k in dead:
+                self._seen.pop(k, None)
+            if nonce in self._seen:
+                return True
+            if len(self._seen) >= self.max_entries:
+                oldest = min(self._seen.items(), key=lambda kv: kv[1])[0]
+                self._seen.pop(oldest, None)
+            self._seen[nonce] = now
+            return False
+
+    def __len__(self) -> int:
+        return len(self._seen)
+
+
+class OutboundSigner:
+    """出站签名器:给一次请求生成 4 个 header。"""
+
+    def __init__(self, secret: str, key_id: str = ""):
+        self.secret = secret or ""
+        self.key_id = key_id or ""
+
+    @property
+    def enabled(self) -> bool:
+        return bool(self.secret)
+
+    def headers(self, body: bytes, nonce: str = "", now: float = None) -> dict:
+        """生成签名头。未配置密钥直接抛错(fail-closed:调用方必须先判 `enabled`)。"""
+        if not self.enabled:
+            raise ValueError("未配置渠道签名密钥(FOXCLAW_CHANNEL_SIGNING_SECRET)")
+        ts = str(int(now if now is not None else time.time()))
+        nonce = nonce or secrets.token_hex(12)
+        h = {
+            SIGNATURE_HEADER: f"{SIGN_VERSION}={sign(self.secret, ts, nonce, body)}",
+            TIMESTAMP_HEADER: ts,
+            NONCE_HEADER: nonce,
+        }
+        if self.key_id:
+            h[KEY_ID_HEADER] = self.key_id
+        return h
+
+
+def _header(headers: Mapping, name: str) -> str:
+    """大小写无关取 header(HTTP header 名不区分大小写,不同框架给的大小写不同)。"""
+    if not headers:
+        return ""
+    if name in headers:
+        return str(headers[name] or "")
+    low = name.lower()
+    for k, v in headers.items():
+        if str(k).lower() == low:
+            return str(v or "")
+    return ""
+
+
+def verify(headers: Mapping, body: bytes, secret: str,
+           tolerance: float = DEFAULT_TOLERANCE, replay: ReplayGuard = None,
+           now: float = None) -> Tuple[bool, str]:
+    """验签。返回 (是否通过, 原因码)。
+
+    原因码:``ok`` / ``missing_secret`` / ``missing_header`` / ``bad_version`` /
+    ``expired`` / ``replay`` / ``bad_signature``(排错时能一眼看出是哪一层挂了)。
+    ``replay`` 传 None 则**不做**防重放(只验真伪),由调用方决定是否记账。
+    """
+    if not secret:
+        return False, "missing_secret"
+    sig_raw = _header(headers, SIGNATURE_HEADER)
+    ts = _header(headers, TIMESTAMP_HEADER)
+    nonce = _header(headers, NONCE_HEADER)
+    if not sig_raw or not ts or not nonce:
+        return False, "missing_header"
+    ver, _, sig = sig_raw.partition("=")
+    if ver != SIGN_VERSION or not sig:
+        return False, "bad_version"
+    try:
+        ts_f = float(ts)
+    except (TypeError, ValueError):
+        return False, "bad_version"
+    now = now if now is not None else time.time()
+    if abs(now - ts_f) > float(tolerance):
+        return False, "expired"
+    expect = sign(secret, ts, nonce, body)
+    if not hmac.compare_digest(expect, sig):
+        return False, "bad_signature"
+    if replay is not None and replay.seen(nonce, now=now):
+        return False, "replay"
+    return True, "ok"
+
+
+def from_env(env: Mapping = None) -> Optional[OutboundSigner]:
+    """按环境变量构造签名器;未配置密钥 → None(不签,opt-in)。"""
+    env = env if env is not None else os.environ
+    secret = (env.get(ENV_SECRET) or "").strip()
+    if not secret:
+        return None
+    return OutboundSigner(secret, key_id=(env.get(ENV_KEY_ID) or "").strip())

package/python/foxclaw/channels/telegram.py

@@ -0,0 +1,121 @@
+"""
+Foxclaw Channels — Telegram 适配器
+
+用 Telegram 官方 Bot API(api.telegram.org),完全合规:
+  · 接入:在 @BotFather 创建 Bot,拿到 bot token
+  · 收消息:getUpdates 长轮询(或 webhook,此处用轮询,本地最易跑通)
+  · 发消息:sendMessage
+
+凭证(bot token)由宿主注入,不硬编码。借鉴 OpenClaw 的 normalize/send 对称结构。
+"""
+from __future__ import annotations
+from typing import Optional
+from . import ChannelAdapter, InboundMessage, OutboundMessage, SendResult
+
+TELEGRAM_API = "https://api.telegram.org"
+
+
+class TelegramAdapter(ChannelAdapter):
+    CHANNEL = "telegram"
+
+    def __init__(self, bot_token: str, on_message=None, timeout: float = 30.0):
+        super().__init__(on_message=on_message)
+        self.bot_token = bot_token
+        self.timeout = timeout
+        self._offset = 0          # getUpdates 增量游标(避免重复拉取)
+
+    @property
+    def _base(self) -> str:
+        return f"{TELEGRAM_API}/bot{self.bot_token}"
+
+    def normalize(self, raw: dict) -> Optional[InboundMessage]:
+        """Telegram update → 标准 InboundMessage。非文本消息返回 None。"""
+        msg = raw.get("message") or raw.get("edited_message")
+        if not msg or "text" not in msg:
+            return None       # 非文本消息(贴纸/图片/已读等)暂忽略
+        chat = msg.get("chat", {})
+        sender = msg.get("from", {})
+        chat_type = chat.get("type", "private")
+        return InboundMessage(
+            channel=self.CHANNEL,
+            message_id=str(msg.get("message_id", "")),
+            text=msg.get("text", ""),
+            sender_id=str(sender.get("id", "")),
+            sender_name=(sender.get("username")
+                         or sender.get("first_name", "") or "").strip(),
+            conversation_id=str(chat.get("id", "")),
+            is_group=chat_type in ("group", "supergroup"),
+            timestamp=float(msg.get("date", 0)),
+            raw=raw)
+
+    def send(self, msg: OutboundMessage) -> SendResult:
+        """通过 sendMessage 发出。"""
+        try:
+            import httpx
+        except ImportError:
+            return SendResult(False, error="缺少 httpx 依赖")
+        if not self.bot_token:
+            return SendResult(False, error="未配置 bot token")
+        payload = {"chat_id": msg.conversation_id, "text": msg.text}
+        if msg.reply_to:
+            payload["reply_to_message_id"] = msg.reply_to
+        try:
+            with httpx.Client() as client:
+                resp = client.post(f"{self._base}/sendMessage",
+                                   json=payload, timeout=self.timeout)
+        except Exception as e:
+            return SendResult(False, error=f"发送失败: {e}")
+        if resp.status_code >= 400:
+            return SendResult(False, error=f"Telegram API HTTP {resp.status_code}: {resp.text[:200]}")
+        data = resp.json()
+        if not data.get("ok"):
+            return SendResult(False, error=f"Telegram: {data.get('description','未知错误')}")
+        return SendResult(True, message_id=str(data["result"].get("message_id", "")))
+
+    def poll_once(self) -> list[InboundMessage]:
+        """拉取一批新消息(getUpdates 长轮询一次)。返回标准化后的消息列表。
+
+        宿主可在循环里反复调用实现持续接收;本地最易跑通的方式。
+        """
+        try:
+            import httpx
+        except ImportError:
+            return []
+        if not self.bot_token:
+            return []
+        try:
+            with httpx.Client() as client:
+                resp = client.get(f"{self._base}/getUpdates",
+                                  params={"offset": self._offset, "timeout": 25},
+                                  timeout=self.timeout + 5)
+        except Exception:
+            return []
+        if resp.status_code != 200:
+            return []
+        data = resp.json()
+        if not data.get("ok"):
+            return []
+        out = []
+        for update in data.get("result", []):
+            # 推进游标:下次从最大 update_id + 1 开始,避免重复
+            uid = update.get("update_id", 0)
+            if uid >= self._offset:
+                self._offset = uid + 1
+            inbound = self.handle_raw(update)   # normalize + 触发 on_message
+            if inbound:
+                out.append(inbound)
+        return out
+
+    def verify_token(self) -> SendResult:
+        """getMe 验证 bot token 是否有效(本地接入时先确认凭证)。"""
+        try:
+            import httpx
+            with httpx.Client() as client:
+                resp = client.get(f"{self._base}/getMe", timeout=self.timeout)
+            data = resp.json()
+            if data.get("ok"):
+                bot = data["result"]
+                return SendResult(True, message_id=bot.get("username", ""))
+            return SendResult(False, error=data.get("description", "token 无效"))
+        except Exception as e:
+            return SendResult(False, error=str(e))

package/python/foxclaw/channels/weixin.py

@@ -0,0 +1,225 @@
+"""
+Foxclaw Channels — 微信 (Weixin) 适配器
+
+照腾讯官方开源插件 Tencent/openclaw-weixin 公开的后端 API 协议(iLink Bot API)
+用 Python 实现。该协议由腾讯官方文档化,README 明确支持开发者用自己的后端对接,
+故这是官方公开协议的合规实现,非逆向。
+
+接入模型(与飞书/Telegram 又不同,不套同一模子):
+  · 网关:https://ilinkai.weixin.qq.com,端点前缀 ilink/bot/
+  · 鉴权:AuthorizationType: ilink_bot_token + Authorization: Bearer <token>
+          + X-WECHAT-UIN(随机 uint32 → 十进制串 → base64)
+  · 收消息:getupdates 长轮询(带 get_updates_buf 游标)
+  · 发消息:sendmessage(带 to_user_id + context_token + item_list)
+  · 每个请求体带 base_info: {channel_version, bot_agent}
+
+凭证(token)由宿主注入:用户需先用 openclaw 官方 CLI 扫码登录拿到 token
+(扫码登录这一步在微信侧,本适配器不复现登录,只复现已登录后的消息收发协议)。
+"""
+from __future__ import annotations
+import base64
+import secrets
+from typing import Optional
+from . import ChannelAdapter, InboundMessage, OutboundMessage, SendResult
+
+# 官方网关与端点(来自 Tencent/openclaw-weixin 源码 src/auth/accounts.ts)
+WEIXIN_BASE_URL = "https://ilinkai.weixin.qq.com"
+EP_GET_UPDATES = "ilink/bot/getupdates"
+EP_SEND_MESSAGE = "ilink/bot/sendmessage"
+EP_GET_CONFIG = "ilink/bot/getconfig"
+EP_SEND_TYPING = "ilink/bot/sendtyping"
+
+# 消息 item 类型(来自 README MessageItem 表)
+ITEM_TEXT = 1
+ITEM_IMAGE = 2
+ITEM_VOICE = 3
+ITEM_FILE = 4
+ITEM_VIDEO = 5
+# message_type
+MSG_FROM_USER = 1
+MSG_FROM_BOT = 2
+
+
+class WeixinAdapter(ChannelAdapter):
+    CHANNEL = "weixin"
+
+    def __init__(self, token: str, base_url: str = WEIXIN_BASE_URL,
+                 bot_agent: str = "Foxclaw", channel_version: str = "2.4.3",
+                 ilink_app_id: str = "bot", on_message=None,
+                 long_poll_timeout_ms: int = 35000, timeout: float = 40.0):
+        super().__init__(on_message=on_message)
+        self.token = token
+        self.base_url = base_url.rstrip("/")
+        self.bot_agent = bot_agent
+        self.channel_version = channel_version
+        self.ilink_app_id = ilink_app_id
+        self.long_poll_timeout_ms = long_poll_timeout_ms
+        self.timeout = timeout
+        self._cursor = ""        # get_updates_buf 同步游标
+        # 记录每个用户最近的 context_token(回复时必须带回)
+        self._context_tokens: dict[str, str] = {}
+
+    @staticmethod
+    def _build_client_version(version: str) -> int:
+        """照官方 buildClientVersion: (major<<16)|(minor<<8)|patch。"""
+        parts = (version.split(".") + ["0", "0", "0"])[:3]
+        try:
+            major, minor, patch = (int(p) for p in parts)
+        except ValueError:
+            major = minor = patch = 0
+        return ((major & 0xFF) << 16) | ((minor & 0xFF) << 8) | (patch & 0xFF)
+
+    # ── 鉴权头(照官方 buildHeaders)──────────────────────
+    @staticmethod
+    def _random_wechat_uin() -> str:
+        """X-WECHAT-UIN: 随机 uint32 → 十进制字符串 → base64。"""
+        uint32 = int.from_bytes(secrets.token_bytes(4), "big")
+        return base64.b64encode(str(uint32).encode()).decode()
+
+    def _headers(self) -> dict:
+        headers = {
+            "Content-Type": "application/json",
+            "AuthorizationType": "ilink_bot_token",
+            "X-WECHAT-UIN": self._random_wechat_uin(),
+            "iLink-App-Id": self.ilink_app_id,
+            "iLink-App-ClientVersion": str(self._build_client_version(self.channel_version)),
+        }
+        if self.token.strip():
+            headers["Authorization"] = f"Bearer {self.token.strip()}"
+        return headers
+
+    def _base_info(self) -> dict:
+        return {"channel_version": self.channel_version, "bot_agent": self.bot_agent}
+
+    def _post(self, endpoint: str, body: dict, timeout: float = None):
+        import httpx
+        url = f"{self.base_url}/{endpoint}"
+        payload = {**body, "base_info": self._base_info()}
+        with httpx.Client() as client:
+            resp = client.post(url, json=payload, headers=self._headers(),
+                               timeout=timeout or self.timeout)
+        return resp
+
+    # ── 入站:getUpdates 长轮询 ────────────────────────────
+    def poll_once(self) -> list[InboundMessage]:
+        """长轮询拉一批新消息。宿主在循环里反复调用即可持续接收。"""
+        try:
+            import httpx  # noqa
+        except ImportError:
+            return []
+        if not self.token:
+            return []
+        try:
+            resp = self._post(EP_GET_UPDATES,
+                              {"get_updates_buf": self._cursor},
+                              timeout=self.long_poll_timeout_ms / 1000 + 5)
+        except Exception:
+            return []        # 长轮询超时/中断 → 空,下次重试
+        if resp.status_code != 200:
+            return []
+        try:
+            data = resp.json()
+        except Exception:
+            return []
+        if data.get("ret") != 0:
+            return []        # errcode -14 = 会话超时,需重新登录
+        # 推进游标
+        new_buf = data.get("get_updates_buf")
+        if new_buf is not None:
+            self._cursor = new_buf
+        out = []
+        for raw_msg in data.get("msgs", []):
+            inbound = self._normalize_msg(raw_msg)
+            if inbound:
+                if self.on_message:
+                    self.on_message(inbound)
+                out.append(inbound)
+        return out
+
+    def normalize(self, raw: dict) -> Optional[InboundMessage]:
+        """单条 WeixinMessage → 标准 InboundMessage(供 handle_raw 用)。"""
+        return self._normalize_msg(raw)
+
+    def _normalize_msg(self, msg: dict) -> Optional[InboundMessage]:
+        # 只处理用户发来的消息(message_type=1),忽略 bot 自己的回显
+        if msg.get("message_type") not in (None, MSG_FROM_USER):
+            return None
+        # 从 item_list 提取文本
+        text = ""
+        for item in msg.get("item_list", []) or []:
+            if item.get("type") == ITEM_TEXT and item.get("text_item"):
+                text += item["text_item"].get("text", "")
+        if not text:
+            return None       # 非文本(图片/语音等)暂忽略
+        from_user = str(msg.get("from_user_id", ""))
+        ctx = msg.get("context_token", "")
+        if from_user and ctx:
+            self._context_tokens[from_user] = ctx   # 记住,回复时带回
+        return InboundMessage(
+            channel=self.CHANNEL,
+            message_id=str(msg.get("message_id", "")),
+            text=text,
+            sender_id=from_user,
+            sender_name="",
+            conversation_id=str(msg.get("session_id", "") or from_user),
+            is_group=False,    # 个人号 DM;群聊当前插件能力未公开
+            timestamp=float(msg.get("create_time_ms", 0)) / 1000 or 0.0,
+            raw=msg)
+
+    # ── 出站:sendMessage ──────────────────────────────────
+    def send(self, msg: OutboundMessage) -> SendResult:
+        """发文本消息。conversation_id 作为 to_user_id;context_token 从记录里取或由 extra 传入。"""
+        try:
+            import httpx  # noqa
+        except ImportError:
+            return SendResult(False, error="缺少 httpx 依赖")
+        if not self.token:
+            return SendResult(False, error="未配置微信 token(需先扫码登录)")
+        to_user = msg.conversation_id
+        ctx = msg.extra.get("context_token") or self._context_tokens.get(to_user, "")
+        body = {
+            "msg": {
+                "to_user_id": to_user,
+                "context_token": ctx,
+                "item_list": [
+                    {"type": ITEM_TEXT, "text_item": {"text": msg.text}}
+                ],
+            }
+        }
+        try:
+            resp = self._post(EP_SEND_MESSAGE, body)
+        except Exception as e:
+            return SendResult(False, error=f"微信发送失败: {e}")
+        if resp.status_code >= 400:
+            return SendResult(False, error=f"微信 API HTTP {resp.status_code}: {resp.text[:200]}")
+        try:
+            data = resp.json()
+        except Exception:
+            data = {}
+        if data.get("ret", 0) != 0:
+            return SendResult(False, error=f"微信: ret={data.get('ret')} {data.get('errmsg','')}")
+        return SendResult(True)
+
+    def reply(self, inbound: InboundMessage, text: str) -> SendResult:
+        """便捷回复:自动带回该用户的 context_token(微信要求回复必须带)。"""
+        ctx = inbound.raw.get("context_token", "") if inbound.raw else ""
+        return self.send(OutboundMessage(
+            conversation_id=inbound.conversation_id, text=text,
+            extra={"context_token": ctx} if ctx else {}))
+
+    def verify_token(self, ilink_user_id: str = "") -> SendResult:
+        """探测 token 是否有效(调 getconfig)。
+
+        官方 getconfig 需要 ilink_user_id;无则取最近一个已记录的用户。
+        若从未收到过消息且未传 user_id,无法探测(返回提示)。
+        """
+        user_id = ilink_user_id or next(iter(self._context_tokens), "")
+        if not user_id:
+            return SendResult(False,
+                              error="需提供 ilink_user_id(或先收到一条消息)才能探测")
+        try:
+            resp = self._post(EP_GET_CONFIG, {"ilink_user_id": user_id})
+            ok = resp.status_code == 200 and resp.json().get("ret") == 0
+            return SendResult(ok, error="" if ok else "token 无效或已过期(需重新扫码登录)")
+        except Exception as e:
+            return SendResult(False, error=str(e))

package/python/foxclaw/cli.py

@@ -0,0 +1,154 @@
+"""命令行入口 `foxclaw`。
+
+与 PyPI 上 `foxclaw` 0.1.0 占位包发布的入口保持一致：包名 `foxclaw`,
+命令名 `foxclaw`。
+
+    foxclaw                # 打印版本与提示
+    foxclaw serve          # 启动 API 服务(默认 http://127.0.0.1:8000)
+    foxclaw config check   # 检查 .env / 环境变量:类型写错、拼错的键、互相矛盾的组合
+    foxclaw config show     # 打印当前生效配置(密钥默认脱敏)
+    foxclaw --version      # 打印版本
+
+`serve` 用字符串目标 `foxclaw.api:app` 交给 uvicorn 导入,避免 CLI 进程
+自己先把整个应用栈加载一遍(含 HKC/HMR 与模型);`--reload` 时 uvicorn 也需要
+字符串目标才能重建子进程。
+"""
+
+from __future__ import annotations
+
+import argparse
+import os
+import sys
+from pathlib import Path
+
+from foxclaw import __version__
+
+APP_TARGET = "foxclaw.api:app"
+
+
+def _repo_root() -> Path:
+    """仓库根目录(可编辑安装时即包含 foxclaw/ 的那一层)。"""
+    return Path(__file__).resolve().parents[1]
+
+
+def _cmd_serve(args: argparse.Namespace) -> int:
+    from foxclaw.core import settings
+
+    # 启动前先查配置:类型写错的值今天会崩在很远的地方(uvicorn 40 行 traceback 中间的
+    # `int()`),用户看不出是自己 .env 写错了。这里提前拦下并说清怎么改。
+    issues = settings.check()
+    fatal = settings.fatal_issues(issues)
+    if fatal:
+        print(settings.format_issues(issues), file=sys.stderr)
+        print("\n以上配置会让启动直接失败,已中止。改好后重试。", file=sys.stderr)
+        return 2
+    if issues:
+        # 不影响启动的问题(可疑但能跑)只提醒一次,不拦
+        print(settings.format_issues(issues, limit=8), file=sys.stderr)
+        print("(以上不阻断启动;`foxclaw config check` 看完整诊断)", file=sys.stderr)
+
+    import uvicorn
+
+    kwargs: dict[str, object] = {
+        "host": args.host,
+        "port": args.port,
+        "log_level": args.log_level,
+    }
+    if args.reload:
+        # 只监听源码目录,避免 vendor/ 与测试临时文件触发重启
+        kwargs["reload"] = True
+        kwargs["reload_dirs"] = [str(_repo_root() / "foxclaw")]
+    uvicorn.run(APP_TARGET, **kwargs)
+    return 0
+
+
+def _cmd_config_check(args: argparse.Namespace) -> int:
+    from foxclaw.core import settings
+
+    issues = settings.check()
+    if args.json:
+        import json as _json
+        print(_json.dumps(
+            [{"level": i.level, "code": i.code, "name": i.name,
+              "message": i.message, "hint": i.hint} for i in issues],
+            ensure_ascii=False, indent=2))
+    else:
+        print(settings.format_issues(issues))
+    return 1 if any(i.level == "error" for i in issues) else 0
+
+
+def _cmd_config_show(args: argparse.Namespace) -> int:
+    from foxclaw.core import settings
+
+    current = ""
+    for opt in settings.SPECS:
+        if opt.group != current:
+            current = opt.group
+            print(f"[{current}]")
+        raw = os.environ.get(opt.name)
+        if raw is None or raw.strip() == "":
+            shown = f"{settings.mask(opt.default) if opt.secret else opt.default}" \
+                if opt.default not in ("", None) else "(未设置)"
+            suffix = "  默认"
+        else:
+            shown = settings.mask(raw) if (opt.secret and not args.reveal) else raw
+            suffix = "  已设置"
+        print(f"  {opt.name} = {shown}{suffix}")
+    return 0
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="foxclaw",
+        description="Foxclaw —— 认知 Agent 操作系统",
+    )
+    parser.add_argument(
+        "-V",
+        "--version",
+        action="version",
+        version=f"foxclaw {__version__}",
+    )
+
+    subparsers = parser.add_subparsers(dest="command", metavar="<command>")
+
+    serve = subparsers.add_parser("serve", help="启动 API 服务")
+    serve.add_argument("--host", default="127.0.0.1", help="监听地址,默认仅本机回环")
+    serve.add_argument("--port", type=int, default=8000, help="监听端口,默认 8000")
+    serve.add_argument("--reload", action="store_true", help="改代码自动重启(开发用)")
+    serve.add_argument("--log-level", default="info", help="uvicorn 日志级别")
+    serve.set_defaults(handler=_cmd_serve)
+
+    config = subparsers.add_parser("config", help="查看/检查配置(.env 与环境变量)")
+    config_sub = config.add_subparsers(dest="config_action", metavar="<action>")
+
+    c_check = config_sub.add_parser(
+        "check", help="检查配置:类型、取值范围、拼错的键、互相矛盾的组合")
+    c_check.add_argument("--json", action="store_true", help="输出 JSON(便于脚本/前端消费)")
+    c_check.set_defaults(handler=_cmd_config_check)
+
+    c_show = config_sub.add_parser("show", help="打印当前生效配置")
+    c_show.add_argument("--reveal", action="store_true",
+                        help="显示密钥原文(默认脱敏;别在截图/日志里用)")
+    c_show.set_defaults(handler=_cmd_config_show)
+
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+
+    handler = getattr(args, "handler", None)
+    if handler is None:
+        if getattr(args, "command", None) == "config":
+            print("用法:`foxclaw config check` 或 `foxclaw config show`")
+            return 2
+        print(f"foxclaw {__version__}")
+        print("用 `foxclaw serve` 启动本地服务;`foxclaw config check` 检查配置;"
+              "`foxclaw --help` 查看全部子命令。")
+        return 0
+    return int(handler(args))
+
+
+if __name__ == "__main__":
+    sys.exit(main())