google/sam · 上手攻略

仓库：google/sam
链接：https://github.com/google/sam
分类：AI Agents & Agency / Infrastructure
作者：Jay
更新：2026-09-01

是什么

SAM（Sovereign Agent Mesh）是由 Google 开发的一个零配置、零信任的 P2P 网络，专为自主 AI Agent 设计。它让 AI Agent 节点自动发现彼此、互相认证，并通过标准 MCP（Model Context Protocol）协议跨节点调用工具——不依赖将内部脚本或 API 暴露到公网。

当前状态：公开测试网（bananas.sam-mesh.dev）已上线生产级二进制；正式生产环境仍标记 beta，2026-08-18 有 MarkTechPost 报道关注。

⚠️ 与 SAM (Segment Anything Model) 无关：本文的 SAM = Sovereign Agent Mesh，不是 Google 的图像分割模型，搜索时注意关键词区分。

⚠️ 非官方 Google 产品：README 明确说明"This is not an officially supported Google product"，且没有 Google 漏洞奖励计划资格。

解决什么问题

AI Agent 现在运行在云服务器、本地数据中心、笔记本、Raspberry Pi、安卓设备等各种环境。让它们互相调用工具，传统做法是把内部脚本/LLM 端点/私有 API 暴露到公网——安全风险大且难以管理。

SAM 的解决思路是：把每个 Agent 变成 P2P 网络节点，用加密身份互相认证，在 overlay 网络中互相发现、调用工具，不暴露内网。

核心四原则： - 零配置：节点自动发现彼此，无需手动指定 IP/端口 - 零信任：每个连接、节点、数据包都经过严格认证（基于 Biscuit token） - Agentic Network：轻量级节点（sam-node）提供自愈 P2P 连接，Agent 插上就能通信 - 可移植：加密身份与环境无关，节点可在云/本地/边缘自由迁移

架构概览

SAM 由三个核心组件构成：

组件	职责
sam-control-plane	注册控制面：节点身份注册、授权策略、路由协调
sam-router	数据面：libp2p 引导节点和中继，提供连通性和转发
sam-node	本地客户端：mesh 传输集成 + MCP sidecar 路由

快速安装

方式一：一键安装脚本（推荐）

curl -sL https://sam-mesh.dev/install.sh | bash

方式二：Go 编译安装（需要 Go 环境）

go install github.com/google/sam/cmd/sam-node@latest
go install github.com/google/sam/cmd/sam-control-plane@latest   # 可选：自建控制面
go install github.com/google/sam/cmd/sam-router@latest          # 可选：自建路由节点

方式三：Docker（无需在主机装依赖）

# 下载并运行（--user 确保容器用宿主机的 uid/gid）
mkdir -p $(pwd)/sam-data

docker run -it \
  --user "$(id -u):$(id -g)" \
  -v $(pwd)/sam-data:/data \
  ghcr.io/google/sam-node:latest \
  join --data-dir /data https://bananas.sam-mesh.dev

核心用法

第一步：注册节点（一次性）

sam-node join https://bananas.sam-mesh.dev

交互式流程：CLI 会打开浏览器让你完成 OIDC 认证（ Dex）；认证成功后节点获得 Biscuit 加密身份 token，存储在数据目录。

无浏览器/headless 场景：使用 bootstrap token 方式（需要先从控制面 API 获取 token）：

sam-node join --bootstrap-token <your-token> https://bananas.sam-mesh.dev

⚠️ 注意：headless 模式下，除非控制面配置了 --auto-approve-enrollment，注册请求会保持 PENDING 状态直到管理员手动批准。

第二步：运行节点

# 前台运行（测试用）
SAM_API_TOKEN=my-secret-token sam-node run --bind-addr 127.0.0.1:8080

# 守护进程模式（生产用）
sam-node run --daemonize
# 输出：
# SAM Node Online.
# PID 48213
# Endpoint http://127.0.0.1:8080/mcp
# Token /home/you/.config/sam-mesh/api-token

⚠️ API Token 必须通过环境变量或文件传入，不能作为命令行参数（会被 process listing 暴露）。

Docker 后台运行（推荐生产配置）

mkdir -p $(pwd)/sam-data

docker run -d \
  --name sam-node \
  --user "$(id -u):$(id -g)" \
  -v $(pwd)/sam-data:/data \
  -p 5001:5001/udp \
  -p 5002:5002 \
  -p 8080:8080 \
  -e SAM_API_TOKEN=my-secret-token \
  ghcr.io/google/sam-node:latest \
  run --data-dir /data --bind-addr 0.0.0.0:8080

需要映射端口： - 5001/udp + 5002/tcp：libp2p 协议端口 - 8080/tcp：本地 MCP API

一键加入 + 运行

# --join 同时完成注册和启动（首次注册，后续为 no-op）
SAM_API_TOKEN=my-secret-token sam-node run --join --bind-addr 127.0.0.1:8080

