跳转到主要内容

Documentation Index

Fetch the complete documentation index at: https://docs.ironclaw.com/llms.txt

Use this file to discover all available pages before exploring further.

Google Compute Engine（GCE）让您在 Google 基础设施上运行虚拟机，提供灵活的定价和慷慨的免费套餐。本指南将带您创建一个 GCE 虚拟机实例，并对其进行安全配置，以便运行 IronClaw 并仅暴露您实际需要的端点。
如果您不想自己搭建基础设施，也可以在 agent.near.ai 上点几下就安装好 IronClaw。

​
创建 Google Cloud 项目

登录 Google Cloud Console。如果是第一次使用，请在提示时接受服务条款。 在顶部导航栏中，点击项目选择器（显示当前项目名称或”选择项目”）→ 新建项目。 填写项目详情：
  • 项目名称：选择一个描述性名称（例如 ironclaw）
  • 组织：除非您的账号属于 Google Workspace 组织，否则保持默认
  • 位置：个人账号保持默认即可
点击创建。Google 需要几秒钟来配置项目。 创建完成后，在继续操作之前，请确保在项目选择器中选中新项目——所有后续创建的资源都归属于当前活跃项目。

​
创建虚拟机实例

导航到 Compute Engine → 虚拟机实例。如果是第一次使用 Compute Engine，系统会提示您启用 Compute Engine API——点击启用并稍等片刻。 GCE 虚拟机实例页面 点击创建实例并进行如下配置：
  • 名称：选择一个描述性名称（例如 ironclaw）
  • 区域 / 可用区：选择离您用户最近的区域
  • 机器类型：e2-micro（符合免费套餐资格）足以满足大多数使用场景，或选择 e2-small 以获得更多余量
  • 启动磁盘：Ubuntu 24.04 LTS，至少 10 GB
  • 防火墙：暂时不勾选”允许 HTTP 流量”和”允许 HTTPS 流量”
实例创建后，您将添加明确的防火墙规则（请参阅下方配置防火墙规则）。 在左侧边栏中，点击安全。向下滚动至 虚拟机访问权限 → 手动添加生成的 SSH 密钥，点击 + 添加项，然后粘贴您的 SSH 公钥。 GCE 实例配置 您可以在本地生成一对密钥： 
ssh-keygen -t ed25519 -C "your-email@example.com"
cat ~/.ssh/id_ed25519.pub   # 将此内容复制到控制台
密钥应为 OpenSSH 公钥格式：<类型> <base64编码密钥> [注释]（例如 ssh-ed25519 AAAA... your-email@example.com）。GCE 支持多种密钥类型，并会自动将密钥添加到实例中。
您也可以使用密码登录，但使用 SSH 密钥会更安全，也更推荐。请妥善保管私钥，不要与他人共享。

​
访问您的实例

实例启动后，在虚拟机实例列表中找到其外部 IP。 GCE 实例 IP 地址 点击实例旁边的 SSH 按钮，即可打开基于浏览器的终端——无需本地配置。 要从您自己的终端使用 IP 地址连接： 
# 将 <IP_ADDRESS> 和 <USERNAME> 替换为实际值
ssh <USERNAME>@<IP_ADDRESS>

​
配置防火墙规则

IronClaw 的 Web 网关默认绑定到 127.0.0.1:3000，即默认仅限本地访问，无法直接从互联网访问。 推荐的暴露模型：
  • 将 Web 网关保持绑定在 127.0.0.1:3000
  • 通过反向代理在 80/443 端口暴露公共流量，并转发到 127.0.0.1:3000
  • 或保持网关私有，通过 SSH 隧道/VPN 访问
在左侧边栏导航到 VPC 网络 → 防火墙，根据您的模型创建规则。 基础规则（大多数配置推荐）：
规则名称方向目标来源 IP 范围协议 / 端口
allow-ssh-myip入站所有实例您的公网 IP（例如 203.0.113.10/32）TCP 22
allow-webhook入站所有实例0.0.0.0/0TCP 8080
如果您运行反向代理（推荐用于公网 Web 访问），还需允许：
规则名称方向目标来源 IP 范围协议 / 端口
allow-http入站所有实例0.0.0.0/0TCP 80
allow-https入站所有实例0.0.0.0/0TCP 443
如果您有意直接暴露网关（通常不推荐），则必须：
  1. 设置 GATEWAY_HOST=0.0.0.0（如果端口不是 3000，可选设置 GATEWAY_PORT=<端口>）
  2. 设置 GATEWAY_AUTH_TOKEN=<强随机令牌>
  3. 为该网关端口添加防火墙规则，最好限制为受信任的来源 IP
如果通过 SSH 隧道或 VPN 访问，保持 GATEWAY_HOST 为默认值（127.0.0.1），不要在 GCE 防火墙中开放网关端口。
将 SSH 限制为您的 IP 可以防止来自互联网的暴力破解攻击。如果您的 IP 发生变化，可以随时更新来源范围。Webhook（例如 Telegram）需要 8080 端口来向 IronClaw 发送事件。在 Linux 上，编排器内部 API 监听 50051 端口并绑定到 0.0.0.0；除非您为其添加防火墙规则，GCE 的默认拒绝所有入站流量策略仍会阻止外部访问。其他 IronClaw 监听器默认绑定到 127.0.0.1。

​
加固您的实例

获得访问权限后，在安装 IronClaw 之前先对虚拟机进行安全加固。

​
更新和升级

确保系统处于最新状态： 
sudo apt update && sudo apt upgrade -y

​
创建新用户

良好的实践是创建一个具备 sudo 权限的专用用户，而不是依赖默认账号。您可以创建一个新用户（例如 ironclaw），并将其加入 sudo 组： 
sudo adduser ironclaw
sudo usermod -aG sudo ironclaw
将 SSH 密钥从当前用户复制到新用户，以便您能够登录： 
# 为新用户创建 .ssh 目录
sudo mkdir -p /home/ironclaw/.ssh

# 从当前用户复制 authorized_keys
sudo cp ~/.ssh/authorized_keys /home/ironclaw/.ssh/authorized_keys

# 设置正确的权限（非常关键——否则 SSH 会忽略该文件）
sudo chown -R ironclaw:ironclaw /home/ironclaw/
sudo chmod 700 /home/ironclaw/.ssh
sudo chmod 600 /home/ironclaw/.ssh/authorized_keys
打开一个新的终端窗口，确认可以成功登录后再继续： 
ssh ironclaw@<IP_ADDRESS>
在确认新用户可以成功登录之前，不要继续后续步骤。如果在没有其他可用用户的情况下失去访问权限，您将需要重新创建虚拟机。

​
安装 IronClaw

服务器加固完成后，安装 IronClaw 并启动： 
curl --proto '=https' --tlsv1.2 -LsSf https://github.com/nearai/ironclaw/releases/latest/download/ironclaw-installer.sh | sh
然后启动 IronClaw 并按照提示完成配置： 
ironclaw
建议使用 tmux 或 screen 这样的会话管理器，以便在 SSH 会话之间轻松分离和恢复运行中的 IronClaw 进程。

​
下一步

阅读我们的快速开始指南，创建您的第一个智能体，把它连接到 Telegram，并开始探索 IronClaw 的能力。 想通过消息应用与您的智能体对话？请查看频道文档，了解如何完成接入。 需要让智能体执行依赖多个工具的复杂任务？请查看扩展文档。