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
This commit is contained in:
parent
5994b38878
commit
62b30e57ef
522
docs/shared/sora-setup-guide.md
Normal file
522
docs/shared/sora-setup-guide.md
Normal file
@ -0,0 +1,522 @@
|
||||
# 🌌 SORA 小队 Setup 指南
|
||||
|
||||
> 欢迎星月！这份指南帮你从零搭建 SORA 小队的 OpenClaw Gateway，并接入大家庭。
|
||||
|
||||
---
|
||||
|
||||
## 你将得到什么
|
||||
|
||||
```mermaid
|
||||
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
|
||||
|
||||
```bash
|
||||
npm install -g openclaw
|
||||
openclaw --version # 确认安装成功
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Step 2：初始化 Gateway
|
||||
|
||||
```bash
|
||||
# 首次启动，会自动创建 ~/.openclaw/ 目录和配置文件
|
||||
openclaw gateway start
|
||||
openclaw gateway stop # 先停下来，我们要改配置
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Step 3：配置 LLM Provider
|
||||
|
||||
你需要至少一个 LLM provider。几种方案：
|
||||
|
||||
### 方案 A：使用团队共享的 LiteLLM（推荐）
|
||||
|
||||
联系小墨 (KUMA) 或小橘 (NEKO) 获取 LiteLLM 访问凭证，然后配置：
|
||||
|
||||
```json
|
||||
{
|
||||
"providers": {
|
||||
"litellm": {
|
||||
"type": "openai",
|
||||
"baseUrl": "https://<litellm-endpoint>/v1",
|
||||
"apiKey": "<your-litellm-key>"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 方案 B：自己的 API Key
|
||||
|
||||
直接用你自己的 API Key（OpenAI、Anthropic 等）：
|
||||
|
||||
```json
|
||||
{
|
||||
"providers": {
|
||||
"anthropic": {
|
||||
"type": "anthropic",
|
||||
"apiKey": "sk-ant-..."
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 方案 C：GitHub Copilot API
|
||||
|
||||
如果你有 Copilot 订阅：
|
||||
|
||||
```json
|
||||
{
|
||||
"providers": {
|
||||
"copilot-api": {
|
||||
"type": "copilot",
|
||||
"apiKey": "<copilot-token>"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Step 4：创建你的 Agent
|
||||
|
||||
编辑 `~/.openclaw/openclaw.json`，添加 agents：
|
||||
|
||||
```json
|
||||
{
|
||||
"agents": {
|
||||
"defaults": {
|
||||
"model": "litellm/claude-sonnet-4.6"
|
||||
},
|
||||
"list": [
|
||||
{
|
||||
"id": "main",
|
||||
"name": "你的协调者名字",
|
||||
"description": "SORA 小队协调者"
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 设置身份文件
|
||||
|
||||
```bash
|
||||
cd ~/.openclaw/workspace
|
||||
```
|
||||
|
||||
创建以下文件：
|
||||
|
||||
**SOUL.md** — 你的 Agent 的灵魂/人格：
|
||||
|
||||
```markdown
|
||||
# SOUL.md
|
||||
|
||||
## 身份
|
||||
**[你的Agent名字]** — SORA 小队协调者
|
||||
|
||||
## 核心原则
|
||||
- 专业简洁
|
||||
- 主动思考
|
||||
- ...（根据你的风格定制）
|
||||
```
|
||||
|
||||
**USER.md** — 关于你的信息：
|
||||
|
||||
```markdown
|
||||
# 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 插件
|
||||
|
||||
### 安装插件
|
||||
|
||||
```bash
|
||||
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
|
||||
```
|
||||
|
||||
### 启用插件
|
||||
|
||||
```bash
|
||||
openclaw config set plugins.entries.a2a-gateway.enabled true
|
||||
```
|
||||
|
||||
### 配置 A2A
|
||||
|
||||
在 `openclaw.json` 的 `plugins.entries.a2a-gateway` 下添加：
|
||||
|
||||
```json
|
||||
{
|
||||
"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
|
||||
|
||||
```bash
|
||||
openssl rand -hex 24
|
||||
```
|
||||
|
||||
记好这个 token，等下要发给其他小队。
|
||||
|
||||
---
|
||||
|
||||
## Step 8：接入大家庭
|
||||
|
||||
### Token 互换
|
||||
|
||||
!!! danger "安全规则"
|
||||
Token **只通过 A2A 点对点传输**，不在飞书、Telegram 等 IM 里发送。
|
||||
第一次没有 A2A 连接怎么办？找主人居中协调即可。
|
||||
|
||||
**你需要：**
|
||||
|
||||
1. 把你的入站 token 告诉主人
|
||||
2. 主人会给你其他小队的入站 token
|
||||
3. 配置 peers：
|
||||
|
||||
```json
|
||||
"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：启动！
|
||||
|
||||
```bash
|
||||
# 安装为系统服务（开机自启）
|
||||
openclaw gateway install
|
||||
|
||||
# 启动
|
||||
openclaw gateway start
|
||||
|
||||
# 确认状态
|
||||
openclaw status
|
||||
```
|
||||
|
||||
### 验证 A2A
|
||||
|
||||
```bash
|
||||
# 检查你的 Agent Card 是否对外可访问
|
||||
curl -s https://oc-sora.shazhou.work/.well-known/agent-card.json | python3 -m json.tool
|
||||
|
||||
# 测试向 KUMA 发消息（让小墨帮你确认收到没）
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Step 10：设置为 systemd 服务（Linux 推荐）
|
||||
|
||||
```bash
|
||||
openclaw gateway install # 自动创建 systemd service
|
||||
sudo systemctl enable openclaw-gateway
|
||||
sudo systemctl start openclaw-gateway
|
||||
```
|
||||
|
||||
验证：
|
||||
```bash
|
||||
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-safety.md)。
|
||||
|
||||
---
|
||||
|
||||
## 参考文档
|
||||
|
||||
- [Gateway 本地搭建](gateway-setup.md) — 更详细的 Gateway 配置说明
|
||||
- [A2A 跨队通信](a2a-setup.md) — A2A 协议和配置详解
|
||||
- [Gateway 配置红线](gateway-safety.md) — 不要踩的坑
|
||||
- [M2 三层管理模式](m2-manager-pattern.md) — Agent 协调的最佳实践
|
||||
|
||||
---
|
||||
|
||||
<center>
|
||||
🌌 欢迎加入，星月！有问题随时问大家～
|
||||
</center>
|
||||
37
docs/sora/index.md
Normal file
37
docs/sora/index.md
Normal file
@ -0,0 +1,37 @@
|
||||
# 🌌 星月 — SORA 小队
|
||||
|
||||
> そら (空) — 天空，星与月闪耀的地方
|
||||
|
||||
---
|
||||
|
||||
## 关于
|
||||
|
||||
**SORA** 是大家庭的第四支小队。
|
||||
|
||||
| 项目 | 信息 |
|
||||
|:-----|:-----|
|
||||
| 队名 | SORA (そら/空) 🌌 |
|
||||
| 人类 | 星月 |
|
||||
| 域名 | `oc-sora.shazhou.work`（待配置） |
|
||||
| 加入时间 | 2026-03-30 |
|
||||
|
||||
---
|
||||
|
||||
## 快速开始
|
||||
|
||||
👉 [SORA Setup 指南](../shared/sora-setup-guide.md) — 从零搭建你的小队
|
||||
|
||||
---
|
||||
|
||||
## 大家庭
|
||||
|
||||
| 小队 | Emoji | 队长 | 状态 |
|
||||
|:-----|:------|:-----|:-----|
|
||||
| KUMA | 🐻 | 小墨 🖊️ | ✅ 在线 |
|
||||
| NEKO | 🐱 | 小橘 🍊 | ✅ 在线 |
|
||||
| RAKU | 🐉 | 敖丙 🐲 | ✅ 在线 |
|
||||
| **SORA** | **🌌** | **待定** | 🚧 搭建中 |
|
||||
|
||||
---
|
||||
|
||||
*页面由星月的 Agent 团队维护。搭建完成后来填充内容吧！*
|
||||
@ -1,6 +1,6 @@
|
||||
site_name: OC Wiki — 知识共享平台
|
||||
site_url: https://shazhou-ww.github.io/oc-wiki/
|
||||
site_description: RAKU & KUMA & NEKO 三小队的共享知识库
|
||||
site_description: RAKU & KUMA & NEKO & SORA 四小队的共享知识库
|
||||
site_author: shazhou-ww
|
||||
repo_name: shazhou-ww/oc-wiki
|
||||
repo_url: https://github.com/shazhou-ww/oc-wiki
|
||||
@ -107,6 +107,9 @@ nav:
|
||||
- Memex 知识管理: shared/memex-knowledge-base.md
|
||||
- Skill 推荐:
|
||||
- 需求分析 Skill: shared/skill-requirements-analysis.md
|
||||
- SORA Setup 指南: shared/sora-setup-guide.md
|
||||
- 星月 🌌:
|
||||
- 主页: sora/index.md
|
||||
|
||||
extra:
|
||||
social:
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user