大家好，我是讯享网，很高兴认识大家。这里提供最前沿的Ai技术和互联网信息。



本教程按操作系统组织，每个系统有独立的完整安装流程。 只需阅读你使用的操作系统章节即可。

---

• 一、IronClaw 简介
• 二、Windows 完整安装指南
• 三、macOS 完整安装指南
• 四、Linux 完整安装指南
• 五、LLM 模型配置详解
• 六、常用命令速查
• 七、常见问题解答

---

1.1 IronClaw 是什么？

IronClaw 是一个安全、私密、可自我扩展的个人 AI 助手。

1.2 核心特点

1.3 IronClaw vs SQLite 方案

IronClaw 使用 PostgreSQL 而非 SQLite，原因如下：

1.4 安全设计

IronClaw 从一开始就设计了多层防御：

• WASM 沙盒 - 工具在隔离容器中运行
• 凭据保护 - 密钥永远不暴露给工具
• 泄露检测 - 扫描请求和响应中的敏感信息
• 端点白名单 - HTTP 请求仅允许访问已批准的地址

1.5 技术架构

1.6 许可证

IronClaw 采用双许可证，你可以任选其一：

• Apache License 2.0
• MIT License

---

本章涵盖 Windows 系统从环境配置到部署的完整流程。

2.1 系统要求

2.2 步骤一：安装 Rust 编译环境

如果你只需要使用预编译版本，可以跳过此步骤。

2.2.1 下载 Rust 安装程序

1. 打开浏览器，访问：rustup.rs
2. 页面会自动检测你的系统，点击下载 rustup-init.exe

2.2.2 运行安装程序

1. 双击运行
2. 如果出现 Windows 安全提示：
   • 点击「更多信息」
   • 点击「仍要运行」
3. 出现命令行界面后，输入 1 选择默认安装，按回车
4. 等待安装完成（约 2-5 分钟）
5. 安装完成后，关闭当前所有 PowerShell 和命令提示符窗口

2.2.3 验证安装

1. 打开新的 PowerShell 窗口
2. 执行以下命令：

3. 如果显示版本号，说明安装成功：

2.2.4 安装 Visual Studio Build Tools（源码编译必需）

如果你计划从源码编译 IronClaw，还需要安装 C++ 编译工具：

1. 访问：visualstudio.microsoft.com/visual-cpp-…
2. 下载并运行安装程序
3. 在安装界面中，勾选 「Desktop development with C++」
4. 点击「安装」
5. 安装完成后，重启电脑

2.3 步骤二：安装 PostgreSQL 数据库

2.3.1 下载 PostgreSQL

1. 访问：www.postgresql.org/download/wi…
2. 点击「Download the installer」链接
3. 选择版本（推荐 PostgreSQL 15 或更高）
4. 选择操作系统架构：Windows x86-64
5. 下载安装程序

2.3.2 运行安装程序

1. 双击下载的安装程序
2. 安装向导步骤：

等待安装完成

取消勾选「Launch Stack Builder at exit」，点击 Finish

2.3.3 验证 PostgreSQL 安装

1. 按 Win + R，输入 ，按回车
2. 进入 PostgreSQL bin 目录：

3. 连接数据库测试：

4. 输入你设置的密码
5. 如果看到 提示符，说明安装成功
6. 输入 退出

2.3.4 安装 pgvector 扩展

方法一：下载预编译文件（推荐）

1. 访问：github.com/pgvector/pg…
2. 下载对应 PostgreSQL 版本的 ZIP 文件，例如：

3. 解压 ZIP 文件
4. 复制文件到 PostgreSQL 目录：

方法二：从源码编译

如果你有 Visual Studio Build Tools：

2.4 步骤三：创建 IronClaw 数据库

2.4.1 打开 SQL Shell

1. 按 Win 键，搜索 SQL Shell (psql)
2. 打开 SQL Shell

2.4.2 创建数据库

在 SQL Shell 中依次执行：

2.5 步骤四：安装 IronClaw

方式 A：使用 MSI 安装包（推荐新手）

1. 访问：github.com/nearai/iron…
2. 下载文件：

3. 双击运行安装包
4. 按提示完成安装
5. 验证安装：

方式 B：使用 PowerShell 脚本

1. 右键点击 Windows 开始菜单
2. 选择 「Windows PowerShell (管理员)」 或 「终端 (管理员)」
3. 执行以下命令：

4. 等待安装完成
5. 验证安装：

方式 C：从源码编译

1. 安装 Git（如果还没有）：
   • 访问 git-scm.com/download/wi…
   • 下载并安装
2. 打开 PowerShell，克隆仓库：

3. 编译：

   首次编译可能需要 5-15 分钟，请耐心等待

4. 编译完成后，可执行文件位于：

5. （可选）添加到 PATH：

2.6 步骤五：配置数据库连接

如果 PostgreSQL 使用默认设置且无密码，IronClaw 可以直接连接。

如果设置了密码，需要配置连接字符串：

永久设置：

1. 按 Win + R，输入 ，按回车
2. 点击「高级」选项卡
3. 点击「环境变量」
4. 在「用户变量」区域，点击「新建」
5. 填写：
   • 变量名：
   • 变量值：
6. 点击「确定」保存
7. 重启 PowerShell

2.7 步骤六：首次启动配置

2.7.1 运行配置向导

2.7.2 配置向导流程

向导会引导你完成以下设置：

1. 数据库连接

