[教程]手把手教你安装和启动结构小龙虾StructureClaw

1 什么是结构小龙虾 StructureClaw

结构小龙虾（StructureClaw）是清华大学陆新征老师团队牵头的一个开源 AI 协同结构工程平台，项目地址是https://github.com/structureclaw/structureclaw，目标是类似前阵子大火的小龙虾，把结构设计流程沉淀成可以服用、可以组合、可以持续进化的skill。

你只需要用自然语言描述一栋结构——例如"建立一个两层钢框架，平面 6 m x 4 m，层高 3.6 m，柱梁均为 Q355 钢，恒载 5 kN/m²，活载 2 kN/m²"——结构小龙虾就会自动完成建模、校验、计算分析、规范校核和报告生成的全流程。

核心亮点：

Chat-first 建模：像聊天一样描述框架、桁架、门式刚架或通用结构，由 AI Agent 生成可计算模型。
真实分析交付：支持 OpenSees（开源）、PKPM SATWE、YJK 8.0 等多种结构分析引擎。
可追踪工程工件：模型草案、校验结果、分析输出、校核和报告全程可见。
本地优先：数据保存在用户本地目录，无需上传到云端。
双语支持：界面和交互同时支持中文和英文。

这个仓库目前还比较早期，安装和启动方式不像成熟项目那样“一键运行”。对于一般用户而言，安装和启动结构小龙虾可能会遇到一些困难，本文就以 Windows 平台为例，介绍如何从零开始一步一步完成安装和启动。

2 准备工作：安装 Node.js LTS 版本

结构小龙虾要求 Node.js 20 或更高版本。推荐安装 Node.js LTS（长期支持）版本，以获得最稳定的体验。

2.1 下载 Node.js

打开 Node.js 官网下载页面：https://nodejs.org/en/download
点击下载 Windows Installer（.msi）。
如果官网下载速度较慢，也可以使用 Node.js 中文网（https://nodejs.cn/）或 npmmirror 镜像下载。

2.2 安装 Node.js

双击下载的 .msi 安装文件。
按照安装向导操作：

Node.js runtime（核心运行时）
npm package manager（包管理器）
Add to PATH（加入系统环境变量，这一项非常重要，确保命令行可以直接使用 node 和 npm 命令）

勾选 Accept the agreement，点击 Next。
选择安装路径（默认即可），点击 Next。
在 Custom Setup 页面，确保以下组件都已勾选：
点击 Install 开始安装。

安装完成后，点击 Finish。

2.3 验证安装

打开 PowerShell（按 Win + X，选择 "Windows PowerShell"），输入以下命令：

node --version

如果显示类似 v20.x.x 或更高版本号，说明 Node.js 安装成功。再输入：

npm --version

如果显示类似 10.x.x 的版本号，说明 npm 也安装成功。

提示：如果提示"无法识别 'node'"，请关闭当前 PowerShell 窗口，重新打开一个新的窗口再试。安装程序修改了环境变量，新窗口才能生效。如果提示“npm : 无法加载文件 C:\Program Files\nodejs\npm.ps1，因为在此系统上禁止运行脚本。”，可能是系统自带的powershell版本太低，推荐安装powershell7并将其设置为默认终端。（限于篇幅，此过程不展开，可以问问万能的AI如何安装设置。）

3 安装 Git

刚开始我尝试用Node的包管理工具npm安装结构小龙虾：

npm install -g @structureclaw/structureclaw

可能是网络原因，并没有安装成功，因此尝试换一种方法，通过git下载源代码运行，一样很方便。

结构小龙虾的源码托管在 GitHub 上，需要通过 Git 来克隆项目代码。

3.1 下载 Git

打开 Git 官网下载页面：https://git-scm.com/download/win
页面会自动识别你的系统，点击 Click here to download 下载最新版安装程序。

3.2 安装 Git

双击下载的 .exe 安装文件。
按照安装向导操作：

在 Select Components 页面，保持默认选项即可。
在 Choosing the default editor used by Git 页面，可以选择你熟悉的编辑器（默认 Vim）。
在 Adjusting your PATH environment 页面，选择 Git from the command line and also from 3rd-party software（推荐），这样可以在 PowerShell 中直接使用 git 命令。
其余选项保持默认，点击 Install。

安装完成后，点击 Finish。

3.3 验证安装

在 PowerShell 中输入：

git --version

如果显示类似 git version 2.x.x.windows.x，说明安装成功。

4 通过 Git Clone 拷贝项目

4.1 克隆仓库

在 PowerShell 中，切换到你希望存放项目的目录（例如 D:\），然后执行：

cd D:\
git clone https://github.com/structureclaw/structureclaw.git

等待克隆完成。项目体积不大，通常几分钟即可下载完毕。

4.2 进入项目目录

cd structureclaw

4.3 确认项目内容

路径	说明
`sclaw`	主命令行入口
`sclaw_cn`	国内镜像命令行入口
`frontend/`	Next.js 14 前端应用
`backend/`	Fastify 后端 API
`scripts/`	CLI 实现和启动脚本
`docs/`	文档目录

5 用国内镜像入口配置 API 和启动结构小龙虾

由于国内网络环境访问 npm 和 PyPI 可能较慢，结构小龙虾专门提供了 sclaw_cn 国内镜像入口。它和标准 sclaw 命令使用完全相同的子命令，但会自动使用国内镜像源：

npm 镜像：https://registry.npmmirror.com
PyPI 镜像：https://pypi.tuna.tsinghua.edu.cn/simple

