IronClaw震撼首发安装详细教程

Kalin_
0 阅读10分钟

IronClaw 安装教程（小白友好版）

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

目录

一、IronClaw 简介

1.1 IronClaw 是什么？

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

1.2 核心特点

特点说明
数据私有所有数据本地加密存储，永不离开你的控制
透明开源完全开源可审计，无隐藏数据收集
自我扩展动态构建新工具，无需等待官方更新
安全沙盒工具在隔离环境运行，防止恶意操作
多渠道接入支持 REPL、HTTP、Telegram、Slack、Web 网关

1.3 IronClaw vs SQLite 方案

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

对比项PostgreSQLSQLite
并发性能支持多用户并发单文件，单写入者
扩展性支持向量搜索等扩展扩展能力有限
生产可用性企业级稳定性适合嵌入式场景
适用场景生产环境、多用户开发测试、单机应用

1.4 安全设计

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

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

1.5 技术架构

┌────────────────────────────────────────────────────────────────┐
│                          渠道层 (Channels)                      │
│  ┌──────┐  ┌──────┐   ┌─────────────┐  ┌─────────────┐         │
│  │ REPL │  │ HTTP │   │WASM Channels│  │ Web Gateway │         │
│  └──┬───┘  └──┬───┘   └──────┬──────┘  └──────┬──────┘         │
│     └─────────┴──────────────┴────────────────┘                │
│                              │                                 │
│                    ┌─────────▼─────────┐                       │
│                    │    Agent Loop     │                       │
│                    └────┬──────────┬───┘                       │
│              ┌──────────▼────┐  ┌──▼───────────────┐           │
│              │  Scheduler    │  │ Routines Engine  │           │
│              └──────┬────────┘  └────────┬─────────┘           │
│       ┌─────────────┼────────────────────┘                     │
│   ┌───▼─────┐  ┌────▼────────────────┐                         │
│   │ Local   │  │    Orchestrator     │                         │
│   │Workers  │  │  ┌───────────────┐  │                         │
│   └───┬─────┘  │  │ Docker Sandbox│  │                         │
│       │        │  └───────────────┘  │                         │
│       │        └─────────┬───────────┘                         │
│       └──────────────────┤                                     │
│              ┌───────────▼──────────┐                          │
│              │    Tool Registry     │                          │
│              └──────────────────────┘                          │
└────────────────────────────────────────────────────────────────┘

1.6 许可证

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

  • Apache License 2.0
  • MIT License

二、Windows 完整安装指南

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

2.1 系统要求

项目要求
操作系统Windows 10 或 Windows 11
内存4GB 以上（推荐 8GB）
硬盘至少 1GB 可用空间
权限需要管理员权限安装部分软件

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

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

2.2.1 下载 Rust 安装程序

  1. 打开浏览器，访问：rustup.rs

  2. 页面会自动检测你的系统，点击下载 rustup-init.exe

2.2.2 运行安装程序

  1. 双击运行 rustup-init.exe

  2. 如果出现 Windows 安全提示：

    • 点击「更多信息」
    • 点击「仍要运行」

  3. 出现命令行界面后，输入 1 选择默认安装，按回车

  4. 等待安装完成（约 2-5 分钟）

  5. 安装完成后，关闭当前所有 PowerShell 和命令提示符窗口

2.2.3 验证安装

  1. 打开新的 PowerShell 窗口

  2. 执行以下命令：

    rustc --version
cargo --version

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

    rustc 1.85.0 (...)
cargo 1.85.0 (...)
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. 安装向导步骤：

    步骤操作
    Installation Directory保持默认，点击 Next
    Select Components保持默认全选，点击 Next
    Data Directory保持默认，点击 Next
    Password设置 postgres 用户密码 （记住这个密码！）
    Port保持默认 5432，点击 Next
    Locale选择默认或你的语言，点击 Next
    Ready to Install点击 Next 开始安装

  3. 等待安装完成

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

2.3.3 验证 PostgreSQL 安装

  1. 按 Win + R，输入 cmd，按回车

  2. 进入 PostgreSQL bin 目录：

    cd "C:\Program Files\PostgreSQL\15\bin"

  3. 连接数据库测试：

    psql -U postgres

  4. 输入你设置的密码

  5. 如果看到 postgres=# 提示符，说明安装成功

  6. 输入 \q 退出

