fix: add optional CLAWBOT_SECRET guard to clawbot endpoint

Add X-ClawBot-Secret header validation to /api/v1/clawbot/message.
When CLAWBOT_SECRET env var is set, callers must send the matching
value in the header; unmatched requests receive 401.
If CLAWBOT_SECRET is not set, the endpoint remains open (backwards
compatible with existing deployments).

Also document CLAWBOT_SECRET in .env.example and add two tests
covering the auth-pass and auth-reject paths.

Author: Copilot

.env.example

@@ -446,6 +446,13 @@ WEBUI_AUTO_BUILD=true
 ADMIN_AUTH_ENABLED=false
 # ADMIN_SESSION_MAX_AGE_HOURS=24  # Session 有效期（小时）
 
+# ===========================================
+# ClawBot API 接入保护（可选）
+# ===========================================
+# 设置后，调用 /api/v1/clawbot/message 时必须在请求头携带 X-ClawBot-Secret: <值>
+# 不设置或留空则端点对所有请求开放（适合内网部署或已有其他访问控制的场景）
+# CLAWBOT_SECRET=your_shared_secret_here
+
 # ===========================================
 # 图片识别股票代码（设置页「从图片添加」）
 # ===========================================

api/v1/endpoints/clawbot.py

@@ -9,7 +9,9 @@
 import uuid
 from typing import Any, Dict, List, Literal, Optional
 
-from fastapi import APIRouter, HTTPException
+import os
+
+from fastapi import APIRouter, HTTPException, Request
 from pydantic import BaseModel, Field
 
 from api.v1.endpoints.agent import _build_executor
@@ -450,16 +452,24 @@ def _run_agent(request: ClawBotMessageRequest) -> ClawBotMessageResponse:
     responses={
         200: {"description": "ClawBot 文本响应", "model": ClawBotMessageResponse},
         400: {"description": "请求参数错误或能力不可用", "model": ErrorResponse},
+        401: {"description": "X-ClawBot-Secret 校验失败（仅在配置 CLAWBOT_SECRET 时生效）", "model": ErrorResponse},
         422: {"description": "请求体验证失败", "model": ErrorResponse},
         500: {"description": "分析或 Agent 执行失败", "model": ErrorResponse},
     },
     summary="ClawBot 文本桥接",
     description="为微信/openclaw ClawBot 提供稳定的文本入参与文本出参桥接层。",
 )
-def handle_clawbot_message(request: ClawBotMessageRequest) -> ClawBotMessageResponse:
+def handle_clawbot_message(http_request: Request, request: ClawBotMessageRequest) -> ClawBotMessageResponse:
     """
     Bridge WeChat/openclaw ClawBot requests to existing analysis/agent capabilities.
     """
+    # Optional shared-secret guard: set CLAWBOT_SECRET to protect the endpoint.
+    # If configured, callers must send the matching value in X-ClawBot-Secret.
+    clawbot_secret = os.environ.get("CLAWBOT_SECRET", "").strip()
+    if clawbot_secret:
+        provided = http_request.headers.get("X-ClawBot-Secret", "")
+        if provided != clawbot_secret:
+            _raise_clawbot_error(401, "unauthorized", "X-ClawBot-Secret 校验失败")
     try:
         if not request.message.strip():
             _raise_clawbot_error(

tests/test_clawbot_api.py

@@ -85,6 +85,7 @@ def test_clawbot_message_routes_to_analysis_and_formats_text():
         return_value=analysis_result,
     ) as handle_analysis:
         response = handle_clawbot_message(
+            _build_request(),
             ClawBotMessageRequest(message="帮我分析贵州茅台", mode="analysis")
         )
 
