shazhou-ww 62b30e57ef docs: add SORA squad setup guide and landing page

- SORA setup guide (Step 0-10): install, config, A2A, public access
- SORA landing page at docs/sora/index.md
- Updated nav and site description for 4 squads

2026-03-30 10:09:09 +00:00

11 KiB

Raw Blame History

🌌 SORA 小队 Setup 指南

欢迎星月！这份指南帮你从零搭建 SORA 小队的 OpenClaw Gateway，并接入大家庭。

你将得到什么

graph LR
    subgraph "SORA 🌌 (星月的设备)"
        GW_SORA[Gateway :18789]
        AG[你的 Agents]
        GW_SORA --- AG
    end
    subgraph "KUMA 🐻"
        GW_KUMA[小墨 🖊️]
    end
    subgraph "NEKO 🐱"
        GW_NEKO[小橘 🍊]
    end
    subgraph "RAKU 🐉"
        GW_RAKU[敖丙 🐲]
    end
    GW_SORA <-->|A2A| GW_KUMA
    GW_SORA <-->|A2A| GW_NEKO
    GW_SORA <-->|A2A| GW_RAKU

完成后你的小队将和 KUMA、NEKO、RAKU 互通，可以跨队发消息、传文件、协作完成任务。

Step 0：确认你的环境

先确认一下设备情况，不同平台走不同路线：

环境	推荐方案	公网接入
Azure/云 VM (Linux)	直接安装 + nginx 反代	Let's Encrypt SSL
家用 PC (Windows/Mac)	本地安装 + Cloudflare Tunnel	CF Tunnel 自动 TLS
WSL2 (Windows 下的 Linux)	在 WSL 内安装	CF Tunnel 或 nginx

!!! tip "新手建议" 如果你有 Azure 账号，开一台 Standard_B2s（2 vCPU / 4GB）就够了，月费很低。如果用家用 PC，参考 RAKU 的 Cloudflare Tunnel 方案。

Step 1：安装 OpenClaw

安装 Node.js (v20+)

=== "Ubuntu/Debian"

```bash
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt-get install -y nodejs
```

=== "macOS"

```bash
brew install node@22
```

=== "Windows"