2.3.4 安装 pgvector 扩展

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

  1. 访问：github.com/pgvector/pg…

  2. 下载对应 PostgreSQL 版本的 ZIP 文件，例如：

    pgvector-0.7.4-windows-x64-pg15.zip

  3. 解压 ZIP 文件

  4. 复制文件到 PostgreSQL 目录：

    源文件目标位置
    pgvector.dllC:\Program Files\PostgreSQL\15\lib\
    vector.controlC:\Program Files\PostgreSQL\15\share\extension\
    vector--*.sqlC:\Program Files\PostgreSQL\15\share\extension\

方法二：从源码编译

如果你有 Visual Studio Build Tools：

# 克隆仓库
git clone https://github.com/pgvector/pgvector.git
cd pgvector

# 编译
nmake /F Makefile.win

# 安装
nmake /F Makefile.win install

2.4 步骤三：创建 IronClaw 数据库

2.4.1 打开 SQL Shell

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

  2. 打开 SQL Shell

2.4.2 创建数据库

在 SQL Shell 中依次执行：

-- 连接信息直接按回车使用默认值
-- Server [localhost]:         直接回车
-- Database [postgres]:        直接回车
-- Port [5432]:                直接回车
-- Username [postgres]:        直接回车
-- Password:                   输入你的密码

-- 创建数据库
CREATE DATABASE ironclaw;

-- 连接到新数据库
\c ironclaw

-- 启用 pgvector 扩展
CREATE EXTENSION IF NOT EXISTS vector;

-- 验证扩展
SELECT * FROM pg_extension WHERE extname = 'vector';

-- 退出
\q

2.5 步骤四：安装 IronClaw

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

  1. 访问：github.com/nearai/iron…

  2. 下载文件：

    ironclaw-x86_64-pc-windows-msvc.msi

  3. 双击运行安装包

  4. 按提示完成安装

  5. 验证安装：

    ironclaw --version
方式 B：使用 PowerShell 脚本

  1. 右键点击 Windows 开始菜单

  2. 选择 「Windows PowerShell (管理员)」 或 「终端 (管理员)」

  3. 执行以下命令：

    irm https://github.com/nearai/ironclaw/releases/latest/download/ironclaw-installer.ps1 | iex

  4. 等待安装完成

  5. 验证安装：

    ironclaw --version
方式 C：从源码编译

  1. 安装 Git（如果还没有）：

  2. 打开 PowerShell，克隆仓库：

    git clone https://github.com/nearai/ironclaw.git
cd ironclaw

  3. 编译：

    cargo build --release

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

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

    target\release\ironclaw.exe

  5. （可选）添加到 PATH：

    # 查看当前目录
pwd

# 将以下内容添加到系统环境变量 PATH
# 例如：C:\dev\ironclaw\target\release

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

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

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

# 设置环境变量（临时，仅当前会话有效）
$env:DATABASE_URL = "postgres://postgres:你的密码@localhost:5432/ironclaw"

永久设置：

  1. 按 Win + R，输入 sysdm.cpl，按回车

  2. 点击「高级」选项卡

  3. 点击「环境变量」

  4. 在「用户变量」区域，点击「新建」

  5. 填写：

    • 变量名：DATABASE_URL
    • 变量值：postgres://postgres:你的密码@localhost:5432/ironclaw

  6. 点击「确定」保存

  7. 重启 PowerShell

2.7 步骤六：首次启动配置

2.7.1 运行配置向导
ironclaw onboard
2.7.2 配置向导流程

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

1. 数据库连接

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

2. NEAR AI 认证

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

3. 密钥加密

  • 确认使用 Windows Credential Manager 加密敏感信息
2.7.3 配置文件位置

配置保存在：

C:\Users\你的用户名\.ironclaw\
├── .env              # 环境变量
├── settings.json     # 用户设置
└── session.json      # NEAR AI 会话

2.8 步骤七：启动和使用

2.8.1 启动交互式 REPL
ironclaw

