OpenClaw Studio 入门指南

博主： admin
发布时间：2026 年 03 月 01 日
0 次浏览
暂无评论
5079字数
分类： WebSocket 人工智能学习笔记 node 运维技术文档

# OpenClaw Studio 入门指南

# 一、概述

## 1. 简介
### A. 是什么
OpenClaw Studio 是一个简洁的 Web 仪表板，用于管理和控制 OpenClaw Gateway。它提供统一的界面来连接 Gateway、查看和创建 agents、进行对话、管理审批任务以及配置定时作业。

### B. 为什么学
- 提供可视化界面，简化 OpenClaw 的操作流程
- 支持多种部署场景，满足本地和云端需求
- 集中管理 agents、聊天、审批和作业配置

### C. 学完能做什么
- 在本地或云端部署 OpenClaw Studio
- 配置 Studio 与 Gateway 的连接
- 使用 Studio 界面管理 agents 和执行任务

# 二、环境准备

## 1. 系统要求
- Node.js 18+（推荐使用 LTS 版本）
- OpenClaw Gateway URL 和访问 token
- Tailscale（可选，推荐用于远程访问）

## 2. 安装步骤

### 推荐安装方式（npx）
```bash
npx -y openclaw-studio@latest
```

### 从源码安装（高级用户）
```bash
git clone https://github.com/grp06/openclaw-studio.git
cd openclaw-studio
npm install
npm run dev
```

## 3. 验证安装
安装完成后，在浏览器中打开 http://localhost:3000，确认 Studio 界面正常加载。

# 三、核心概念

## 1. 基本术语
- Gateway：OpenClaw 的核心服务，负责 agents 的执行和管理
- Studio：Web 仪表板，提供图形化界面与 Gateway 交互
- Upstream：Studio 连接到 Gateway 的上游服务
- Agent：可执行特定任务的智能代理
- Tailscale：虚拟网络服务，用于安全的远程访问

## 2. 工作原理

OpenClaw Studio 采用双路径网络架构，Studio 作为中间层连接浏览器和 Gateway。

