> ## 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

> 在 Google Compute Engine 虚拟机上托管 IronClaw

Google Compute Engine（GCE）让您在 Google 基础设施上运行虚拟机，提供灵活的定价和慷慨的免费套餐。本指南将带您创建一个 GCE 虚拟机实例，并对其进行安全配置，以便运行 IronClaw 并仅暴露您实际需要的端点。

<Tip>
  如果您不想自己搭建基础设施，也可以在 [agent.near.ai](https://agent.near.ai) 上点几下就安装好 IronClaw。
</Tip>

***

## 创建 Google Cloud 项目

登录 [Google Cloud Console](https://console.cloud.google.com)。如果是第一次使用，请在提示时接受服务条款。

在顶部导航栏中，点击**项目选择器**（显示当前项目名称或"选择项目"）→ **新建项目**。

填写项目详情：

* **项目名称**：选择一个描述性名称（例如 `ironclaw`）
* **组织**：除非您的账号属于 Google Workspace 组织，否则保持默认
* **位置**：个人账号保持默认即可

点击**创建**。Google 需要几秒钟来配置项目。

创建完成后，在继续操作之前，请确保在项目选择器中**选中**新项目——所有后续创建的资源都归属于当前活跃项目。

***

## 创建虚拟机实例

导航到 **Compute Engine → 虚拟机实例**。如果是第一次使用 Compute Engine，系统会提示您启用 Compute Engine API——点击**启用**并稍等片刻。

<img src="https://mintcdn.com/nearai/4151wbND8wVyukXI/images/infrastructure/google/google-vm.png?fit=max&auto=format&n=4151wbND8wVyukXI&q=85&s=7ef35abcf1957a21463287a08fb14506" alt="GCE 虚拟机实例页面" width="1685" height="770" data-path="images/infrastructure/google/google-vm.png" />

点击**创建实例**并进行如下配置：

* **名称**：选择一个描述性名称（例如 `ironclaw`）
* **区域 / 可用区**：选择离您用户最近的区域
* **机器类型**：`e2-micro`（符合免费套餐资格）足以满足大多数使用场景，或选择 `e2-small` 以获得更多余量
* **启动磁盘**：Ubuntu 24.04 LTS，至少 10 GB
* **防火墙**：暂时**不勾选**"允许 HTTP 流量"和"允许 HTTPS 流量"

实例创建后，您将添加明确的防火墙规则（请参阅下方[配置防火墙规则](#配置防火墙规则)）。

在左侧边栏中，点击**安全**。向下滚动至 **虚拟机访问权限 → 手动添加生成的 SSH 密钥**，点击 **+ 添加项**，然后粘贴您的 SSH 公钥。

<img src="https://mintcdn.com/nearai/4151wbND8wVyukXI/images/infrastructure/google/google-ssh.png?fit=max&auto=format&n=4151wbND8wVyukXI&q=85&s=a66922101347e69c5ad4e89ff9eb17ec" alt="GCE 实例配置" width="1927" height="770" data-path="images/infrastructure/google/google-ssh.png" />

您可以在本地生成一对密钥：

```bash theme={null}
ssh-keygen -t ed25519 -C "your-email@example.com"
cat ~/.ssh/id_ed25519.pub   # 将此内容复制到控制台
```

密钥应为 OpenSSH 公钥格式：`<类型> <base64编码密钥> [注释]`（例如 `ssh-ed25519 AAAA... your-email@example.com`）。GCE 支持多种密钥类型，并会自动将密钥添加到实例中。

<Note>
  您也可以使用密码登录，但使用 SSH 密钥会更安全，也更推荐。请妥善保管私钥，不要与他人共享。
</Note>

***

## 访问您的实例

实例启动后，在虚拟机实例列表中找到其**外部 IP**。

<img src="https://mintcdn.com/nearai/4151wbND8wVyukXI/images/infrastructure/google/google-ip.png?fit=max&auto=format&n=4151wbND8wVyukXI&q=85&s=9e946027ac547c0b77e977ffa523b7b0" alt="GCE 实例 IP 地址" width="2939" height="629" data-path="images/infrastructure/google/google-ip.png" />

点击实例旁边的 **SSH** 按钮，即可打开基于浏览器的终端——无需本地配置。

要从您自己的终端使用 IP 地址连接：

```bash theme={null}
# 将 <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/0`                   | TCP 8080 |

如果您运行反向代理（推荐用于公网 Web 访问），还需允许：

| 规则名称          | 方向 | 目标   | 来源 IP 范围    | 协议 / 端口 |
| ------------- | -- | ---- | ----------- | ------- |
| `allow-http`  | 入站 | 所有实例 | `0.0.0.0/0` | TCP 80  |
| `allow-https` | 入站 | 所有实例 | `0.0.0.0/0` | TCP 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 防火墙中开放网关端口。

<Note>
  将 SSH 限制为您的 IP 可以防止来自互联网的暴力破解攻击。如果您的 IP 发生变化，可以随时更新来源范围。Webhook（例如 Telegram）需要 `8080` 端口来向 IronClaw 发送事件。在 Linux 上，编排器内部 API 监听 `50051` 端口并绑定到 `0.0.0.0`；除非您为其添加防火墙规则，GCE 的默认拒绝所有入站流量策略仍会阻止外部访问。其他 IronClaw 监听器默认绑定到 `127.0.0.1`。
</Note>

***

## 加固您的实例

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

### 更新和升级

确保系统处于最新状态：

```bash theme={null}
sudo apt update && sudo apt upgrade -y
```

### 创建新用户

良好的实践是创建一个具备 sudo 权限的专用用户，而不是依赖默认账号。您可以创建一个新用户（例如 `ironclaw`），并将其加入 sudo 组：

```bash theme={null}
sudo adduser ironclaw
sudo usermod -aG sudo ironclaw
```

将 SSH 密钥从当前用户复制到新用户，以便您能够登录：

```bash theme={null}
# 为新用户创建 .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
```

打开一个新的终端窗口，确认可以成功登录后再继续：

```bash theme={null}
ssh ironclaw@<IP_ADDRESS>
```

<Warning>
  在确认新用户可以成功登录之前，不要继续后续步骤。如果在没有其他可用用户的情况下失去访问权限，您将需要重新创建虚拟机。
</Warning>

***

## 安装 IronClaw

服务器加固完成后，安装 IronClaw 并启动：

```bash theme={null}
curl --proto '=https' --tlsv1.2 -LsSf https://github.com/nearai/ironclaw/releases/latest/download/ironclaw-installer.sh | sh
```

然后启动 IronClaw 并按照提示完成配置：

```bash theme={null}
ironclaw
```

<Tip>
  建议使用 `tmux` 或 `screen` 这样的会话管理器，以便在 SSH 会话之间轻松分离和恢复运行中的 IronClaw 进程。
</Tip>

***

## 下一步

阅读我们的[快速开始指南](/quickstart)，创建您的第一个智能体，把它连接到 Telegram，并开始探索 IronClaw 的能力。

想通过消息应用与您的智能体对话？请查看[**频道**](/channels/overview)文档，了解如何完成接入。

需要让智能体执行依赖多个工具的复杂任务？请查看[**扩展**](/extensions/overview)文档。