github.com/DingyangLyu/MatClaw @main

用自然语言描述材料问题，MatClaw 自动编写代码、运行模拟、交付结果。

         

         

---

目录

• MatClaw 是什么？
• 聊天命令
• 内置计算技能库
• 通用研究工具
• 基本使用
• 示例
• 计算引擎
• 快速开始
• 架构
• 配置
• 文档
• 贡献
• 引用

MatClaw 是什么？

MatClaw 是一个能自主执行材料科学计算的 AI Agent。你用自然语言描述任务，它自动编写 Python/Shell 脚本，在隔离的 Docker 容器中运行（容器内预装了完整的计算工具链），然后返回结果。

在飞书（或任意通道）发送任务，即可获得脚本、模拟、图表和分析——无需手写任何代码。

核心特性：

• 自主计算 — 理解任务、编写代码、执行计算、分析输出、遇错自动重试
• 240 个内置技能 — 47 个技能组，涵盖计算材料科学（电子结构、声子、力学性质、缺陷、光学、磁学、催化、电池、相图、蒙特卡洛、分子动力学等）及通用研究工具（文献检索、绘图、文档生成、数据分析）。每个技能包含完整可运行脚本、参数指南和方法选择决策树。详见材料计算技能参考手册。
• 支持 VASP — 通过 SSH 连接 HPC 集群或挂载本地 VASP，Agent 自动生成输入、提交任务、解析结果。详见 VASP 接入指南。
• GPU 加速 — 可选 CUDA 容器 (./container/build.sh --cuda)，GPU 加速 MACE、CHGNet、SevenNet、MatGL 计算。运行时自动检测 GPU，无 GPU 时自动降级为 CPU
• 多种 MLIP 模型 — MACE-MP-0（预装）、CHGNet、SevenNet、MatGL 全部预装，支持快速筛选和分子动力学
• 开箱即用 — QE 7.5、LAMMPS、RASPA3、MACE、pymatgen、ASE、PyTorch 全部预装
• 安全隔离 — 每次计算都在一次性 Docker 容器中运行，文件系统隔离
• 灵活的 LLM 后端 — 支持 Anthropic Claude、DeepSeek 或任何 Anthropic 兼容 API
• 多通道接入 — 通过飞书、钉钉、Gmail、WhatsApp、Telegram、Discord、Slack 对话
• 聊天命令 — /watch、/status、/stop、/sessions、/new、/resume、/compact — 直接在聊天中管理会话、监控进度、控制 Agent
• 实时监控面板 — 内置 Web 界面 (localhost:3210)，实时查看 Agent 活动、解析对话记录、查看容器日志
• 可扩展 — 容器内有 conda/pip，Agent 可以按需安装额外的包

聊天命令

在任意消息通道中直接控制 Agent——无需终端或打开面板。

命令	说明
/watch	查看 Agent 正在做什么（最近的工具调用、文件读写、命令执行）
/status	Agent 状态——运行中/空闲、当前会话、容器名称、排队任务数
/stop	强制停止正在运行的 Agent
/sessions	列出所有历史会话（ID、时间、大小、活跃标记）
/new	开启全新对话，不携带任何历史记忆
/resume [id]	恢复上一次会话，或通过 ID 前缀切换到任意历史会话
/compact [重点]	压缩 Agent 记忆。可指定保留重点（如 /compact 只保留 VASP 配置相关）
/help	显示所有可用命令

会话管理 — 每次对话都是可恢复的会话。用 /new 重新开始，/sessions 浏览历史，/resume 跳回到任意之前的上下文，Agent 会从中断处继续。

实时监控 — 随时发送 /watch 查看 Agent 最近的操作，无需等它跑完。如需完整图形化视图，打开内置面板 http://localhost:3210。

内置计算技能库

MatClaw 内置 240 个 SKILL.md 文件，涵盖 47 个技能组，全面覆盖计算材料科学各领域及通用研究工具。每个技能包含完整可运行脚本、参数指南、方法选择决策树和常见问题排查表——使 Agent 能够自主执行任何主流材料计算工作流。

47 组 / 195 个子技能 / 240 个 SKILL.md 文件

