diff --git a/docs/zh-CN/install/hetzner.md b/docs/zh-CN/install/hetzner.md index 41c5a39f0..2251f7ed2 100644 --- a/docs/zh-CN/install/hetzner.md +++ b/docs/zh-CN/install/hetzner.md @@ -1,89 +1,89 @@ --- read_when: - - 你想让 OpenClaw 在云 VPS 上 24/7 运行（而不是在你的笔记本上） - - 你想在自己的 VPS 上部署一个生产级、始终在线的 Gateway 网关 - - 你想完全控制持久化、二进制文件和重启行为 - - 你正在 Hetzner 或类似提供商上通过 Docker 运行 OpenClaw -summary: 在低成本的 Hetzner VPS（Docker）上 24/7 运行 OpenClaw Gateway 网关，提供持久化状态和内置二进制文件 + - 你希望 OpenClaw 在云 VPS 上全天候运行（而不是你的笔记本电脑） + - 你想在自己的虚拟专用服务器上运行生产级、始终在线的 Gateway 网关 + - 你想完全掌控持久化、二进制文件和重启行为 + - 你正在 Hetzner 或类似提供商的 Docker 中运行 OpenClaw +summary: 在廉价的 Hetzner VPS（Docker）上全天候运行 OpenClaw Gateway 网关，并具备持久状态和内置二进制文件 title: Hetzner x-i18n: - generated_at: "2026-04-27T06:05:16Z" - model: gpt-5.4 + generated_at: "2026-04-29T03:21:08Z" + model: gpt-5.5 provider: openai - source_hash: c81b597601daf9af4daa5fb6061fa847c0fd19990de6cfcc8de405fdacbb011d + source_hash: 96b5b54bfd8d976c575ecffcd229106fc322b9a53828a9d7358f583434b7bbc2 source_path: install/hetzner.md - workflow: 15 + workflow: 16 --- # Hetzner 上的 OpenClaw（Docker，生产 VPS 指南） ## 目标 -在 Hetzner VPS 上使用 Docker 运行一个持久化的 OpenClaw Gateway 网关，并具备持久状态、内置二进制文件以及安全的重启行为。 +使用 Docker 在 Hetzner VPS 上运行一个持久化的 OpenClaw Gateway 网关，具备持久状态、内置二进制文件和安全的重启行为。 -如果你想要“每月约 5 美元实现 OpenClaw 24/7 在线”，这是最简单且可靠的配置方式。 -Hetzner 的价格会变化；请选择最小规格的 Debian/Ubuntu VPS，如果遇到 OOM 再向上扩容。 +如果你想要“每月约 5 美元、全天候运行的 OpenClaw”，这是最简单可靠的设置。 +Hetzner 价格会变化；选择最小规格的 Debian/Ubuntu VPS，如果遇到 OOM 再扩容。 安全模型提醒： -- 当所有人都处于同一信任边界内，且运行时仅用于业务用途时，共享的公司智能体是可以接受的。 -- 保持严格隔离：使用专用 VPS/运行时 + 专用账户；不要在该主机上使用个人 Apple/Google/浏览器/密码管理器配置文件。 -- 如果用户彼此具有对抗性，请按 Gateway 网关/主机/操作系统用户拆分。 +- 当所有人处于同一信任边界且运行时仅用于业务时，公司共享智能体是可以的。 +- 保持严格隔离：专用 VPS/运行时 + 专用账号；不要在该主机上使用个人 Apple/Google/浏览器/密码管理器配置文件。 +- 如果用户之间存在对抗关系，请按 Gateway 网关/主机/操作系统用户拆分。 -参见 [Security](/zh-CN/gateway/security) 和 [VPS hosting](/zh-CN/vps)。 +参见 [安全](/zh-CN/gateway/security) 和 [VPS 托管](/zh-CN/vps)。 ## 我们要做什么（简单来说）？ - 租用一台小型 Linux 服务器（Hetzner VPS） - 安装 Docker（隔离的应用运行时） - 在 Docker 中启动 OpenClaw Gateway 网关 -- 在主机上持久化 `~/.openclaw` + `~/.openclaw/workspace`（重启/重建后仍然保留） -- 通过 SSH 隧道从你的笔记本访问 Control UI +- 在主机上持久化 `~/.openclaw` + `~/.openclaw/workspace`（可在重启/重建后保留） +- 通过 SSH 隧道从你的笔记本访问控制 UI -该挂载的 `~/.openclaw` 状态包括 `openclaw.json`、每个智能体的 -`agents//agent/auth-profiles.json` 以及 `.env`。 +挂载的 `~/.openclaw` 状态包括 `openclaw.json`、每个智能体的 +`agents//agent/auth-profiles.json` 和 `.env`。 -Gateway 网关 可以通过以下方式访问： +可通过以下方式访问 Gateway 网关： - 从你的笔记本进行 SSH 端口转发 - 如果你自行管理防火墙和令牌，也可以直接暴露端口 本指南假设你在 Hetzner 上使用 Ubuntu 或 Debian。 -如果你使用的是其他 Linux VPS，请对应调整软件包。 -关于通用 Docker 流程，请参见 [Docker](/zh-CN/install/docker)。 +如果你使用其他 Linux VPS，请对应映射软件包。 +通用 Docker 流程见 [Docker](/zh-CN/install/docker)。 --- -## 快速路径（适合有经验的运维人员） +## 快速路径（有经验的运维人员） -1. 创建 Hetzner VPS +1. 配置 Hetzner VPS 2. 安装 Docker 3. 克隆 OpenClaw 仓库 4. 创建持久化主机目录 5. 配置 `.env` 和 `docker-compose.yml` 6. 将所需二进制文件内置到镜像中 7. `docker compose up -d` -8. 验证持久化和 Gateway 网关 访问 +8. 验证持久化和 Gateway 网关访问 --- -## 你需要准备什么 +## 你需要准备 -- 一台具有 root 访问权限的 Hetzner VPS +- 拥有 root 访问权限的 Hetzner VPS - 从你的笔记本进行 SSH 访问 -- 对 SSH + 复制粘贴有基本了解 -- 大约 20 分钟 +- 基本熟悉 SSH + 复制/粘贴 +- 约 20 分钟 - Docker 和 Docker Compose -- 模型认证凭证 -- 可选的提供商凭证 - - WhatsApp QR - - Telegram bot token +- 模型认证凭据 +- 可选的提供商凭据 + - WhatsApp 二维码 + - Telegram 机器人令牌 - Gmail OAuth --- - + 在 Hetzner 中创建一台 Ubuntu 或 Debian VPS。 以 root 身份连接： @@ -92,8 +92,8 @@ Gateway 网关 可以通过以下方式访问： ssh root@YOUR_VPS_IP ``` - 本指南假设该 VPS 是有状态的。 - 不要将它视为一次性基础设施。 + 本指南假设 VPS 是有状态的。 + 不要将其视为可随时丢弃的基础设施。 @@ -119,18 +119,18 @@ Gateway 网关 可以通过以下方式访问： cd openclaw ``` - 本指南假设你将构建一个自定义镜像，以确保二进制文件持久存在。 + 本指南假设你会构建自定义镜像，以保证二进制文件持久存在。 - Docker 容器是临时性的。 + Docker 容器是临时的。 所有长期状态都必须保存在主机上。 ```bash mkdir -p /root/.openclaw/workspace - # 将所有权设置为容器用户（uid 1000）： + # Set ownership to the container user (uid 1000): chown -R 1000:1000 /root/.openclaw ``` @@ -152,7 +152,8 @@ Gateway 网关 可以通过以下方式访问： XDG_CONFIG_HOME=/home/node/.openclaw ``` - 除非你明确希望通过 `.env` 管理它，否则请将 `OPENCLAW_GATEWAY_TOKEN` 留空；OpenClaw 会在首次启动时将一个随机 Gateway 网关 令牌写入配置。请生成一个 keyring 密码并粘贴到 `GOG_KEYRING_PASSWORD` 中： + 除非你明确想通过 `.env` 管理 `OPENCLAW_GATEWAY_TOKEN`，否则保持为空；OpenClaw 会在首次启动时将随机 Gateway 网关令牌写入配置。生成一个钥匙串密码并粘贴到 + `GOG_KEYRING_PASSWORD`： ```bash openssl rand -hex 32 @@ -161,8 +162,8 @@ Gateway 网关 可以通过以下方式访问： **不要提交此文件。** 这个 `.env` 文件用于容器/运行时环境变量，例如 `OPENCLAW_GATEWAY_TOKEN`。 - 已存储的提供商 OAuth/API key 认证位于挂载的 - `~/.openclaw/agents//agent/auth-profiles.json` 中。 + 已存储的提供商 OAuth/API 密钥认证位于挂载的 + `~/.openclaw/agents//agent/auth-profiles.json`。 @@ -191,8 +192,8 @@ Gateway 网关 可以通过以下方式访问： - ${OPENCLAW_CONFIG_DIR}:/home/node/.openclaw - ${OPENCLAW_WORKSPACE_DIR}:/home/node/.openclaw/workspace ports: - # 推荐：让 VPS 上的 Gateway 网关 仅绑定 loopback；通过 SSH 隧道访问。 - # 如果你要将其公开暴露，请去掉 `127.0.0.1:` 前缀，并相应配置防火墙。 + # Recommended: keep the Gateway loopback-only on the VPS; access via SSH tunnel. + # To expose it publicly, remove the `127.0.0.1:` prefix and firewall accordingly. - "127.0.0.1:${OPENCLAW_GATEWAY_PORT}:18789" command: [ @@ -207,22 +208,36 @@ Gateway 网关 可以通过以下方式访问： ] ``` - `--allow-unconfigured` 仅用于引导阶段的便利，不可替代正确的 Gateway 网关 配置。你仍然应当设置认证（`gateway.auth.token` 或密码），并为你的部署使用安全的绑定设置。 + `--allow-unconfigured` 仅用于引导阶段的便利，它不能替代合适的 Gateway 网关配置。仍需设置认证（`gateway.auth.token` 或密码），并为你的部署使用安全的绑定设置。 - 对于通用 Docker 主机流程，请使用共享运行时指南： + 使用共享运行时指南完成通用 Docker 主机流程： - [将所需二进制文件内置到镜像中](/zh-CN/install/docker-vm-runtime#bake-required-binaries-into-the-image) - [构建并启动](/zh-CN/install/docker-vm-runtime#build-and-launch) - - [哪些内容会持久保存，保存在哪里](/zh-CN/install/docker-vm-runtime#what-persists-where) + - [哪些内容持久化到哪里](/zh-CN/install/docker-vm-runtime#what-persists-where) - [更新](/zh-CN/install/docker-vm-runtime#updates) - - 在完成共享构建和启动步骤后，从你的笔记本建立隧道： + + 完成共享构建和启动步骤后，完成以下设置以打开隧道： + + **前提条件：** 确保你的 VPS sshd 配置允许 TCP 转发。如果你 + 已加固 SSH 配置，请检查 `/etc/ssh/sshd_config` 并设置： + + ``` + AllowTcpForwarding local + ``` + + `local` 允许从你的笔记本使用 `ssh -L` 进行本地转发，同时阻止 + 从服务器发起的远程转发。将其设置为 `no` 会导致隧道失败，并显示： + `channel 3: open failed: administratively prohibited: open failed` + + 确认 TCP 转发已启用后，重启 SSH 服务 + (`systemctl restart ssh`)，并从你的笔记本运行隧道： ```bash ssh -N -L 18789:127.0.0.1:18789 root@YOUR_VPS_IP @@ -232,43 +247,44 @@ Gateway 网关 可以通过以下方式访问： `http://127.0.0.1:18789/` - 粘贴已配置的共享密钥。本指南默认使用 Gateway 网关 令牌；如果你改用了密码认证，请改为使用该密码。 + 粘贴已配置的共享密钥。本指南默认使用 Gateway 网关令牌； + 如果你切换到了密码认证，请改用该密码。 -共享持久化映射位于 [Docker VM Runtime](/zh-CN/install/docker-vm-runtime#what-persists-where)。 +共享持久化映射位于 [Docker VM 运行时](/zh-CN/install/docker-vm-runtime#what-persists-where)。 ## 基础设施即代码（Terraform） -对于偏好基础设施即代码工作流的团队，社区维护的 Terraform 配置提供了： +对于偏好基础设施即代码工作流的团队，社区维护的 Terraform 设置提供： - 带远程状态管理的模块化 Terraform 配置 -- 通过 cloud-init 自动完成配置 -- 部署脚本（bootstrap、deploy、backup/restore） +- 通过 cloud-init 自动配置 +- 部署脚本（引导、部署、备份/恢复） - 安全加固（防火墙、UFW、仅 SSH 访问） -- 用于 Gateway 网关 访问的 SSH 隧道配置 +- 用于 Gateway 网关访问的 SSH 隧道配置 **仓库：** -- Infrastructure：[openclaw-terraform-hetzner](https://github.com/andreesg/openclaw-terraform-hetzner) -- Docker config：[openclaw-docker-config](https://github.com/andreesg/openclaw-docker-config) +- 基础设施：[openclaw-terraform-hetzner](https://github.com/andreesg/openclaw-terraform-hetzner) +- Docker 配置：[openclaw-docker-config](https://github.com/andreesg/openclaw-docker-config) -这种方式在上述 Docker 配置基础上进一步提供了可复现部署、版本控制的基础设施以及自动化灾难恢复。 +这种方式在上述 Docker 设置基础上补充了可复现部署、版本控制的基础设施和自动化灾难恢复。 -由社区维护。如有问题或希望贡献，请参见上面的仓库链接。 +由社区维护。有关问题或贡献，请参见上方仓库链接。 ## 后续步骤 -- 设置消息渠道：[Channels](/zh-CN/channels) -- 配置 Gateway 网关：[Gateway configuration](/zh-CN/gateway/configuration) -- 保持 OpenClaw 为最新版本：[Updating](/zh-CN/install/updating) +- 设置消息渠道：[渠道](/zh-CN/channels) +- 配置 Gateway 网关：[Gateway 网关配置](/zh-CN/gateway/configuration) +- 让 OpenClaw 保持最新：[更新](/zh-CN/install/updating) -## 相关 +## 相关内容 - [安装概览](/zh-CN/install) - [Fly.io](/zh-CN/install/fly) - [Docker](/zh-CN/install/docker) -- [VPS hosting](/zh-CN/vps) +- [VPS 托管](/zh-CN/vps) diff --git a/docs/zh-CN/tools/creating-skills.md b/docs/zh-CN/tools/creating-skills.md index 86aebc8ca..45589257d 100644 --- a/docs/zh-CN/tools/creating-skills.md +++ b/docs/zh-CN/tools/creating-skills.md @@ -1,27 +1,27 @@ --- read_when: - - 你正在工作区中创建一个新的自定义 Skill - - 你需要一个基于 `SKILL.md` 的 Skill 快速入门工作流 -summary: 使用 `SKILL.md` 构建并测试自定义工作区 Skills + - 你正在工作区中创建一个新的自定义技能 + - 你需要一个基于 SKILL.md 的 Skills 快速入门工作流 +summary: 使用 SKILL.md 构建并测试自定义工作区 Skills title: 创建 Skills x-i18n: - generated_at: "2026-04-23T21:07:18Z" - model: gpt-5.4 + generated_at: "2026-04-29T03:21:01Z" + model: gpt-5.5 provider: openai - source_hash: df9249e14936c65143580a6618679cf2d79a2960390e5c7afc5dbea1a9a6e045 + source_hash: 201718f4088f4243b0dabe12fb4fce4b8a7e64df9a4b7d651356ab4ae0dd3579 source_path: tools/creating-skills.md - workflow: 15 + workflow: 16 --- -Skills 用于教会智能体如何以及何时使用工具。每个 Skill 都是一个目录， +Skills 教会智能体如何以及何时使用工具。每个技能都是一个目录， 其中包含一个带有 YAML frontmatter 和 Markdown 指令的 `SKILL.md` 文件。 -有关 Skills 如何加载和排序优先级，请参见 [Skills](/zh-CN/tools/skills)。 +有关 Skills 如何加载和确定优先级，请参阅 [Skills](/zh-CN/tools/skills)。 -## 创建你的第一个 Skill +## 创建你的第一个技能 - + Skills 位于你的工作区中。创建一个新文件夹： ```bash @@ -30,13 +30,13 @@ Skills 用于教会智能体如何以及何时使用工具。每个 Skill 都是 - + 在该目录中创建 `SKILL.md`。frontmatter 定义元数据， - Markdown 正文则包含给智能体的指令。 + Markdown 正文包含给智能体的指令。 ```markdown --- - name: hello_world + name: hello-world description: A simple skill that says hello. --- @@ -46,17 +46,20 @@ Skills 用于教会智能体如何以及何时使用工具。每个 Skill 都是 "Hello from your custom skill!". ``` + 技能 `name` 使用由小写字母、数字和连字符组成的连字符命名法。 + 保持文件夹名称与 frontmatter 中的 `name` 一致。 + - + 你可以在 frontmatter 中定义自定义工具 schema，或指示智能体 使用现有系统工具（如 `exec` 或 `browser`）。Skills 也可以 - 和它们所描述的工具一起打包进插件中。 + 随插件一起分发，并与它们所记录的工具放在一起。 - - 启动一个新会话，以便 OpenClaw 读取该 Skill： + + 启动一个新会话，让 OpenClaw 识别该技能： ```bash # From chat @@ -66,7 +69,7 @@ Skills 用于教会智能体如何以及何时使用工具。每个 Skill 都是 openclaw gateway restart ``` - 验证 Skill 已加载： + 验证该技能已加载： ```bash openclaw skills list @@ -74,51 +77,51 @@ Skills 用于教会智能体如何以及何时使用工具。每个 Skill 都是 - - 发送一条应当触发该 Skill 的消息： + + 发送一条应触发该技能的消息： ```bash openclaw agent --message "give me a greeting" ``` - 或者直接与智能体聊天，并请求一个问候。 + 或者直接与智能体聊天，并请求一条问候语。 -## Skill 元数据参考 +## 技能元数据参考 -YAML frontmatter 支持以下字段： +YAML frontmatter 支持这些字段： -| 字段 | 必填 | 描述 | -| ----------------------------------- | -------- | ------------------------------------------- | -| `name` | 是 | 唯一标识符（snake_case） | -| `description` | 是 | 展示给智能体的一行描述 | -| `metadata.openclaw.os` | 否 | OS 过滤器（`["darwin"]`、`["linux"]` 等） | -| `metadata.openclaw.requires.bins` | 否 | PATH 上必需的二进制 | -| `metadata.openclaw.requires.config` | 否 | 必需的配置键 | +| 字段 | 必填 | 描述 | +| ----------------------------------- | -------- | -------------------------------------------------------------- | +| `name` | 是 | 使用小写字母、数字和连字符的唯一标识符 | +| `description` | 是 | 显示给智能体的单行描述 | +| `metadata.openclaw.os` | 否 | OS 过滤器（`["darwin"]`、`["linux"]` 等） | +| `metadata.openclaw.requires.bins` | 否 | PATH 上所需的二进制文件 | +| `metadata.openclaw.requires.config` | 否 | 所需配置键 | ## 最佳实践 -- **保持简洁** —— 告诉模型_做什么_，而不是如何扮演 AI -- **安全优先** —— 如果你的 Skill 使用 `exec`，请确保提示词不会允许来自不受信任输入的任意命令注入 -- **本地测试** —— 在分享前使用 `openclaw agent --message "..."` 进行测试 -- **使用 ClawHub** —— 在 [ClawHub](https://clawhub.ai) 浏览并贡献 Skills +- **保持简洁** — 指示模型要做_什么_，而不是如何成为 AI +- **安全优先** — 如果你的技能使用 `exec`，请确保提示不会允许来自不可信输入的任意命令注入 +- **本地测试** — 分享前使用 `openclaw agent --message "..."` 进行测试 +- **使用 ClawHub** — 在 [ClawHub](https://clawhub.ai) 浏览并贡献 Skills -## Skills 位于哪里 +## Skills 的位置 -| 位置 | 优先级 | 范围 | +| 位置 | 优先级 | 范围 | | ------------------------------- | ---------- | --------------------- | -| `\/skills/` | 最高 | 按智能体 | -| `\/.agents/skills/` | 高 | 按工作区智能体 | -| `~/.agents/skills/` | 中 | 共享智能体配置文件 | -| `~/.openclaw/skills/` | 中 | 共享（所有智能体） | -| 内置（随 OpenClaw 一起发布） | 低 | 全局 | -| `skills.load.extraDirs` | 最低 | 自定义共享文件夹 | +| `\/skills/` | 最高 | 每个智能体 | +| `\/.agents/skills/` | 高 | 每个工作区智能体 | +| `~/.agents/skills/` | 中 | 共享智能体配置文件 | +| `~/.openclaw/skills/` | 中 | 共享（所有智能体） | +| 内置（随 OpenClaw 一起提供） | 低 | 全局 | +| `skills.load.extraDirs` | 最低 | 自定义共享文件夹 | -## 相关内容 +## 相关 -- [Skills reference](/zh-CN/tools/skills) —— 加载、优先级和门控规则 -- [Skills 配置](/zh-CN/tools/skills-config) —— `skills.*` 配置 schema -- [ClawHub](/zh-CN/tools/clawhub) —— 公共 Skill 注册表 -- [Building Plugins](/zh-CN/plugins/building-plugins) —— 插件可以携带 Skills +- [Skills 参考](/zh-CN/tools/skills) — 加载、优先级和门控规则 +- [Skills 配置](/zh-CN/tools/skills-config) — `skills.*` 配置 schema +- [ClawHub](/zh-CN/tools/clawhub) — 公共技能注册表 +- [构建插件](/zh-CN/plugins/building-plugins) — 插件可以分发 Skills