启动后界面：

Welcome to IronClaw!
Type your message and press Enter to chat.
Type /help for available commands.

You:
2.8.2 带调试日志启动
$env:RUST_LOG = "ironclaw=debug"
ironclaw
2.8.3 启动 Web 网关
$env:GATEWAY_ENABLED = "true"
$env:GATEWAY_PORT = "3001"
$env:GATEWAY_AUTH_TOKEN = "your-token"
ironclaw

访问：http://localhost:3001

三、macOS 完整安装指南

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

3.1 系统要求

项目要求
操作系统macOS 10.15 (Catalina) 或更高
处理器Intel 或 Apple Silicon (M1/M2/M3)
内存4GB 以上（推荐 8GB）

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

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

3.2.1 安装 Homebrew

  1. 打开「终端」（Terminal）应用

    • 按 Command + Space 搜索「终端」

  2. 执行以下命令：

    /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

  3. 按提示输入密码

  4. 等待安装完成

3.2.2 配置 PATH（Apple Silicon Mac 必需）

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

# 添加到 shell 配置
echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zprofile

# 立即生效
eval "$(/opt/homebrew/bin/brew shellenv)"
3.2.3 验证安装
brew --version

3.3 步骤二：安装 Rust

3.3.1 安装 Rust
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

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

3.3.2 加载 Rust 环境
source $HOME/.cargo/env
3.3.3 验证安装
rustc --version
cargo --version

3.4 步骤三：安装 PostgreSQL

3.4.1 使用 Homebrew 安装
# 安装 PostgreSQL 15
brew install postgresql@15
3.4.2 启动 PostgreSQL 服务
# 启动服务
brew services start postgresql@15

# 检查服务状态
brew services list
3.4.3 添加到 PATH
# 如果使用 zsh（macOS 默认）
echo 'export PATH="/opt/homebrew/opt/postgresql@15/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

# 如果使用 bash
echo 'export PATH="/opt/homebrew/opt/postgresql@15/bin:$PATH"' >> ~/.bash_profile
source ~/.bash_profile
3.4.4 安装 pgvector
brew install pgvector
3.4.5 验证安装
psql --version

3.5 步骤四：创建 IronClaw 数据库

# 创建数据库
createdb ironclaw

# 启用 pgvector 扩展
psql ironclaw -c "CREATE EXTENSION IF NOT EXISTS vector;"

# 验证
psql ironclaw -c "SELECT * FROM pg_extension WHERE extname = 'vector';"

3.6 步骤五：安装 IronClaw

方式 A：使用 Homebrew（推荐）
brew install ironclaw

验证安装：

ironclaw --version
方式 B：使用安装脚本
curl --proto '=https' --tlsv1.2 -LsSf https://github.com/nearai/ironclaw/releases/latest/download/ironclaw-installer.sh | sh

安装完成后，重启终端：

source ~/.zshrc
ironclaw --version
方式 C：从源码编译
# 克隆仓库
git clone https://github.com/nearai/ironclaw.git
cd ironclaw

# 编译
cargo build --release

# 验证
./target/release/ironclaw --version

# （可选）创建符号链接
sudo ln -s $(pwd)/target/release/ironclaw /usr/local/bin/ironclaw

3.7 步骤六：首次启动配置

# 运行配置向导
ironclaw onboard

向导会引导完成：

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

3.8 步骤七：启动和使用

3.8.1 启动 REPL
ironclaw
3.8.2 带调试日志
RUST_LOG=ironclaw=debug ironclaw
3.8.3 启动 Web 网关
export GATEWAY_ENABLED=true
export GATEWAY_PORT=3001
export GATEWAY_AUTH_TOKEN=your-token
ironclaw

四、Linux 完整安装指南

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

4.1 系统要求

项目要求
发行版Ubuntu 20.04+ / Debian 11+ / Fedora 35+
内存2GB 以上（推荐 4GB）
权限需要 sudo 权限

4.2 步骤一：更新系统

# Ubuntu/Debian
sudo apt update && sudo apt upgrade -y

# Fedora
sudo dnf update -y

4.3 步骤二：安装 Rust

# 下载并运行 Rust 安装脚本
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

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