```mermaid
graph LR
    subgraph 用户终端
        Browser[浏览器]
    end

subgraph Studio主机
 Studio[OpenClaw Studio Web服务]
 WS1[WebSocket 3000端口]
 end

subgraph Gateway主机
 Gateway[OpenClaw Gateway]
 WS2[WebSocket 18789端口]
 end

![OpenClaw Studio 工作原理](https://static.op123.ren/static/7e/7ea3c2e0e9617f7b.svg)

网络连接说明：
- 浏览器到 Studio：HTTP 用于 UI 界面，WebSocket 用于实时更新
- Studio 到 Gateway：Studio 服务器通过 WebSocket 连接配置的上游 URL

## 3. 部署模式

Studio 支持三种常见的部署场景，根据 Gateway 和 Studio 的运行位置选择合适的方式。

# 四、快速上手

## 1. 场景选择

根据你的网络环境选择部署场景：

- 场景 A：Gateway 本地运行，Studio 本地运行（同一台计算机）
- 场景 B：Gateway 云端运行，Studio 本地运行（你的笔记本电脑）
- 场景 C：Studio 云端运行，Gateway 云端运行（始终在线）

## 2. 场景 A：Gateway 本地，Studio 本地

适用于开发和测试环境，两者在同一台计算机上运行。

### 安装和启动
```bash
npx -y openclaw-studio@latest
cd openclaw-studio
npm run dev
```

### 配置连接
打开 http://localhost:3000，在 Studio 中设置：

- Upstream URL: ws://localhost:18789
- Upstream Token: 你的 Gateway token（可通过 openclaw config get gateway.auth.token 获取）

## 3. 场景 B：Gateway 云端，Studio 本地

适用于 Gateway 部署在云服务器，而在本地进行管理的场景。

### 运行 Studio
```bash
npx -y openclaw-studio@latest
cd openclaw-studio
npm run dev
```

### 配置网络连接

#### 方案一：Tailscale Serve（推荐）

在 Gateway 主机上：
```bash
tailscale serve --yes --bg --https 443 http://127.0.0.1:18789
```

在 Studio（你的笔记本）中：
- Upstream URL: wss://<gateway-host>.ts.net
- Upstream Token: 你的 Gateway token

#### 方案二：SSH 隧道

从你的笔记本执行：
```bash
ssh -L 18789:127.0.0.1:18789 user@<gateway-host>
```

在 Studio 中：
- Upstream URL: ws://localhost:18789

## 4. 场景 C：Studio 云端，Gateway 云端

适用于始终在线的生产环境，推荐使用 Tailscale 实现安全访问。

### 在 VPS 上运行 Studio
```bash
npx -y openclaw-studio@latest
cd openclaw-studio
npm run dev
```

### 暴露 Studio 到 Tailnet
```bash
tailscale serve --yes --bg --https 443 http://127.0.0.1:3000
```

### 访问和配置
从你的笔记本或手机打开：https://<studio-host>.ts.net

在 Studio 中设置：
- Upstream URL: wss://<gateway-host>.ts.net
- 或者其他 Studio 主机可以访问的 Gateway 地址
- Upstream Token: 你的 Gateway token

# 五、配置说明

## 1. 配置文件路径

- OpenClaw 配置：~/.openclaw/openclaw.json
  - 可通过环境变量 OPENCLAW_CONFIG_PATH 或 OPENCLAW_STATE_DIR 覆盖

- Studio 设置：~/.openclaw/openclaw-studio/settings.json

## 2. 环境变量

| 变量名 | 说明 | 默认值 | 是否必填 |
|-------|------|--------|---------|
| NEXT_PUBLIC_GATEWAY_URL | 默认 Gateway URL | ws://localhost:18789 | 否 |
| STUDIO_ACCESS_TOKEN | Studio 访问令牌 | 无 | 有条件必填 |
| HOST | 绑定主机地址 | 127.0.0.1 | 否 |

STUDIO_ACCESS_TOKEN 使用规则：
- 绑定到公网主机时必填（HOST=0.0.0.0、HOST=:: 或非回环地址）
- 仅绑定到回环地址时可省略（127.0.0.1、::1、localhost）

## 3. 网络配置注意事项

- 避免将 Studio 部署在 /studio 路径下，除非配置 basePath 并重新构建
- 如果 Studio 可从非回环地址访问，必须设置 STUDIO_ACCESS_TOKEN
- 使用 /?access_token=... 一次性设置访问令牌的 cookie

# 六、故障排查

## 1. 连接失败

如果 UI 加载正常但连接失败，通常是 Studio 到 Gateway 的连接问题：

- 检查上游 URL 和 token 是否正确
- 配置存储位置：<state dir>/openclaw-studio/settings.json

## 2. 常见错误码

| 错误 | 原因 | 解决方案 |
|------|------|---------|
| EPROTO 或 wrong version number | 使用 wss:// 连接非 TLS 端点 | 改用 ws://，或将 Gateway 置于 HTTPS 后 |
| Assets 404 under /studio | Studio 部署在 /studio 路径 | 在根路径 / 部署，或配置 basePath |
| Studio access token required | 未提供 STUDIO_ACCESS_TOKEN | 设置环境变量或通过 /?access_token=... 设置 |
| studio.gateway_url_missing | Gateway URL 未配置 | 在 Studio 设置中配置 Upstream URL |
| studio.gateway_token_missing | Gateway token 未配置 | 在 Studio 设置中配置 Upstream Token |
| studio.upstream_error | 上游连接错误 | 检查 Gateway 是否运行且可访问 |
| studio.upstream_closed | 上游连接关闭 | 检查网络连接和 Gateway 状态 |

# 七、进阶功能

## 1. UI 工作流
详见 docs/ui-guide.md，了解以下功能的操作流程：
- Agent 创建
- Cron 定时任务配置
- 执行审批管理

## 2. PI 和聊天流式传输
详见 docs/pi-chat-streaming.md，了解：
- Studio 如何将浏览器 WebSocket 流量桥接到上游 Gateway
- 运行时流式事件（聊天/agent 事件）如何到达
- 聊天 UI 如何渲染工具调用、思考追踪和最终对话行

## 3. 权限和沙箱
详见 docs/permissions-sandboxing.md，了解：
- Agent 创建选项（工具策略、沙箱配置、执行审批）
- 这些设置如何从 Studio 流向 OpenClaw Gateway
- 上游 OpenClaw 在运行时如何强制执行这些设置

## 4. 颜色系统
详见 docs/color-system.md，了解：
- 语义化颜色契约
- 状态映射规则
- 确保 action/status/danger 在 UI 中一致使用的防护措施

## 5. 架构详情
详见 ARCHITECTURE.md，了解：
- 模块组织结构
- 数据流设计
- 系统组件交互

***

## 参考资料

1. [OpenClaw Studio GitHub 仓库](https://github.com/grp06/openclaw-studio)
2. [OpenClaw 官方文档](https://github.com/anthropics/openclaw)

最后修改：2026 年 03 月 01 日

如果觉得我的文章对你有用，请随意赞赏

发表评论取消回复
使用cookie技术保留您的个人信息以便您下次快速评论，继续评论表示您已同意该条款

评论 *

私密评论

名称 *

🎲

邮箱 *

地址

OpenClaw Studio 入门指南

admin • 2026 年 03 月 01 日

# OpenClaw Studio 入门指南

# 一、概述

### B. 为什么学
- 提供可视化界面，简化 OpenClaw 的操作流程
- 支持多种部署场景，满足本地和云端需求
- 集中管理 agents、聊天、审批和作业配置

### C. 学完能做什么
- 在本地或云端部署 OpenClaw Studio
- 配置 Studio 与 Gateway 的连接
- 使用 Studio 界面管理 agents 和执行任务

# 二、环境准备

## 1. 系统要求
- Node.js 18+（推荐使用 LTS 版本）
- OpenClaw Gateway URL 和访问 token
- Tailscale（可选，推荐用于远程访问）

## 2. 安装步骤

### 推荐安装方式（npx）
```bash
npx -y openclaw-studio@latest
```

### 从源码安装（高级用户）
```bash
git clone https://github.com/grp06/openclaw-studio.git
cd openclaw-studio
npm install
npm run dev
```

## 3. 验证安装
安装完成后，在浏览器中打开 http://localhost:3000，确认 Studio 界面正常加载。

# 三、核心概念

## 2. 工作原理

OpenClaw Studio 采用双路径网络架构，Studio 作为中间层连接浏览器和 Gateway。

```mermaid
graph LR
    subgraph 用户终端
        Browser[浏览器]
    end