• 向导会自动检测数据库
• 如果连接失败，按提示输入连接信息

2. NEAR AI 认证

• 向导显示一个 URL 和授权码
• 按回车打开浏览器
• 选择 GitHub 或 Google 登录
• 登录成功后返回终端

3. 密钥加密

• 确认使用 Windows Credential Manager 加密敏感信息

2.7.3 配置文件位置

配置保存在：

2.8 步骤七：启动和使用

2.8.1 启动交互式 REPL

启动后界面：

2.8.2 带调试日志启动

2.8.3 启动 Web 网关

访问：http://localhost:3001

---

本章涵盖 macOS 系统从环境配置到部署的完整流程。

3.1 系统要求

3.2 步骤一：安装 Homebrew 包管理器

Homebrew 是 macOS 最流行的包管理器，强烈推荐安装。

3.2.1 安装 Homebrew

1. 打开「终端」（Terminal）应用
   • 按 Command + Space 搜索「终端」
2. 执行以下命令：

3. 按提示输入密码
4. 等待安装完成

3.2.2 配置 PATH（Apple Silicon Mac 必需）

如果你使用 M1/M2/M3 芯片的 Mac：

3.2.3 验证安装

3.3 步骤二：安装 Rust

3.3.1 安装 Rust

当提示选择安装选项时，直接按 回车 选择默认。

3.3.2 加载 Rust 环境

3.3.3 验证安装

3.4 步骤三：安装 PostgreSQL

3.4.1 使用 Homebrew 安装

3.4.2 启动 PostgreSQL 服务

3.4.3 添加到 PATH

3.4.4 安装 pgvector

3.4.5 验证安装

3.5 步骤四：创建 IronClaw 数据库

3.6 步骤五：安装 IronClaw

方式 A：使用 Homebrew（推荐）

验证安装：

方式 B：使用安装脚本

安装完成后，重启终端：

方式 C：从源码编译

3.7 步骤六：首次启动配置

向导会引导完成：

1. 数据库连接检测
2. NEAR AI 浏览器认证
3. macOS Keychain 加密配置

3.8 步骤七：启动和使用

3.8.1 启动 REPL

3.8.2 带调试日志

3.8.3 启动 Web 网关

---

本章涵盖 Linux 系统从环境配置到部署的完整流程。 以 Ubuntu/Debian 为例，其他发行版类似。

4.1 系统要求

4.2 步骤一：更新系统

4.3 步骤二：安装 Rust

当提示选择时，直接按 回车 选择默认安装。

4.4 步骤三：安装 PostgreSQL

Ubuntu/Debian

Fedora

Arch Linux

4.5 步骤四：创建 IronClaw 数据库

或者交互式操作：

4.6 步骤五：安装 IronClaw

方式 A：使用安装脚本

安装完成后：

方式 B：从源码编译

4.7 步骤六：配置数据库连接

如果 PostgreSQL 使用默认设置，IronClaw 可以直接连接。

如果需要密码认证：

4.8 步骤七：首次启动配置

向导会引导完成：

1. 数据库连接检测
2. NEAR AI 浏览器认证
3. 系统密钥环配置（GNOME Keyring / KDE Wallet）

4.9 步骤八：启动和使用

4.9.1 启动 REPL

4.9.2 带调试日志

4.9.3 后台运行

---

无论你使用哪个操作系统，LLM 配置方式相同。

5.1 NEAR AI（默认，推荐）

NEAR AI 提供免费的 AI 模型访问。

配置方式：

通过配置向导自动完成，或手动配置：

使用 API Key（服务器部署推荐）：

1. 访问 cloud.near.ai 获取 API Key
2. 配置：

5.2 OpenRouter（300+ 模型）

获取 API Key：

1. 访问 openrouter.ai
2. 注册账号
3. 进入 Settings → Keys → Create Key

配置：

热门模型：

5.3 Ollama（本地免费）

安装 Ollama：

1. 访问 ollama.ai
2. 下载并安装

下载模型：

配置 IronClaw：

5.4 Together AI

获取 API Key： api.together.xyz

配置：

5.5 Fireworks AI

获取 API Key： fireworks.ai

配置：

5.6 Anthropic 直连

获取 API Key： console.anthropic.com

配置：

---

6.1 主要命令

6.2 配置管理

6.3 工具管理

6.4 诊断命令

6.5 REPL 内命令

---

Q1: Windows 上 命令找不到？

解决方案：

方法一：使用 SQL Shell

1. 搜索并打开「SQL Shell (psql)」
2. 执行

方法二：使用完整路径

方法三：添加到 PATH

1. 右键「此电脑」→「属性」→「高级系统设置」
2. 「环境变量」→ 编辑
3. 添加

Q2: 编译时 “linker ‘link.exe’ not found”？

解决方案：

安装 Visual Studio Build Tools：

1. 访问 visualstudio.microsoft.com/visual-cpp-…
2. 安装时选择「Desktop development with C++」
3. 重启电脑后重新编译

Q3: 数据库连接失败？

检查清单：

1. 服务是否运行？

2. 端口是否正确？ 默认 5432
3. 密码是否正确？ 检查 DATABASE_URL

Q4: NEAR AI 认证失败？

解决方案：

1. 检查网络连接
2. 尝试手动认证：

3. 使用 API Key 代替会话令牌

Q5: 如何完全重置？

Windows：

macOS/Linux：

Q6: 如何备份数据？

---

---

本教程基于 IronClaw 官方文档编写 最后更新：2026年3月