使用 MCP 客户端查询

# 列出本地节点可用工具
mcp-client -url http://localhost:8080/mcp \
  -token my-secret-token \
  -list

# 在公网 mesh 上发现已注册 MCP 服务
mcp-client -url http://localhost:8080/mcp \
  -tool discover_remote_services \
  -args '{"type":"mcp"}'

# 发现指定节点上的工具
mcp-client -url http://localhost:8080/mcp \
  -tool find_remote_tools \
  -args '{"peer_id":"<target-peer-id>"}'

# 跨节点调用远程工具
mcp-client -url http://localhost:8080/mcp \
  -tool call_remote_tool \
  -args '{"peer_id":"<target-peer-id>","tool_name":"everything.get-sum","arguments":{"a":12.5,"b":7.5}}'

安装 Agent Skill（让 AI Agent 自动管理节点）

sam-node skill install
# 安装到各 Agent 的 skill 目录：
# Claude Code / Claude Desktop: ~/.claude/skills/sam-mesh/SKILL.md
# Google Antigravity: ~/.gemini/config/skills/sam-mesh/SKILL.md
# 也支持 --project 或 --dir DIR 自定义路径

安装后重启 Agent，然后直接说"connect to the sam mesh and show me what tools are available"，Agent 会自动启动节点、注册 MCP 端点——唯一需要人类操作的是一次性的 OIDC 登录（设计上要求人类介入）。

重置节点

sam-node reset       # 忘记 mesh 身份，保留 PeerID
sam-node reset --all # 删除所有数据（包括密钥），重新生成 PeerID 并需重新注册

典型适用场景

跨云/本地 Agent 工具共享：同一个 mesh 内的 Agent 可以在不需要暴露 API 的情况下互相调用工具
私有 MCP 工具发现：企业内网多个 Agent 各有专长工具，通过 SAM 自动发现和组合使用
边缘设备 Agent 协作：IoT 边缘设备上的 Agent 通过 mesh 互相调用，不需要每个设备都暴露公网端口
暖池 Agent 调度（Warm Agent Pool）：预先启动一组 Reviewer Agent，新任务通过 mesh 分发给空闲节点处理

坑与注意

公网测试网仍是 beta：README 自述"public mesh is still labelled a beta testnet"，正式生产部署建议自建 control plane + router，而非依赖 bananas.sam-mesh.dev
端口映射是生产部署门槛：libp2p 需要 5001/udp + 5002/tcp 双向可达，NAT/防火墙环境下部署有门槛；文档提供了 Kubernetes 部署参考，但需要一定网络知识
Token 安全模型要求严格：API token 不能写进命令行参数（会出现在 /proc），必须用环境变量或文件；这点比大多数工具严格，初次使用者容易踩坑
Agent Skill 安装路径因 Agent 而异：sam-node skill install 默认写 Claude Code 路径，但 Google Antigravity 路径不同；文档提供了 --dir 参数但不同 Agent 的 skill 扫描路径规范各不一样
与 Segment Anything Model 名称冲突：搜索"SAM"会出现大量图像分割内容；README 专门注明"this is not Segment Anything"，实际使用时需注意关键词区分
没有 CVE/漏洞奖励兜底：项目明确不在 Google VRP 范围内，发现严重漏洞也没有官方激励；生产使用前建议自行安全审计

与同类对比

工具	架构	认证模型	协议	适用场景
SAM	P2P overlay	零信任 + Biscuit token	MCP	Agent 间安全工具互调
传统 VPN	中心化隧道	证书/密码	任意	机器间网络互通
MCP 官方	1:1 连接	无内置 P2P	MCP (原生)	单机 Agent + 本地工具
Agent-Skills.io	独立平台	各家自定	Skill 抽象	跨平台 Agent 技能发现

核心差异：SAM 是唯一把 P2P 网络 + 零信任认证 + MCP 协议三者融合的 Agent 网络层；传统 VPN 不理解 Agent 语义，标准 MCP 不支持 P2P 发现。

一句话推荐结论

如果你在构建需要跨机器协作的 AI Agent 系统（尤其是 Claude Code / Gemini / Antigravity 等支持 Skill 的 Agent），用 curl -sL https://sam-mesh.dev/install.sh | bash 在 5 分钟内把节点加入 bananas.sam-mesh.dev 测试网，然后 sam-node skill install 让 Agent 自动托管——不需要任何 VPN 配置，就能实现跨机器的零信任工具发现和调用。

⚠️ 来源：GitHub README + Quickstart 文档（fetch 自 github.com/google/sam）+ MarkTechPost 2026-08-18 报道 + daily.dev 2026-08-18 报道；API Token 禁止命令行参数、Docker 端口要求、beta 测试网状态均 fetch 自文档原文；不 clone、不跑代码。