5.1 运行 doctor 命令（环境预检与配置）

在项目目录下，打开 PowerShell，执行：

node sclaw_cn doctor

doctor 命令会自动完成以下工作：

创建运行工作区：在用户目录下创建 ~/.structureclaw/ 作为运行数据目录。
检查并安装依赖：检查 Node.js 版本、npm 是否可用，安装所需的 npm 依赖包（通过国内镜像）。
准备 SQLite 数据库：初始化本地 SQLite 数据库文件。
准备 Python 分析环境：自动安装 uv 工具，创建 Python 3.12 虚拟环境（位于 ~/.structureclaw/.venv/），安装 OpenSees 等 Python 分析依赖（通过清华大学 PyPI 镜像）。
**生成 settings.json**：在 ~/.structureclaw/ 下创建配置文件。

注意：在 Windows 上，自动安装 uv 需要系统已安装 winget。如果提示找不到 winget，请手动安装 uv 后再运行 doctor。winget 通常在较新版本的 Windows 10/11 中已预装，可在 PowerShell 中通过 winget --version 检查。

首次运行 doctor 时，由于需要下载依赖包，可能需要几分钟时间。请耐心等待，直到看到类似 "Doctor checks complete" 的提示。

5.2 配置 LLM API 密钥

结构小龙虾需要一个兼容 OpenAI 接口的 LLM 服务来完成 AI 对话和分析。配置方式有两种：

方式一：通过前端界面配置（推荐）

启动成功后，在浏览器中打开工作台，进入 General Settings（通用设置）页面，在 LLM 配置区域填入：

API Key：你的 LLM API 密钥
Base URL：LLM 服务的接口地址
Model：模型名称

方式二：手动编辑 settings.json

用文本编辑器打开 ~/.structureclaw/settings.json，找到 llm 部分：

{
"llm": {
"apiKey": "你的API密钥",
"baseUrl": "https://api.example.com/v1",
"model": "模型名称"
  }
}

修改后保存文件。

这里可以使用任何与OpenAI兼容的其他模型接口，以智谱GLM的为例：

{
"llm": {
"apiKey": "你的API密钥",
"baseUrl": "https://open.bigmodel.cn/api/paas/v4/",
"model": "glm-5.1"
  }
}

也可以是Deepseek：

{
"llm": {
"apiKey": "你的API密钥",
"baseUrl": "https://api.deepseek.com",
"model": "deepseek-v4-flash"
  }
}

其他模型的url和model都可以上对应的官网页面查询。如果是新手想体验一下建议在platform.deepseek.com注册一个API key。

提示：配置项会同时写入 settings.json，前端设置面板和手动编辑是等效的。sclaw doctor 也会在检查时提示你 LLM 配置的状态。

5.3 启动结构小龙虾

配置完成后，在 PowerShell 中执行：

node sclaw_cn start

start 命令会：

启动后端 Fastify 服务。
启动前端 Next.js 开发服务器。
在控制台打印本地工作台的访问地址（通常为 http://localhost:31415）。

当看到类似以下输出时，说明启动成功：

The seed command has been executed.
backend is already running (pid 9204).

Local stack started.
UI + API: http://localhost:31415

此时浏览器会自动打开结构龙虾的主入口页面：

注意：启动过程中请勿关闭 PowerShell 窗口。如果需要停止服务，按 Ctrl + C，或打开一个新的 PowerShell 窗口执行 node .\sclaw_cn stop。

5.4 打开工作台并试跑

可以试着输入以下内容来体验完整流程（记得提前在设置里启用GB50017规范校核技能）：

结构小龙虾会自动执行：模型草案 -> 校验 -> 计算分析 -> 规范校核 -> 报告的完整链路。

结构小龙虾自带开源结构计算软件OpenSees，并可以配置商用软件PKPM或YJK作为结构计算软件自动调用。

如何进一步利用小龙虾，就有待大家的开发了。

5.5 常用后续命令

命令	说明
`node .\sclaw_cn status`	查看前后端服务运行状态
`node .\sclaw_cn logs`	查看运行日志
`node .\sclaw_cn stop`	停止所有服务
`node .\sclaw_cn doctor`	再次运行环境预检

5.6 将来如何更新结构小龙虾？

源码开发版的更新方法很简单，在项目目录下执行：

  cd D:\structureclaw
  git pull origin master
  node sclaw_cn doctor

git pull 拉取最新代码
sclaw_cn doctor 会重新检查依赖、同步数据库 schema、更新 Python 分析环境等

如果 doctor 运行正常，直接 node sclaw_cn start 即可使用新版本。

如果之前是 npm 全局安装的方式，更新命令是：

  npm update -g @structureclaw/structureclaw
  sclaw_cn doctor

小结

安装和启动结构小龙虾只需四步：

安装 Node.js 20+ （ LTS 版本，确保 npm 一并安装）
安装 Git（用于克隆源码）
克隆项目（git clone https://github.com/structureclaw/structureclaw.git）
运行国内镜像命令：node sclaw_cn doctor 配置环境，node sclaw_cn start 启动服务

一切就绪后，切换到浏览器，用自然语言描述你的结构需求，就可以开始使用结构小龙虾了。

如果在使用过程中遇到问题，可以查阅以下文档：

中文手册：docs/handbook_CN.md
中文参考：docs/reference_CN.md
贡献指南：CONTRIBUTING_CN.md
GitHub Issues：https://github.com/structureclaw/structureclaw/issues