From 091af29fc4be172ae2b321c59139fc39a99c7ba4 Mon Sep 17 00:00:00 2001 From: educoder Date: Wed, 29 Apr 2026 21:11:49 +0800 Subject: [PATCH] =?UTF-8?q?=E6=9B=B4=E6=96=B0=20'SKILL.md'?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- SKILL.md | 37 ++++++++++++++++++++++--------------- 1 file changed, 22 insertions(+), 15 deletions(-) diff --git a/SKILL.md b/SKILL.md index 37dd889..4b0df5c 100644 --- a/SKILL.md +++ b/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` -2. 每次创建 MCPClient 或建立 MCP 连接时，从 `os.getenv("EDUCODER_AUTHORIZATION")` 读取最新值 -3. 把读取到的 token 原文放进 MCP transport headers 的 `Authorization`，不要添加 `Bearer ` 前缀 -4. 多个会话可以分别创建 MCPClient 实例，但认证 token 都来自同一个环境变量 +1. 在 OpenClaw 持久化配置或密钥存储中保存 token +2. OpenClaw 启动服务或创建新会话时，把保存的 token 注入环境变量 `EDUCODER_AUTHORIZATION` +3. 每次创建 MCPClient 或建立 MCP 连接时，从 `os.getenv("EDUCODER_AUTHORIZATION")` 读取最新值 +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` -4. 重新创建 MCP 连接，并从环境变量读取最新 token -5. 使用新 token 重新发起本次工具调用 +3. 将用户输入的新 token 保存到 OpenClaw 的持久化配置或密钥存储 +4. 同步更新当前进程环境变量 `EDUCODER_AUTHORIZATION` +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` -3. 当前用户发起工具调用时，后端创建 MCPClient -4. MCPClient 建连时从环境变量读取 `EDUCODER_AUTHORIZATION` -5. MCPClient 把读取到的 token 原文放进 MCP headers，不要添加 `Bearer ` 前缀 -6. 如果调用返回 `401 Unauthorized`，提示用户重新输入 token，更新 `EDUCODER_AUTHORIZATION` 后重新建连并重试 +2. 在 OpenClaw 持久化配置或密钥存储中保存 token +3. OpenClaw 启动服务或创建新会话时，把保存的 token 注入环境变量 `EDUCODER_AUTHORIZATION` +4. 当前用户发起工具调用时，后端创建 MCPClient +5. MCPClient 建连时从环境变量读取 `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` 数组属于预期行为，因为外部接口尚未接入 - 后续新增或调整工具时，需要同步更新本文件