# 加载 Rust 环境
source $HOME/.cargo/env

# 验证
rustc --version
cargo --version

4.4 步骤三：安装 PostgreSQL

Ubuntu/Debian
# 安装 PostgreSQL 15
sudo apt install -y postgresql-15 postgresql-contrib-15

# 安装 pgvector
sudo apt install -y postgresql-15-pgvector

# 启动服务
sudo systemctl start postgresql
sudo systemctl enable postgresql

# 检查状态
sudo systemctl status postgresql
Fedora
# 安装 PostgreSQL
sudo dnf install -y postgresql-server postgresql-contrib

# 初始化数据库
sudo postgresql-setup --initdb

# 启动服务
sudo systemctl start postgresql
sudo systemctl enable postgresql

# 安装 pgvector（从源码）
sudo dnf install -y git make gcc
git clone https://github.com/pgvector/pgvector.git
cd pgvector
make
sudo make install
Arch Linux
# 安装 PostgreSQL 和 pgvector
sudo pacman -S postgresql pgvector

# 初始化数据库
sudo -u postgres initdb -D /var/lib/postgres/data

# 启动服务
sudo systemctl start postgresql
sudo systemctl enable postgresql

4.5 步骤四：创建 IronClaw 数据库

# 切换到 postgres 用户创建数据库
sudo -u postgres createdb ironclaw

# 启用 pgvector
sudo -u postgres psql ironclaw -c "CREATE EXTENSION IF NOT EXISTS vector;"

# 验证
sudo -u postgres psql ironclaw -c "SELECT * FROM pg_extension WHERE extname = 'vector';"

或者交互式操作：

# 以 postgres 用户连接
sudo -u postgres psql

# 在 psql 中执行
CREATE DATABASE ironclaw;
\c ironclaw
CREATE EXTENSION IF NOT EXISTS vector;
\q

4.6 步骤五：安装 IronClaw

方式 A：使用安装脚本
curl --proto '=https' --tlsv1.2 -LsSf https://github.com/nearai/ironclaw/releases/latest/download/ironclaw-installer.sh | sh

安装完成后：

source ~/.bashrc
ironclaw --version
方式 B：从源码编译
# 安装编译依赖
sudo apt install -y build-essential pkg-config libssl-dev git

# 克隆仓库
git clone https://github.com/nearai/ironclaw.git
cd ironclaw

# 编译
cargo build --release

# 验证
./target/release/ironclaw --version

# 创建符号链接（可选）
sudo ln -s $(pwd)/target/release/ironclaw /usr/local/bin/ironclaw

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

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

如果需要密码认证：

# 设置 PostgreSQL 用户密码
sudo -u postgres psql
\password postgres
# 输入新密码
\q

# 配置环境变量
export DATABASE_URL="postgres://postgres:你的密码@localhost:5432/ironclaw"

# 永久设置（添加到 .bashrc）
echo 'export DATABASE_URL="postgres://postgres:你的密码@localhost:5432/ironclaw"' >> ~/.bashrc
source ~/.bashrc

4.8 步骤七：首次启动配置

ironclaw onboard

向导会引导完成：

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

4.9 步骤八：启动和使用

4.9.1 启动 REPL
ironclaw
4.9.2 带调试日志
RUST_LOG=ironclaw=debug ironclaw
4.9.3 后台运行
# 使用 nohup
nohup ironclaw > ironclaw.log 2>&1 &

# 或使用 systemd 服务
ironclaw service install
ironclaw service start

五、LLM 模型配置详解

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

5.1 NEAR AI（默认，推荐）

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

配置方式：

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

NEARAI_MODEL=zai-org/GLM-5-FP8
NEARAI_BASE_URL=https://private.near.ai

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

  1. 访问 cloud.near.ai 获取 API Key

  2. 配置：

    NEARAI_API_KEY=your-api-key

5.2 OpenRouter（300+ 模型）

获取 API Key：

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

配置：

LLM_BACKEND=openai_compatible
LLM_BASE_URL=https://openrouter.ai/api/v1
LLM_API_KEY=sk-or-v1-xxxxxxxxx
LLM_MODEL=anthropic/claude-sonnet-4