#	技能组	子技能数	包含子技能
1	2d-materials	4	band-edges, layer-manipulation, stacking-energy, vacuum-resize
2	advanced-electronic	5	gw-approximation, hubbard-u, spin-orbit-coupling, topological-invariants, van-der-waals
3	agent-browser	0	（浏览器工具，非计算）
4	alloy-disorder	2	cluster-expansion, sqs-generation
5	band-advanced	3	3d-band-structure, band-unfolding, hybrid-dft-bands
6	battery-electrode	2	intercalation-voltage, ion-diffusion
7	biomolecular-md	1	openmm-simulation
8	bonding-analysis	10	bader2pqr, bader-charge, charge-density, charge-density-difference, charge-format-conversion, elf-analysis, lobster-cohp, orbital-projection, planar-charge, stm-simulation
9	catalysis-electrochem	6	band-center, imaginary-freq-correction, implicit-solvation, neb-analysis, reaction-kinetics, thermal-corrections
10	catalyst-screening	3	d-band-center, overpotential, scaling-relations
11	code-interfaces	5	boltztrap-interface, ifc-analysis, phonopy-interface, vasp-qe-converter, wannier90-interface
12	deepchem	0	（分子 ML：性质预测、GNN、迁移学习）
13	defects-reactions	13	activation-relaxation-technique, adsorption-energy, configuration-coordinate, defect-thermodynamics, interstitial-defect, migration-barrier, neb-transition-state, point-defect, reaction-pathway, substitution-defect, surface-adsorption, surface-energy, vacancy-formation
14	dft-corrections	3	hubbard-u, spin-orbit-coupling, vdw-correction
15	electronic-structure	8	band-structure, convergence-testing, density-of-states, inverse-participation-ratio, projected-dos, scf-relax, spatially-resolved-dos, vasp-bands
16	electron-phonon	4	deformation-potential, electronic-transport, elph-coupling, superconductivity
17	fermi-surface	3	2d-fermi-surface, 3d-fermi-surface, projected-fermi-surface
18	ferroelectric	5	born-effective-charge, dielectric-tensor, ferroelectric-switching, piezoelectric, polarization
19	general-tools	16	（见通用研究工具）
20	high-throughput	8	batch-calculations, batch-screening, convergence-automation, materials-filtering, matpes-dual-static, phase-stability, property-prediction, screening-workflow
21	interface	2	grain-boundary, heterostructure
22	kpath-utilities	5	1d-kpath, 2d-kpath, bulk-kpath, cp2k-kpath, phonopy-kpath
23	magnetic-properties	3	magnetic-anisotropy, magnetic-ordering, spin-polarized
24	materials-compute	0	（根技能：QE/LAMMPS/MACE 环境说明）
25	materials-databases	2	2d-semiconductors, materials-project
26	mechanical-properties	5	angular-mechanics, elastic-constants, energy-strain-method, equation-of-state, stress-strain-method
27	mlip-guide	4	mace-advanced, mlip-validation, torchsim-batch, universal-mlip
28	molecular-qchem	1	gaussian-qchem-workflow
29	monte-carlo	5	adsorption-isotherm, gas-adsorption, gas-separation, gcmc-simulation, pore-analysis
30	optical-properties	6	absorption-spectrum, dielectric-function, joint-dos, optical-conductivity, slme, transition-dipole
31	phase-diagram	2	convex-hull, pourbaix-diagram
32	phase-transition	6	amorphous-structure, melting-point-coexistence, metadynamics, mpmorph-melting, order-parameter, phase-diagram
33	piezoelectric	1	piezoelectric-tensor
34	potential-analysis	3	macroscopic-average, planar-average, work-function
35	rdkit	0	（化学信息学：SMILES、描述符、指纹、相似度）
36	semiconductor-kit	4	angular-effective-mass, band-gap, effective-mass, fermi-velocity
37	spectroscopy	2	raman-ir, xas-xanes
38	spin-texture	2	2d-spin-texture, 3d-spin-texture
39	structure-models	8	alloy-builder, defect-builder, heterostructure, moire-superlattice, nanowire-nanotube, quantum-dot, supercell-builder, surface-builder
40	structure-tools	8	advanced-optimization, format-conversion, input-generation, pdf-analysis, structure-editing, structure-matching, symmetry-analysis, xrd-pattern
41	surface-energy	2	surface-energy-calc, wulff-construction
42	thermal-properties	13	anharmonicity, bond-distribution, free-energy-calculation, gruneisen-qha, md-trajectory-tools, molecular-dynamics, msd-diffusion, phonon, phonon-from-outcar, quasi-harmonic-debye, rdf-analysis, thermal-conductivity, vacf-vdos
43	thermoconductivity	1	lattice-thermal-conductivity
44	topological	2	berry-curvature, z2-invariant
45	transport-properties	2	boltzmann-transport, kpoints-transport
46	wannier-functions	1	wannier90-workflow
47	wavefunction-analysis	2	real-space-wavefunction, wavefunction-parity

覆盖领域：电子结构、力学、热学、声子、缺陷、光学、磁学、拓扑、催化、电池、相图、铁电/压电、输运、表面、界面、2D 材料、合金、蒙特卡洛、分子动力学、机器学习势、生物分子模拟、量子化学、化学信息学等。已对标 atomate2、aiida-quantumespresso、aiida-vasp 验证——所有工作流能力均已覆盖。详见材料计算技能参考手册。

通用研究工具

除材料计算外，MatClaw 还内置 16 个通用研究技能，涵盖文献检索、可视化、文档生成和数据分析——统一归入 general-tools 技能组。

类别	技能	说明
文献与引用	arxiv-database, openalex-database, citation-management	arXiv / OpenAlex（2.4 亿+论文）检索，DOI → BibTeX
可视化	matplotlib, plotly, seaborn, scientific-visualization	出版级图表、交互式图表、期刊配色多面板
文档	scientific-writing, pptx, docx, pdf, latex-posters, xlsx	论文、PPT、Word、PDF、海报、表格
数据分析	statistical-analysis, exploratory-data-analysis, sympy	统计检验、200+ 格式 EDA、符号数学