下载 [nvm-windows](https://github.com/coreybutler/nvm-windows/releases)，然后：
```powershell
nvm install 22
nvm use 22
```

安装 OpenClaw

npm install -g openclaw
openclaw --version   # 确认安装成功

Step 2：初始化 Gateway

# 首次启动，会自动创建 ~/.openclaw/ 目录和配置文件
openclaw gateway start
openclaw gateway stop   # 先停下来，我们要改配置

Step 3：配置 LLM Provider

你需要至少一个 LLM provider。几种方案：

方案 A：使用团队共享的 LiteLLM（推荐）

联系小墨 (KUMA) 或小橘 (NEKO) 获取 LiteLLM 访问凭证，然后配置：

{
  "providers": {
    "litellm": {
      "type": "openai",
      "baseUrl": "https://<litellm-endpoint>/v1",
      "apiKey": "<your-litellm-key>"
    }
  }
}

方案 B：自己的 API Key

直接用你自己的 API Key（OpenAI、Anthropic 等）：

{
  "providers": {
    "anthropic": {
      "type": "anthropic",
      "apiKey": "sk-ant-..."
    }
  }
}

方案 C：GitHub Copilot API

如果你有 Copilot 订阅：

{
  "providers": {
    "copilot-api": {
      "type": "copilot",
      "apiKey": "<copilot-token>"
    }
  }
}

Step 4：创建你的 Agent

编辑 ~/.openclaw/openclaw.json，添加 agents：

{
  "agents": {
    "defaults": {
      "model": "litellm/claude-sonnet-4.6"
    },
    "list": [
      {
        "id": "main",
        "name": "你的协调者名字",
        "description": "SORA 小队协调者"
      }
    ]
  }
}

设置身份文件

cd ~/.openclaw/workspace

创建以下文件：

SOUL.md — 你的 Agent 的灵魂/人格：

# SOUL.md

## 身份
**[你的Agent名字]** — SORA 小队协调者

## 核心原则
- 专业简洁
- 主动思考
- ...（根据你的风格定制）

USER.md — 关于你的信息：

# USER.md

- **Name:** 星月
- **What to call them:** [你喜欢的称呼]
- **Timezone:** [你的时区，如 Asia/Shanghai]

AGENTS.md — 行为规范（可以参考 KUMA 的 AGENTS.md，找小墨要）

Step 5：配置消息通道

选择你常用的聊天平台：

=== "Telegram"

1. 找 [@BotFather](https://t.me/BotFather) 创建一个 bot
2. 拿到 Bot Token
3. 配置：
```json
{
  "messages": {
    "telegram": {
      "enabled": true,
      "accounts": {
        "default": {
          "botToken": "<你的 Bot Token>"
        }
      }
    }
  }
}
```
4. 给 bot 发消息就能和你的 Agent 聊天了

=== "飞书"

1. 在飞书开放平台创建应用
2. 获取 App ID 和 App Secret
3. 配置：
```json
{
  "messages": {
    "feishu": {
      "enabled": true,
      "appId": "<App ID>",
      "appSecret": "<App Secret>"
    }
  }
}
```

Step 6：公网接入（A2A 互通必需）

要和其他小队 A2A 通信，你的 Gateway 需要一个公网可达的 HTTPS 端点。

选一个域名

向主人申请一个 oc-sora.shazhou.work 子域名（或用你自己的域名）。

=== "Azure VM + nginx"

**1. 安装 nginx + certbot：**
```bash
sudo apt update
sudo apt install -y nginx certbot python3-certbot-nginx
```

**2. 配置 nginx：**
```nginx
server {
    listen 80;
    server_name oc-sora.shazhou.work;

    # OpenClaw Gateway（Dashboard + WebSocket）
    location / {
        proxy_pass http://127.0.0.1:18789;
        proxy_set_header Host $host;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }

    # A2A Gateway
    location /a2a/ {
        proxy_pass http://127.0.0.1:18800/a2a/;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_buffering off;
        proxy_read_timeout 120s;
    }

    # A2A Agent Card
    location /.well-known/agent-card.json {
        proxy_pass http://127.0.0.1:18800/.well-known/agent-card.json;
        proxy_set_header Host $host;
    }
}
```

**3. 申请 SSL 证书：**
```bash
sudo certbot --nginx -d oc-sora.shazhou.work --non-interactive --agree-tos --email <你的邮箱>
```

**4. 开放 Azure NSG 端口：**
确保 NSG 放行 443（HTTPS）入站。

=== "家用 PC + Cloudflare Tunnel"

**1. 安装 cloudflared：**
```bash
# Linux
curl -L https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-linux-amd64 -o cloudflared
chmod +x cloudflared && sudo mv cloudflared /usr/local/bin/

# Windows (PowerShell)
winget install Cloudflare.cloudflared
```

**2. 登录并创建 Tunnel：**
```bash
cloudflared tunnel login
cloudflared tunnel create sora
```

**3. 配置 Tunnel（`~/.cloudflared/config.yml`）：**
```yaml
tunnel: <tunnel-id>
credentials-file: ~/.cloudflared/<tunnel-id>.json

ingress:
  - hostname: oc-sora.shazhou.work
    service: http://127.0.0.1:18800
    originRequest:
      noTLSVerify: true
  - service: http_status:404
```

**4. 在 Cloudflare DNS 添加 CNAME：**
`oc-sora.shazhou.work` → `<tunnel-id>.cfargotunnel.com`

**5. 启动：**
```bash
cloudflared tunnel run sora
```

Step 7：配置 A2A 插件

安装插件

mkdir -p ~/.openclaw/workspace/plugins
cd ~/.openclaw/workspace/plugins
git clone https://github.com/win4r/openclaw-a2a-gateway.git a2a-gateway
cd a2a-gateway
npm install --production

启用插件

openclaw config set plugins.entries.a2a-gateway.enabled true

配置 A2A

在 openclaw.json 的 plugins.entries.a2a-gateway 下添加：

{
  "enabled": true,
  "config": {
    "agentCard": {
      "name": "SORA 小队",
      "description": "SORA 小队 A2A Gateway — 星月的小队 🌌",
      "url": "https://oc-sora.shazhou.work/a2a/jsonrpc"
    },
    "server": {
      "host": "0.0.0.0",
      "port": 18800
    },
    "security": {
      "inboundAuth": "bearer",
      "token": "<生成你的入站 token>"
    },
    "routing": {
      "defaultAgentId": "main"
    },
    "peers": []
  }
}

生成你的入站 Token

openssl rand -hex 24

记好这个 token，等下要发给其他小队。

Step 8：接入大家庭

Token 互换

!!! danger "安全规则" Token 只通过 A2A 点对点传输，不在飞书、Telegram 等 IM 里发送。第一次没有 A2A 连接怎么办？找主人居中协调即可。

你需要：

把你的入站 token 告诉主人
主人会给你其他小队的入站 token
配置 peers：

"peers": [
  {
    "name": "KUMA",
    "agentCardUrl": "https://oc-kuma.shazhou.work/.well-known/agent-card.json",
    "auth": { "type": "bearer", "token": "<kuma 给你的 token>" }
  },
  {
    "name": "NEKO",
    "agentCardUrl": "https://oc-neko.shazhou.work/.well-known/agent-card.json",
    "auth": { "type": "bearer", "token": "<neko 给你的 token>" }
  },
  {
    "name": "RAKU",
    "agentCardUrl": "https://oc-raku.shazhou.work/.well-known/agent-card.json",
    "auth": { "type": "bearer", "token": "<raku 给你的 token>" }
  }
]

同时，KUMA / NEKO / RAKU 也会在各自的 peers 里加上你。

Step 9：启动！

# 安装为系统服务（开机自启）
openclaw gateway install

# 启动
openclaw gateway start

# 确认状态
openclaw status

验证 A2A

# 检查你的 Agent Card 是否对外可访问
curl -s https://oc-sora.shazhou.work/.well-known/agent-card.json | python3 -m json.tool

# 测试向 KUMA 发消息（让小墨帮你确认收到没）

Step 10：设置为 systemd 服务（Linux 推荐）

openclaw gateway install    # 自动创建 systemd service
sudo systemctl enable openclaw-gateway
sudo systemctl start openclaw-gateway

验证：

sudo systemctl status openclaw-gateway
openclaw gateway status

验证清单

openclaw --version 正常输出
openclaw status 显示 Gateway running
Agent Card HTTPS 可访问
消息通道连通（Telegram/飞书能收发消息）
至少与一个小队 A2A 互通测试成功
SOUL.md / USER.md / AGENTS.md 已创建
systemd 服务已安装（Linux）

避坑指南

!!! warning "血泪教训（从前辈们那里学来的）"

❌ 别这样	✅ 应该这样
改 `gateway.bind` 为 `lan`	保持 `loopback`，用 nginx 反代
手动改 systemd service 里的端口	用 `openclaw config set` 改配置
TLS 字段写错了直接重启	改完先 `openclaw gateway status` 验证配置
Token 在群聊里发	通过 A2A 或主人居中传递
一次改太多配置	每次只改一项，改完验证再改下一项

更多详见 Gateway 配置红线。

参考文档

Gateway 本地搭建 — 更详细的 Gateway 配置说明
A2A 跨队通信 — A2A 协议和配置详解
Gateway 配置红线 — 不要踩的坑
M2 三层管理模式 — Agent 协调的最佳实践

🌌 欢迎加入，星月！有问题随时问大家～

11 KiB Raw Blame History