更新 'SKILL.md'

SKILL.md

@@ -24,12 +24,14 @@ description: 提供 Educoder 用户与课堂相关查询能力，当前支持用
 
 ### Authorization 配置
 
-在运行 OpenClaw 或 MCP 客户端的进程环境中配置：
+在运行 OpenClaw 或 MCP 客户端的进程环境中配置。下面的 `export` 只对当前 shell 或当前进程有效，适合临时调试：
 
 ```bash
 export EDUCODER_AUTHORIZATION="xxxxx"
 ```
 
+OpenClaw 线上使用时，必须把 token 保存到 OpenClaw 的持久化配置或密钥存储中，并在启动服务、创建新会话或刷新 token 后注入到进程环境变量 `EDUCODER_AUTHORIZATION`。不要只依赖临时 `export`，否则新开会话或服务重启后会读不到 token。
+
 MCP 客户端每次连接时应读取环境变量并注入：
 
 ```python
@@ -65,10 +67,11 @@ async with streamable_http_client(self.server_url, headers=headers or None) as (
 
 正确做法是：
 
-1. 在 OpenClaw 运行环境中配置 `EDUCODER_AUTHORIZATION`
+1. 在 OpenClaw 持久化配置或密钥存储中保存 token
-2. 每次创建 MCPClient 或建立 MCP 连接时，从 `os.getenv("EDUCODER_AUTHORIZATION")` 读取最新值
+2. OpenClaw 启动服务或创建新会话时，把保存的 token 注入环境变量 `EDUCODER_AUTHORIZATION`
-3. 把读取到的 token 原文放进 MCP transport headers 的 `Authorization`，不要添加 `Bearer ` 前缀
+3. 每次创建 MCPClient 或建立 MCP 连接时，从 `os.getenv("EDUCODER_AUTHORIZATION")` 读取最新值
-4. 多个会话可以分别创建 MCPClient 实例，但认证 token 都来自同一个环境变量
+4. 把读取到的 token 原文放进 MCP transport headers 的 `Authorization`，不要添加 `Bearer ` 前缀
+5. 多个会话可以分别创建 MCPClient 实例，但认证 token 都来自同一个环境变量
 
 ### 401 Token 过期处理
 
@@ -78,9 +81,10 @@ async with streamable_http_client(self.server_url, headers=headers or None) as (
 
 1. 停止继续使用当前 token 重试
 2. 提示用户重新输入新的 `Authorization`
-3. 将用户输入的新 token 更新到环境变量 `EDUCODER_AUTHORIZATION`
+3. 将用户输入的新 token 保存到 OpenClaw 的持久化配置或密钥存储
-4. 重新创建 MCP 连接，并从环境变量读取最新 token
+4. 同步更新当前进程环境变量 `EDUCODER_AUTHORIZATION`
-5. 使用新 token 重新发起本次工具调用
+5. 重新创建 MCP 连接，并从环境变量读取最新 token
+6. 使用新 token 重新发起本次工具调用
 
 示例提示：
 
@@ -94,18 +98,19 @@ async with streamable_http_client(self.server_url, headers=headers or None) as (
 export EDUCODER_AUTHORIZATION="new-token"
 ```
 
-> 更新 token 后必须重新建立 MCP 连接，不能复用已经携带旧 headers 的连接。
+> `export` 只是临时示例。线上需要同时更新持久化配置，否则新开会话或服务重启后仍会丢失 token。更新 token 后必须重新建立 MCP 连接，不能复用已经携带旧 headers 的连接。
 
 ### OpenClaw 接入建议
 
 如果使用 OpenClaw，推荐按下面的方式接入：
 
 1. 安装 skill 时，MCP 服务地址填写：`http://47.98.32.66:48000/mcp`
-2. 在 OpenClaw 运行环境中配置 `EDUCODER_AUTHORIZATION`
+2. 在 OpenClaw 持久化配置或密钥存储中保存 token
-3. 当前用户发起工具调用时，后端创建 MCPClient
+3. OpenClaw 启动服务或创建新会话时，把保存的 token 注入环境变量 `EDUCODER_AUTHORIZATION`
-4. MCPClient 建连时从环境变量读取 `EDUCODER_AUTHORIZATION`
+4. 当前用户发起工具调用时，后端创建 MCPClient
-5. MCPClient 把读取到的 token 原文放进 MCP headers，不要添加 `Bearer ` 前缀
+5. MCPClient 建连时从环境变量读取 `EDUCODER_AUTHORIZATION`
-6. 如果调用返回 `401 Unauthorized`，提示用户重新输入 token，更新 `EDUCODER_AUTHORIZATION` 后重新建连并重试
+6. MCPClient 把读取到的 token 原文放进 MCP headers，不要添加 `Bearer ` 前缀
+7. 如果调用返回 `401 Unauthorized`，提示用户重新输入 token，更新持久化配置和 `EDUCODER_AUTHORIZATION` 后重新建连并重试
 
 参考流程：
 
@@ -141,6 +146,7 @@ class MCPClient:
 - 让用户在每个会话里重复输入 `Authorization`
 - 把 `Authorization` 放到工具参数里
 - 给 `Authorization` 自动拼接 `Bearer ` 前缀
+- 只在当前 shell 中临时 `export EDUCODER_AUTHORIZATION`，没有写入 OpenClaw 持久化配置
 - 在进程启动后只读取一次 token，导致环境变量更新后无法生效
 
 ## 触发场景
@@ -329,6 +335,7 @@ async def main():
 - 当前服务使用 `streamable-http`，不是 SSE
 - 如果客户端使用了 `sse_client`，将无法正常调用当前服务
 - `Authorization` 应从环境变量 `EDUCODER_AUTHORIZATION` 读取 token 原文，通过 MCP 连接层 headers 传入，不放在工具参数里，也不要添加 `Bearer ` 前缀
-- 调用接口返回 `401 Unauthorized` 时，视为 token 过期或无效，应要求用户重新输入 token，并更新到环境变量 `EDUCODER_AUTHORIZATION`
+- 调用接口返回 `401 Unauthorized` 时，视为 token 过期或无效，应要求用户重新输入 token，并同步更新 OpenClaw 持久化配置和环境变量 `EDUCODER_AUTHORIZATION`
+- 新开会话读不到 token 时，通常是 token 只做了临时 `export`，没有写入 OpenClaw 持久化配置；需要先从持久化配置恢复到环境变量
 - 当前工具返回空 `data` 数组属于预期行为，因为外部接口尚未接入
 - 后续新增或调整工具时，需要同步更新本文件