所有通用工具均在本地运行，无需额外 API 密钥。

基本使用

通过任意已接入的通道（飞书、WhatsApp、Gmail 等）发送自然语言任务，或直接通过 Docker 运行：

echo '{
  "prompt": "用 DFT (Quantum ESPRESSO) 计算硅的带隙",
  "groupFolder": "test",
  "chatJid": "test@g.us",
  "isMain": false,
  "secrets": {
    "ANTHROPIC_API_KEY": "your-api-key",
    "ANTHROPIC_BASE_URL": "https://api.anthropic.com"
  }
}' | docker run -i -v ./workspace:/workspace/group matclaw-agent:latest

Agent 会自主完成以下步骤：

1. 解析任务需求，规划计算方案
2. 编写输入文件和脚本
3. 运行模拟（DFT、MD、MC 或 MLIP）
4. 分析结果、生成图表、汇报结论
5. 如遇错误，自动调整并重试

结果——包括图表、数据文件和结构化摘要——直接返回。

示例

Benchmark 任务改编自 QUASAR。全部由 Agent 自主完成——编写脚本、运行模拟、汇报结果。详见 examples/。

基础任务

Cu K 点收敛（DFT / Quantum ESPRESSO）

使体 Cu 能量收敛到 < 1 meV/atom。Agent 运行 8 次 QE 计算并绘制收敛曲线。

---

水密度（MD / LAMMPS）

计算 298 K、1 bar 下水的密度。Agent 构建 SPC/E 水盒子，运行 NPT 模拟，返回结果和诊断图。

---

IRMOF-1 孔隙率（MC / RASPA3）

计算 IRMOF-1 在 298 K 下的氦可及孔隙率。Agent 配置并运行 RASPA3 Widom 插入蒙特卡洛。

---

工作流编排

NiO 带隙（DFT+U / Quantum ESPRESSO）

计算 NiO 的电子带隙。Agent 识别出强关联体系，自主选择 DFT+U 方法。

[!TIP] 用户仅要求"计算 NiO 的带隙"——Agent 独立判断出关联氧化物需要 DFT+U 处理，自主选择了合适的 U 值，并完成了 SCF → NSCF → DOS 的完整流程。

---

CO₂ 在 UiO-66 中的吸附（MC / RASPA3）

计算 4 个压力点下的 CO₂ 吸附等温线。Agent 运行 GCMC 模拟并生成等温线图。

---

Al 熔点（MD / LAMMPS）

通过两相共存法计算铝的熔点。Agent 构建 8000 原子体系，使用键序参数进行分析。

---

NaCl 溶液密度（MD / LAMMPS + packmol）

计算 1 mol/L NaCl 溶液的密度。Agent 自主安装 packmol（未预装），构建体系并运行 MD。

[!TIP] packmol 未预装在容器中。Agent 检测到缺失依赖后，自主下载并从源码编译（尝试了 3 种不同方案），成功后继续完成模拟。

---

结果汇总

示例	方法	引擎	参考值	Agent 结果
Cu k 点收敛	DFT	QE	< 1 meV/atom	12×12×12 收敛
水密度	MD	LAMMPS	0.997 g/cm³	0.985 g/cm³
IRMOF-1 孔隙率	MC	RASPA3	0.7988	0.8025
NiO 带隙	DFT+U	QE	4.0 eV	2.11 eV
CO₂ in UiO-66	MC	RASPA3	5.98 mmol/g	5.48 mmol/g
Al 熔点	MD	LAMMPS	933 K	~850–880 K
NaCl 溶液密度	MD	LAMMPS	1.038 g/cm³	1.033 g/cm³

计算引擎

引擎	版本	方法	应用场景
Quantum ESPRESSO	7.5	DFT	电子结构、带隙、态密度、声子、弹性常数
LAMMPS	2021	MD	热学性质、扩散系数、力学性质、相变
RASPA3	3.0.16	MC	MOF/沸石中的气体吸附、吸附等温线、Henry 常数
VASP	5.x / 6.x	DFT	通过外部接入实现全功能 DFT（配置指南）
MACE-MP-0	latest	MLIP	通用机器学习势，快速能量/力/应力预测

Python 材料科学工具栈（全部预装）

包	用途
pymatgen	晶体结构操作、相图、电子结构分析
ASE	原子对象、计算器、结构优化、分子动力学
MACE-torch	通用机器学习原子间势
mp-api	Materials Project 数据库访问
spglib	空间群/对称性分析
PyTorch	机器学习框架（CPU 版）
numpy, scipy, matplotlib, pandas, seaborn	科学计算与可视化

快速开始

一键安装（推荐）

git clone https://github.com/DingyangLyu/MatClaw.git
cd MatClaw
npm install && npm run setup

交互式安装向导将引导你完成环境检查、容器设置、API 配置、冒烟测试和消息通道选择——逐步完成。

前置要求

• Linux（推荐 Ubuntu 24.04+）或 macOS
• Docker
• Anthropic 兼容的 API 密钥（Claude、DeepSeek 或 44 家其他供应商）

手动安装

1. 获取容器

方式 A — 拉取预构建镜像（推荐）：

```bash doc