热门模型：

模型 ID说明
anthropic/claude-sonnet-4高质量对话
openai/gpt-4oGPT-4 优化版
google/gemini-pro-1.5长上下文
meta-llama/llama-3.3-70b-instruct开源大模型

5.3 Ollama（本地免费）

安装 Ollama：

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

下载模型：

ollama pull llama3.2
ollama pull mistral

配置 IronClaw：

LLM_BACKEND=ollama
OLLAMA_MODEL=llama3.2
OLLAMA_BASE_URL=http://localhost:11434

5.4 Together AI

获取 API Key： api.together.xyz

配置：

LLM_BACKEND=openai_compatible
LLM_BASE_URL=https://api.together.xyz/v1
LLM_API_KEY=xxxxxxxxx
LLM_MODEL=meta-llama/Llama-3.3-70B-Instruct-Turbo

5.5 Fireworks AI

获取 API Key： fireworks.ai

配置：

LLM_BACKEND=openai_compatible
LLM_BASE_URL=https://api.fireworks.ai/inference/v1
LLM_API_KEY=fw_xxxxxxxxx
LLM_MODEL=accounts/fireworks/models/llama4-maverick-instruct-basic

5.6 Anthropic 直连

获取 API Key： console.anthropic.com

配置：

LLM_BACKEND=anthropic
ANTHROPIC_API_KEY=sk-ant-xxxxxxxxx
ANTHROPIC_MODEL=claude-sonnet-4-20250514

六、常用命令速查

6.1 主要命令

命令说明
ironclaw onboard首次配置向导
ironclaw启动交互式 REPL
ironclaw --version查看版本
ironclaw --help显示帮助

6.2 配置管理

命令说明
ironclaw config list列出所有配置
ironclaw config get <key>获取配置值
ironclaw config set <key> <value>设置配置值

6.3 工具管理

命令说明
ironclaw tool list列出所有工具
ironclaw tool install <name>安装工具
ironclaw tool remove <name>移除工具

6.4 诊断命令

命令说明
ironclaw doctor系统诊断
ironclaw status健康状态

6.5 REPL 内命令

命令说明
/help显示帮助
/exit退出
/tools显示工具列表
/status显示状态

七、常见问题解答

Q1: Windows 上 createdb 命令找不到？

解决方案：

方法一：使用 SQL Shell

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

方法二：使用完整路径

& "C:\Program Files\PostgreSQL\15\bin\createdb.exe" ironclaw

方法三：添加到 PATH

  1. 右键「此电脑」→「属性」→「高级系统设置」
  2. 「环境变量」→ 编辑 Path
  3. 添加 C:\Program Files\PostgreSQL\15\bin

Q2: 编译时 "linker 'link.exe' not found"？

解决方案：

安装 Visual Studio Build Tools：

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

Q3: 数据库连接失败？

检查清单：

  1. 服务是否运行？

    # Windows
Get-Service postgresql*

# macOS
brew services list

# Linux
sudo systemctl status postgresql

  2. 端口是否正确？ 默认 5432

  3. 密码是否正确？ 检查 DATABASE_URL

Q4: NEAR AI 认证失败？

解决方案：

  1. 检查网络连接
  2. 尝试手动认证： 
    浏览器打开：https://private.near.ai/auth
  3. 使用 API Key 代替会话令牌

Q5: 如何完全重置？

Windows：

Remove-Item -Recurse -Force "$env:USERPROFILE\.ironclaw"
ironclaw onboard

macOS/Linux：

rm -rf ~/.ironclaw
ironclaw onboard

Q6: 如何备份数据？

# 备份配置
cp -r ~/.ironclaw ~/.ironclaw-backup

# 备份数据库
pg_dump ironclaw > ironclaw_backup.sql

# 恢复数据库
psql ironclaw < ironclaw_backup.sql

参考资源

资源链接
GitHub 仓库github.com/nearai/iron…
Releases 下载github.com/nearai/iron…
问题反馈github.com/nearai/iron…
Telegram 社区t.me/ironclawAI
Reddit 社区www.reddit.com/r/ironclawA…

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

avatar
文章
阅读
粉丝