@@ -114,6 +115,7 @@ def test_clawbot_message_routes_to_agent_with_stable_session_id():
     with patch("api.v1.endpoints.clawbot.get_config", return_value=config), \
          patch("api.v1.endpoints.clawbot._build_executor", return_value=executor):
         response = handle_clawbot_message(
+            _build_request(),
             ClawBotMessageRequest(
                 message="用缠论分析 600519",
                 mode="agent",
@@ -148,6 +150,7 @@ def test_clawbot_message_auto_mode_falls_back_to_agent_for_plain_english_text():
          patch("api.v1.endpoints.clawbot.CommandDispatcher._resolve_stock_code_from_text", return_value=None), \
          patch("api.v1.endpoints.clawbot._handle_sync_analysis") as handle_analysis:
         response = handle_clawbot_message(
+            _build_request(),
             ClawBotMessageRequest(message="I need advice", mode="auto", user_id="wx_user_002")
         )
 
@@ -173,6 +176,7 @@ def test_clawbot_message_auto_mode_falls_back_to_agent_for_uppercase_english_tex
          patch("api.v1.endpoints.clawbot.CommandDispatcher._resolve_stock_code_from_text", return_value=None), \
          patch("api.v1.endpoints.clawbot._handle_sync_analysis") as handle_analysis:
         response = handle_clawbot_message(
+            _build_request(),
             ClawBotMessageRequest(message="I NEED ADVICE", mode="auto", user_id="wx_user_004")
         )
 
@@ -210,6 +214,7 @@ def test_clawbot_message_auto_mode_routes_direct_ascii_ticker_to_analysis(
         return_value=analysis_result,
     ) as handle_analysis:
         response = handle_clawbot_message(
+            _build_request(),
             ClawBotMessageRequest(message=message, mode="auto")
         )
 
@@ -250,6 +255,7 @@ def test_clawbot_message_auto_mode_routes_english_request_with_ascii_ticker_to_a
         return_value=analysis_result,
     ) as handle_analysis:
         response = handle_clawbot_message(
+            _build_request(),
             ClawBotMessageRequest(message=message, mode="auto")
         )
 
@@ -267,6 +273,7 @@ def test_clawbot_analysis_mode_rejects_plain_english_text():
     """mode=analysis should return unresolved_stock for non-stock plain text."""
     try:
         handle_clawbot_message(
+            _build_request(),
             ClawBotMessageRequest(message="I need advice", mode="analysis")
         )
         assert False, "Expected HTTPException"
@@ -282,6 +289,7 @@ def test_clawbot_message_returns_consistent_error_when_agent_unavailable():
         with patch("api.v1.endpoints.clawbot._build_executor") as build_executor:
             try:
                 handle_clawbot_message(
+                    _build_request(),
                     ClawBotMessageRequest(message="用缠论分析 600519", mode="agent")
                 )
                 assert False, "Expected HTTPException"
@@ -312,6 +320,7 @@ def test_clawbot_message_validation_handler_returns_error_response_shape():
 def test_clawbot_message_http_handler_normalizes_analysis_validation_error():
     try:
         handle_clawbot_message(
+            _build_request(),
             ClawBotMessageRequest(message="??", mode="analysis", stock_code="??")
         )
         assert False, "Expected HTTPException"
@@ -331,6 +340,7 @@ def test_clawbot_message_http_handler_wraps_executor_exception_as_agent_failed()
          patch("api.v1.endpoints.clawbot._build_executor", side_effect=RuntimeError("executor boom")):
         try:
             handle_clawbot_message(
+                _build_request(),
                 ClawBotMessageRequest(
                     message="用缠论分析 600519",
                     mode="agent",
@@ -362,6 +372,7 @@ def test_clawbot_auto_mode_rejects_plain_english_word_as_direct_ticker(word: str
          patch("api.v1.endpoints.clawbot.CommandDispatcher._resolve_stock_code_from_text", return_value=None), \
          patch("api.v1.endpoints.clawbot._handle_sync_analysis") as handle_analysis:
         response = handle_clawbot_message(
+            _build_request(),
             ClawBotMessageRequest(message=word, mode="auto")
         )
 
@@ -384,6 +395,7 @@ def test_clawbot_analysis_mode_resolves_word_like_ticker():
         return_value=analysis_result,
     ) as handle_analysis:
         response = handle_clawbot_message(
+            _build_request(),
             ClawBotMessageRequest(message="SHOP", mode="analysis")
         )
 
@@ -410,6 +422,7 @@ def test_clawbot_auto_mode_routes_analyze_word_like_ticker_to_analysis():
         return_value=analysis_result,
     ) as handle_analysis:
         response = handle_clawbot_message(
+            _build_request(),
             ClawBotMessageRequest(message="analyze SHOP", mode="auto")
         )
 
@@ -446,6 +459,7 @@ def test_clawbot_auto_mode_routes_single_letter_ticker_in_text(
         return_value=analysis_result,
     ) as handle_analysis:
         response = handle_clawbot_message(
+            _build_request(),
             ClawBotMessageRequest(message=message, mode="auto")
         )
 
@@ -481,9 +495,73 @@ def test_clawbot_auto_mode_resolves_lowercase_ticker_in_free_text(
         return_value=analysis_result,
     ) as handle_analysis:
         response = handle_clawbot_message(
+            _build_request(),
             ClawBotMessageRequest(message=message, mode="auto")
         )
 
     assert response.mode == "analysis"
     assert response.stock_code == expected_code
     handle_analysis.assert_called_once()
+
+
+def test_clawbot_message_rejects_request_when_secret_mismatch():
+    """When CLAWBOT_SECRET is set, mismatched header should return 401."""
+    import os
+    from starlette.datastructures import Headers
+
+    def _build_request_with_header(secret_value: str) -> Request:
+        encoded = secret_value.encode()
+        return Request(
+            {
+                "type": "http",
+                "http_version": "1.1",
+                "method": "POST",
+                "scheme": "http",
+                "path": "/api/v1/clawbot/message",
+                "raw_path": b"/api/v1/clawbot/message",
+                "query_string": b"",
+                "headers": [(b"x-clawbot-secret", encoded)],
+                "client": ("testclient", 50000),
+                "server": ("testserver", 80),
+            }
+        )
+
+    with patch.dict(os.environ, {"CLAWBOT_SECRET": "correct_secret"}):
+        # Wrong secret → 401
+        try:
+            handle_clawbot_message(
+                _build_request_with_header("wrong_secret"),
+                ClawBotMessageRequest(message="分析茅台", mode="auto"),
+            )
+            assert False, "Expected HTTPException 401"
+        except HTTPException as exc:
+            assert exc.status_code == 401
+            assert exc.detail["error"] == "unauthorized"
+
+        # Correct secret → proceeds past auth (agent unavailable → 400 is fine)
+        config = SimpleNamespace(is_agent_available=lambda: False)
+        with patch("api.v1.endpoints.clawbot.get_config", return_value=config):
+            try:
+                handle_clawbot_message(
+                    _build_request_with_header("correct_secret"),
+                    ClawBotMessageRequest(message="分析茅台", mode="auto"),
+                )
+            except HTTPException as exc:
+                assert exc.status_code != 401, "Should not get 401 with correct secret"
+
+
+def test_clawbot_message_allows_request_when_no_secret_configured():
+    """When CLAWBOT_SECRET is not set, all requests should proceed past auth."""
+    import os
+
+    env_without_secret = {k: v for k, v in os.environ.items() if k != "CLAWBOT_SECRET"}
+    with patch.dict(os.environ, env_without_secret, clear=True):
+        config = SimpleNamespace(is_agent_available=lambda: False)
+        with patch("api.v1.endpoints.clawbot.get_config", return_value=config):
+            try:
+                handle_clawbot_message(
+                    _build_request(),
+                    ClawBotMessageRequest(message="分析茅台", mode="auto"),
+                )
+            except HTTPException as exc:
+                assert exc.status_code != 401, "No secret configured, should not get 401"