Understand-Anything 仪表盘提示 "Access Token Required" 怎么排查？
【免费下载链接】Understand-AnythingGraphs that teach > graphs that impress. Turn any code into an interactive knowledge graph you can explore, search, and ask questions about. Works with Claude Code, Codex, Cursor, Copilot, Gemini CLI, and more.项目地址: https://gitcode.com/GitHub_Trending/un/Understand-Anything
启动 Understand-Anything 的交互式知识图谱仪表盘后，浏览器里出现的不是图谱，而是一个标题为 "Access Token Required" 的输入框，提示你把终端里 🔑 行的 access token 粘进来。这个提示本身不是故障：仪表盘的数据接口（knowledge-graph.json、domain-graph.json、diff-overlay.json、meta.json、config.json、file-content.json）全部带一次性 token 门禁，服务进程启动时生成 token，只打印在终端里；浏览器 URL 里没有带正确的?token=参数，前端就会停在这道门。排查思路只有一条：确认服务进程还活着，从终端输出里找到带 token 的完整 URL。
先弄清这道门是怎么触发的
- token 在服务器进程启动时生成：
UNDERSTAND_ACCESS_TOKEN环境变量未设置时，用 16 字节随机数（hex）作为一次性 token（见 vite.config.ts 与 viewer.mjs）。 - 服务监听地址固定绑定
127.0.0.1，默认端口 5173，端口被占用时自动选用下一个可用端口。 - 数据接口对
token参数做严格比对，不匹配时返回403 Forbidden: missing or invalid token；带 token 的请求成功，Access Token Required界面消失，图谱加载出来。
所以只要浏览器里看到的是这道门，问题一定出在"URL 缺少 token"或"token 与服务端不一致"上，而不是图谱数据本身。
最短路径：直接打开终端里带 token 的完整 URL
无论你用哪条路径启动仪表盘，服务启动后都会在终端打印一行带 🔑 的 URL（文档示例，端口和 token 以实际输出为准）：
🔑 Dashboard URL: http://127.0.0.1:<PORT>/?token=<TOKEN>- 通过
/understand-dashboardskill 启动时，它会优先运行按插件版本固定的预构建 viewer（npx下载 release 里的understand-anything-viewer.tgz），后台运行并打印这一行；skill 文档明确要求把?token=参数一并放进你分享的 URL——省略它就会被 token 门拦住（见 SKILL.md）。 - 用独立 viewer 时，命令是
npx <release-tarball> /path/to/analyzed/project，终端打印http://127.0.0.1:<port>/?token=…并自动打开浏览器（见 viewer README，要求 Node.js >= 18，项目目录需含.ua/或旧版.understand-anything/数据目录）。
正确做法是回到打印了 🔑 行那个终端窗口，复制整行 URL（端口和?token=参数都不能少），粘贴到浏览器打开。这样无需手动输入 token，门禁直接被绕过。
如果必须走输入框：把 🔑 行中token=后面那段值粘贴进输入框，点 Continue。前端会请求/knowledge-graph.json?token=<你输入的值>，返回 200 即放行。
输入框里的三种报错分别怎么处理
TokenGate.tsx 里一共只有三类提示，可以按报错逐一对号：
| 界面提示 | 触发条件 | 处理方式 |
|---|---|---|
Invalid token. Please check and try again. | 请求返回 403，token 与服务端不一致 | 重新从终端 🔑 行复制 token。常见原因：复制了旧 URL、中途重启过服务、端口看错拿成了另一个实例 |
Unexpected response (<status>). Is the dashboard server running? | 请求通了但既不是 200 也不是 403 | 说明请求没有落在预期的仪表盘接口上，优先确认 URL 主机和端口是否就是服务打印的那个，然后重启服务重试 |
Could not reach the server: ... | fetch 抛异常，连不上 127.0.0.1 | 服务进程没在跑（或已退出）。重新启动 viewer / Vite dev server，再从新的终端输出里取 🔑 行 URL |
需要特别注意的是：token 是一次性、随进程生成的。服务每重启一次，旧 URL 里的?token=就作废，之前的书签或聊天记录里的链接都打不开，必须取新终端输出里的那一行。
服务起不来或没有输出 🔑 行时的回退
/understand-dashboard的快路径（预构建 viewer）如果进程退出且没有打印 🔑 行——skill 文档说明这对应"该版本没有 release 资源，或没有网络"两种情况——按 SKILL.md 的回退步骤走：
cd "$DASHBOARD_DIR" && (pnpm install --frozen-lockfile 2>/dev/null || pnpm install)cd "$PLUGIN_ROOT" && pnpm --filter @understand-anything/core buildcd "$DASHBOARD_DIR" && GRAPH_DIR="$PROJECT_DIR" npx vite --host 127.0.0.1第二条命令构建仪表盘依赖的 core 包；第三条用 Vite dev server 启动，GRAPH_DIR环境变量告诉 dev server 去哪里找知识图谱。$DASHBOARD_DIR、$PLUGIN_ROOT、$PROJECT_DIR按 SKILL.md 第 3 步的探测逻辑解析（$PLUGIN_ROOT/packages/dashboard等），后台运行后同样会打印 🔑 行。
从仓库 clone 安装的等价写法（见 README.md）：
pnpm install && pnpm --filter @understand-anything/core build GRAPH_DIR=/path/to/analyzed/project pnpm dev:dashboard其中/path/to/analyzed/project替换为你已生成过图谱的项目目录。
验证与限制
- 验证方式：打开带 token 的 URL 后，"Access Token Required" 界面消失、知识图谱正常渲染，即说明门禁通过；输入框输入正确 token 后点 Continue，前端收到 200 也会直接进入仪表盘。
- 仪表盘从本地磁盘只读提供服务、只绑定
127.0.0.1、数据不出本机（viewer README 的表述）；token 门是这套本地只读模型的一部分，没有"关闭 token"的选项。 - 边界条件：如果项目目录里根本没有
knowledge-graph.json，skill 会直接提示No knowledge graph found. Run /understand first to analyze this project.——先跑/understand生成图谱，再谈仪表盘门禁。 - 想固定 token 而不是每次随机生成，服务支持
UNDERSTAND_ACCESS_TOKEN环境变量（vite 配置和 viewer 都是process.env.UNDERSTAND_ACCESS_TOKEN || 随机值的取值方式）；设了之后每次启动用同一个值，旧 URL 不会因重启失效。
【免费下载链接】Understand-AnythingGraphs that teach > graphs that impress. Turn any code into an interactive knowledge graph you can explore, search, and ask questions about. Works with Claude Code, Codex, Cursor, Copilot, Gemini CLI, and more.项目地址: https://gitcode.com/GitHub_Trending/un/Understand-Anything
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