subgraph Studio主机
 Studio[OpenClaw Studio Web服务]
 WS1[WebSocket 3000端口]
 end

subgraph Gateway主机
 Gateway[OpenClaw Gateway]
 WS2[WebSocket 18789端口]
 end

![OpenClaw Studio 工作原理](https://static.op123.ren/static/7e/7ea3c2e0e9617f7b.svg)

网络连接说明：
- 浏览器到 Studio：HTTP 用于 UI 界面，WebSocket 用于实时更新
- Studio 到 Gateway：Studio 服务器通过 WebSocket 连接配置的上游 URL

## 3. 部署模式

Studio 支持三种常见的部署场景，根据 Gateway 和 Studio 的运行位置选择合适的方式。

# 四、快速上手

## 1. 场景选择

根据你的网络环境选择部署场景：

## 2. 场景 A：Gateway 本地，Studio 本地

适用于开发和测试环境，两者在同一台计算机上运行。

### 安装和启动
```bash
npx -y openclaw-studio@latest
cd openclaw-studio
npm run dev
```

### 配置连接
打开 http://localhost:3000，在 Studio 中设置：

- Upstream URL: ws://localhost:18789
- Upstream Token: 你的 Gateway token（可通过 openclaw config get gateway.auth.token 获取）

## 3. 场景 B：Gateway 云端，Studio 本地

适用于 Gateway 部署在云服务器，而在本地进行管理的场景。

### 运行 Studio
```bash
npx -y openclaw-studio@latest
cd openclaw-studio
npm run dev
```

### 配置网络连接

#### 方案一：Tailscale Serve（推荐）

在 Gateway 主机上：
```bash
tailscale serve --yes --bg --https 443 http://127.0.0.1:18789
```

在 Studio（你的笔记本）中：
- Upstream URL: wss://<gateway-host>.ts.net
- Upstream Token: 你的 Gateway token

#### 方案二：SSH 隧道

从你的笔记本执行：
```bash
ssh -L 18789:127.0.0.1:18789 user@<gateway-host>
```

在 Studio 中：
- Upstream URL: ws://localhost:18789

## 4. 场景 C：Studio 云端，Gateway 云端

适用于始终在线的生产环境，推荐使用 Tailscale 实现安全访问。

### 在 VPS 上运行 Studio
```bash
npx -y openclaw-studio@latest
cd openclaw-studio
npm run dev
```

### 暴露 Studio 到 Tailnet
```bash
tailscale serve --yes --bg --https 443 http://127.0.0.1:3000
```

### 访问和配置
从你的笔记本或手机打开：https://<studio-host>.ts.net

在 Studio 中设置：
- Upstream URL: wss://<gateway-host>.ts.net
- 或者其他 Studio 主机可以访问的 Gateway 地址
- Upstream Token: 你的 Gateway token

# 五、配置说明

## 1. 配置文件路径

- OpenClaw 配置：~/.openclaw/openclaw.json
  - 可通过环境变量 OPENCLAW_CONFIG_PATH 或 OPENCLAW_STATE_DIR 覆盖

- Studio 设置：~/.openclaw/openclaw-studio/settings.json

## 2. 环境变量

STUDIO_ACCESS_TOKEN 使用规则：
- 绑定到公网主机时必填（HOST=0.0.0.0、HOST=:: 或非回环地址）
- 仅绑定到回环地址时可省略（127.0.0.1、::1、localhost）

## 3. 网络配置注意事项

# 六、故障排查

## 1. 连接失败

如果 UI 加载正常但连接失败，通常是 Studio 到 Gateway 的连接问题：

- 检查上游 URL 和 token 是否正确
- 配置存储位置：<state dir>/openclaw-studio/settings.json

## 2. 常见错误码

# 七、进阶功能

## 1. UI 工作流
详见 docs/ui-guide.md，了解以下功能的操作流程：
- Agent 创建
- Cron 定时任务配置
- 执行审批管理

## 4. 颜色系统
详见 docs/color-system.md，了解：
- 语义化颜色契约
- 状态映射规则
- 确保 action/status/danger 在 UI 中一致使用的防护措施

## 5. 架构详情
详见 ARCHITECTURE.md，了解：
- 模块组织结构
- 数据流设计
- 系统组件交互

***

## 参考资料

1. [OpenClaw Studio GitHub 仓库](https://github.com/grp06/openclaw-studio)
2. [OpenClaw 官方文档](https://github.com/anthropics/openclaw)

OpenClaw Studio 入门指南

发表评论取消回复
使用cookie技术保留您的个人信息以便您下次快速评论，继续评论表示您已同意该条款

搭建国内LabHub

CentOS 7.9 编译并使用rpm方式升级openssh9.6p1（包括后续更新9.8p1等）

一天从 redis 大 key 开始

安装eve-ng

重装ensp

Tencent 开源 WeKnora：智能文档理解与检索框架

社交文件系统 AT 协议技术分析

wireguard 客户端 for linux

活久见 opentsdb三字节id用完了

CRS 全流程拆解｜中国人如何让海外账户不被交换回中国大陆

OpenClaw Studio 入门指南

发表评论 取消回复 使用cookie技术保留您的个人信息以便您下次快速评论，继续评论表示您已同意该条款

OpenClaw Studio 入门指南

发表评论取消回复
使用cookie技术保留您的个人信息以便您下次快速评论，继续评论表示您已同意该条款