openclaw/docs
openclaw/docs
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

chore(i18n): refresh zh-CN translations

Browse Source
This commit is contained in:
openclaw-docs-i18n[bot] 2026-04-19 06:57:13 +00:00
parent 89e7110f57
commit 680137c4dc
4 changed files with 1114 additions and 1113 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1906
docs/zh-CN/help/faq.md
View File

File diff suppressed because it is too large Load Diff

96
docs/zh-CN/install/index.md
View File

@ -1,15 +1,15 @@
---
read_when:
- 你需要一种不同于“入门指南”快速开始的安装方式
- 你想部署到云平台
- 你想要部署到云平台
- 你需要更新、迁移或卸载
summary: 安装 OpenClaw —— 安装脚本、npm/pnpm/bun、从源码安装、Docker 等
summary: 安装 OpenClaw —— 安装脚本、npm/pnpm/bun、从源码安装、Docker 等更多方式
title: 安装
x-i18n:
generated_at: "2026-04-05T08:27:26Z"
generated_at: "2026-04-19T06:50:07Z"
model: gpt-5.4
provider: openai
source_hash: eca17c76a2a66166b3d8cda9dc3144ab920d30ad0ed2a220eb9389d7a383ba5d
source_hash: ad0a5fdbbf13dcaf2fed6840f35aa22b2e9e458509509f98303c8d87c2556a6f
source_path: install/index.md
workflow: 15
---
@ -26,14 +26,14 @@ x-i18n:
curl -fsSL https://openclaw.ai/install.sh | bash
```
</Tab>
<Tab title="Windows (PowerShell)">
<Tab title="Windows（PowerShell）">
```powershell
iwr -useb https://openclaw.ai/install.ps1 | iex
```
</Tab>
</Tabs>
如果你希望安装时不运行新手引导：
如果你想安装但不运行新手引导：
<Tabs>
<Tab title="macOS / Linux / WSL2">
@ -41,34 +41,34 @@ x-i18n:
curl -fsSL https://openclaw.ai/install.sh | bash -s -- --no-onboard
```
</Tab>
<Tab title="Windows (PowerShell)">
<Tab title="Windows（PowerShell）">
```powershell
& ([scriptblock]::Create((iwr -useb https://openclaw.ai/install.ps1))) -NoOnboard
```
</Tab>
</Tabs>
有关所有标志以及 CI/自动化选项，请参见 [安装器内部机制](/install/installer)。
有关所有标志和 CI / 自动化选项，请参阅 [安装器内部机制](/zh-CN/install/installer)。
## 系统要求
- **Node 24**（推荐）或 Node 22.14+ —— 安装脚本会自动处理
- **macOS、Linux 或 Windows** —— 同时支持原生 Windows 和 WSL2；WSL2 更稳定。参见 [Windows](/platforms/windows)。
- 只有在你从源码构建时才需要 `pnpm`
- **Node 24**（推荐）或 Node 22.14+ —— 安装脚本会自动处理这一点
- **macOS、Linux 或 Windows** —— 同时支持原生 Windows 和 WSL2；WSL2 更稳定。参见 [Windows](/zh-CN/platforms/windows)。
- 仅当你从源码构建时才需要 `pnpm`
## 其他安装方式
### 本地前缀安装器（`install-cli.sh`）
当你希望将 OpenClaw 和 Node 保持在本地前缀下（例如
`~/.openclaw`），而不依赖系统范围的 Node 安装时，请使用此方式：
如果你希望将 OpenClaw 和 Node 保存在本地前缀目录下，例如
`~/.openclaw`，而不依赖系统范围安装的 Node，请使用此方式：
```bash
curl -fsSL https://openclaw.ai/install-cli.sh | bash
```
它默认支持 npm 安装，也支持在同一
前缀流程下使用 git 检出安装。完整参考： [安装器内部机制](/install/installer#install-clish)。
它默认支持通过 npm 安装，也支持在相同前缀流程下从 git 检出进行安装。
完整参考请见：[安装器内部机制](/zh-CN/install/installer#install-clish)。
### npm、pnpm 或 bun
@ -89,7 +89,7 @@ curl -fsSL https://openclaw.ai/install-cli.sh | bash
```
<Note>
pnpm 对带有构建脚本的软件包要求显式批准。首次安装后请运行 `pnpm approve-builds -g`。
pnpm 对包含构建脚本的软件包需要显式批准。首次安装后请运行 `pnpm approve-builds -g`。
</Note>
</Tab>
@ -106,7 +106,7 @@ curl -fsSL https://openclaw.ai/install-cli.sh | bash
</Tab>
</Tabs>
<Accordion title="故障排除：sharp 构建错误（npm）">
<Accordion title="故障排除：`sharp` 构建错误（npm）">
如果 `sharp` 因全局安装的 libvips 而失败：
```bash
@ -117,17 +117,17 @@ SHARP_IGNORE_GLOBAL_LIBVIPS=1 npm install -g openclaw@latest
### 从源码安装
适用于贡献者，或任何希望从本地检出运行的人：
适用于贡献者，或任何想从本地检出运行的人：
```bash
git clone https://github.com/openclaw/openclaw.git
cd openclaw
pnpm install && pnpm ui:build && pnpm build
pnpm install && pnpm build && pnpm ui:build
pnpm link --global
openclaw onboard --install-daemon
```
或者跳过 link，直接在仓库内使用 `pnpm openclaw ...`。完整开发工作流请参见 [设置](/start/setup)。
或者跳过 link，直接在仓库内使用 `pnpm openclaw ...`。完整开发工作流请参见 [设置](/zh-CN/start/setup)。
### 从 GitHub main 安装
@ -138,20 +138,20 @@ npm install -g github:openclaw/openclaw#main
### 容器和包管理器
<CardGroup cols={2}>
<Card title="Docker" href="/install/docker" icon="container">
<Card title="Docker" href="/zh-CN/install/docker" icon="container">
容器化或无头部署。
</Card>
<Card title="Podman" href="/install/podman" icon="container">
<Card title="Podman" href="/zh-CN/install/podman" icon="container">
Docker 的无 root 容器替代方案。
</Card>
<Card title="Nix" href="/install/nix" icon="snowflake">
<Card title="Nix" href="/zh-CN/install/nix" icon="snowflake">
通过 Nix flake 进行声明式安装。
</Card>
<Card title="Ansible" href="/install/ansible" icon="server">
自动化 fleet 配置。
<Card title="Ansible" href="/zh-CN/install/ansible" icon="server">
自动化批量部署。
</Card>
<Card title="Bun" href="/install/bun" icon="zap">
通过 Bun 运行时进行仅 CLI 用法。
<Card title="Bun" href="/zh-CN/install/bun" icon="zap">
通过 Bun 运行时仅使用 CLI。
</Card>
</CardGroup>
@ -163,39 +163,39 @@ openclaw doctor # 检查配置问题
openclaw gateway status # 验证 Gateway 网关正在运行
```
如果你希望安装后由系统托管启动：
如果你希望安装后启用托管启动：
- macOS：通过 `openclaw onboard --install-daemon` 或 `openclaw gateway install` 安装 LaunchAgent
- Linux/WSL2：通过相同命令安装 systemd 用户服务
- 原生 Windows：优先使用 Scheduled Task；如果任务创建被拒绝，则回退到按用户的 Startup 文件夹登录项
- Linux / WSL2：通过相同命令安装 systemd 用户服务
- 原生 Windows：优先使用计划任务；如果任务创建被拒绝，则回退为每用户“启动”文件夹登录项
## 托管和部署
## 托管与部署
将 OpenClaw 部署到云服务器或 VPS：
<CardGroup cols={3}>
<Card title="VPS" href="/vps">任意 Linux VPS</Card>
<Card title="Docker VM" href="/install/docker-vm-runtime">共享 Docker 步骤</Card>
<Card title="Kubernetes" href="/install/kubernetes">K8s</Card>
<Card title="Fly.io" href="/install/fly">Fly.io</Card>
<Card title="Hetzner" href="/install/hetzner">Hetzner</Card>
<Card title="GCP" href="/install/gcp">Google Cloud</Card>
<Card title="Azure" href="/install/azure">Azure</Card>
<Card title="Railway" href="/install/railway">Railway</Card>
<Card title="Render" href="/install/render">Render</Card>
<Card title="Northflank" href="/install/northflank">Northflank</Card>
<Card title="VPS" href="/zh-CN/vps">任意 Linux VPS</Card>
<Card title="Docker VM" href="/zh-CN/install/docker-vm-runtime">共享 Docker 步骤</Card>
<Card title="Kubernetes" href="/zh-CN/install/kubernetes">K8s</Card>
<Card title="Fly.io" href="/zh-CN/install/fly">Fly.io</Card>
<Card title="Hetzner" href="/zh-CN/install/hetzner">Hetzner</Card>
<Card title="GCP" href="/zh-CN/install/gcp">Google Cloud</Card>
<Card title="Azure" href="/zh-CN/install/azure">Azure</Card>
<Card title="Railway" href="/zh-CN/install/railway">Railway</Card>
<Card title="Render" href="/zh-CN/install/render">Render</Card>
<Card title="Northflank" href="/zh-CN/install/northflank">Northflank</Card>
</CardGroup>
## 更新、迁移或卸载
<CardGroup cols={3}>
<Card title="更新" href="/install/updating" icon="refresh-cw">
<Card title="更新" href="/zh-CN/install/updating" icon="refresh-cw">
让 OpenClaw 保持最新。
</Card>
<Card title="迁移" href="/install/migrating" icon="arrow-right">
迁移到新机器。
<Card title="迁移" href="/zh-CN/install/migrating" icon="arrow-right">
迁移到新设备。
</Card>
<Card title="卸载" href="/install/uninstall" icon="trash-2">
<Card title="卸载" href="/zh-CN/install/uninstall" icon="trash-2">
完全移除 OpenClaw。
</Card>
</CardGroup>
@ -205,15 +205,15 @@ openclaw gateway status # 验证 Gateway 网关正在运行
如果安装成功，但终端中找不到 `openclaw`：
```bash
node -v # Node 是否已安装？
node -v # 已安装 Node？
npm prefix -g # 全局软件包安装在哪里？
echo "$PATH" # 全局 bin 目录是否在 PATH 中？
```
如果 `$(npm prefix -g)/bin` 不在你的 `$PATH` 中，请将它添加到你的 shell 启动文件（`~/.zshrc` 或 `~/.bashrc`）中：
如果 `$(npm prefix -g)/bin` 不在你的 `$PATH` 中，请将其添加到 shell 启动文件（`~/.zshrc` 或 `~/.bashrc`）中：
```bash
export PATH="$(npm prefix -g)/bin:$PATH"
```
然后打开一个新的终端。更多细节请参见 [Node 设置](/install/node)。
然后重新打开一个终端。更多详情请参见 [Node 设置](/zh-CN/install/node)。

110
docs/zh-CN/platforms/windows.md
View File

@ -1,40 +1,40 @@
---
read_when:
- 在 Windows 上安装 OpenClaw
- 在原生 Windows 和 WSL2 之间做选择
- 了解 Windows 配套应用的当前状态
- 在原生 Windows 和 WSL2 之间进行选择
- 查找 Windows 配套应用状态
summary: Windows 支持：原生和 WSL2 安装路径、守护进程以及当前注意事项
title: Windows
x-i18n:
generated_at: "2026-04-05T08:38:21Z"
generated_at: "2026-04-19T06:50:03Z"
model: gpt-5.4
provider: openai
source_hash: 7d9819206bdd65cf03519c1bc73ed0c7889b0ab842215ea94343262300adfd14
source_hash: 1e7451c785a1d75c809522ad93e2c44a00b211f77f14c5c489fd0b01840d3fe2
source_path: platforms/windows.md
workflow: 15
---
# Windows
OpenClaw 同时支持 **原生 Windows** 和 **WSL2**。WSL2 是更稳定的路径，也是获得完整体验的推荐方式 —— CLI、Gateway 网关和工具链都在 Linux 内运行，并具备完整兼容性。原生 Windows 可用于核心 CLI 和 Gateway 网关场景，但有一些如下所述的注意事项。
OpenClaw 同时支持**原生 Windows**和 **WSL2**。WSL2 是更稳定的路径，推荐用于获得完整体验——CLI、Gateway 网关和工具链都在 Linux 内运行，并具备完整兼容性。原生 Windows 可用于核心 CLI 和 Gateway 网关，但存在下文所述的一些注意事项。
原生 Windows 配套应用已在计划中。
原生 Windows 配套应用已在规划中。
## WSL2（推荐）
- [入门指南](/start/getting-started)（请在 WSL 内使用）
- [安装与更新](/install/updating)
- [入门指南](/zh-CN/start/getting-started)（在 WSL 内使用）
- [安装与更新](/zh-CN/install/updating)
- 官方 WSL2 指南（Microsoft）：[https://learn.microsoft.com/windows/wsl/install](https://learn.microsoft.com/windows/wsl/install)
## 原生 Windows 状态
原生 Windows CLI 流程正在持续改进，但 WSL2 仍然是推荐路径。
当前在原生 Windows 上运行良好的内容：
当前原生 Windows 上运行良好的内容：
- 通过 `install.ps1` 进行网站安装
- 通过 `install.ps1` 使用网站安装器
- 本地 CLI 用法，例如 `openclaw --version`、`openclaw doctor` 和 `openclaw plugins list --json`
- 内置 local-agent / provider 冒烟测试，例如：
- 内置 local-agent/provider 冒烟测试，例如：
```powershell
openclaw agent --local --agent main --thinking low -m "Reply with exactly WINDOWS-HATCH-OK."
@ -42,36 +42,36 @@ openclaw agent --local --agent main --thinking low -m "Reply with exactly WINDOW
当前注意事项：
- `openclaw onboard --non-interactive` 仍然需要可访问的本地 gateway，除非你传入 `--skip-health`
- `openclaw onboard --non-interactive --install-daemon` 和 `openclaw gateway install` 会优先尝试 Windows Scheduled Tasks
- 如果创建 Scheduled Task 被拒绝，OpenClaw 会回退到当前用户 Startup 文件夹中的登录启动项，并立即启动 gateway
- 如果 `schtasks` 本身卡住或停止响应，OpenClaw 现在会快速终止该路径并回退，而不会一直挂起
- 在可用时，仍然优先使用 Scheduled Tasks，因为它们能提供更好的 supervisor 状态
- `openclaw onboard --non-interactive` 仍然要求可访问的本地 Gateway 网关，除非你传入 `--skip-health`
- `openclaw onboard --non-interactive --install-daemon` 和 `openclaw gateway install` 会优先尝试使用 Windows 计划任务
- 如果计划任务创建被拒绝，OpenClaw 会回退到当前用户的 Startup 文件夹登录启动项，并立即启动 Gateway 网关
- 如果 `schtasks` 本身卡住或停止响应，OpenClaw 现在会快速中止该路径并回退，而不是永久挂起
- 在可用时，仍然优先使用计划任务，因为它们能提供更好的 supervisor 状态
如果你只想使用原生 CLI，而不安装 gateway 服务，请使用以下任一命令：
如果你只想使用原生 CLI，而不安装 Gateway 网关服务，可使用以下任一命令：
```powershell
openclaw onboard --non-interactive --skip-health
openclaw gateway run
```
如果你确实希望在原生 Windows 上启用受管启动：
如果你确实希望在原生 Windows 上启用托管启动：
```powershell
openclaw gateway install
openclaw gateway status --json
```
如果创建 Scheduled Task 受阻，回退服务模式仍会通过当前用户的 Startup 文件夹在登录后自动启动。
如果计划任务创建被阻止，回退服务模式仍会通过当前用户的 Startup 文件夹在登录后自动启动。
## Gateway 网关
- [Gateway 网关运行手册](/gateway)
- [配置](/gateway/configuration)
- [Gateway 网关运行手册](/zh-CN/gateway)
- [配置](/zh-CN/gateway/configuration)
## Gateway 网关服务安装（CLI）
在 WSL2 中：
在 WSL2 内：
```
openclaw onboard --install-daemon
@ -89,9 +89,9 @@ openclaw gateway install
openclaw configure
```
在提示时选择 **Gateway service**。
出现提示时，选择**Gateway 网关服务**。
修复 / 迁移：
修复/迁移：
```
openclaw doctor
@ -99,10 +99,9 @@ openclaw doctor
## 在 Windows 登录前自动启动 Gateway 网关
对于无头部署，请确保即使没有人登录
Windows，完整的启动链也能运行。
对于无人值守的设置，请确保即使没有人登录 Windows，完整的启动链路也能运行。
### 1）让用户服务在未登录时持续运行
### 1) 在未登录时保持用户服务运行
在 WSL 内：
@ -110,7 +109,7 @@ Windows，完整的启动链也能运行。
sudo loginctl enable-linger "$(whoami)"
```
### 2）安装 OpenClaw gateway 用户服务
### 2) 安装 OpenClaw Gateway 网关用户服务
在 WSL 内：
@ -118,23 +117,23 @@ sudo loginctl enable-linger "$(whoami)"
openclaw gateway install
```
### 3）在 Windows 启动时自动启动 WSL
### 3) 在 Windows 启动时自动启动 WSL
以管理员身份在 PowerShell 中运行：
在 PowerShell 中以管理员身份运行：
```powershell
schtasks /create /tn "WSL Boot" /tr "wsl.exe -d Ubuntu --exec /bin/true" /sc onstart /ru SYSTEM
```
将 `Ubuntu` 替换为以下命令显示的发行版名称：
将 `Ubuntu` 替换为你通过以下命令查看到的发行版名称：
```powershell
wsl --list --verbose
```
### 验证启动链
### 验证启动链路
重启后（在 Windows 登录之前），在 WSL 中检查：
重启后（在 Windows 登录前），可在 WSL 中检查：
```bash
systemctl --user is-enabled openclaw-gateway.service
@ -143,12 +142,9 @@ systemctl --user status openclaw-gateway.service --no-pager
## 高级：通过 LAN 暴露 WSL 服务（portproxy）
WSL 有自己的虚拟网络。如果另一台机器需要访问
**运行在 WSL 内部** 的服务（SSH、本地 TTS 服务器或 Gateway 网关），你必须
将一个 Windows 端口转发到当前的 WSL IP。WSL IP 会在重启后变化，
因此你可能需要刷新转发规则。
WSL 有自己的虚拟网络。如果另一台机器需要访问**运行在 WSL 内部**的服务（SSH、本地 TTS 服务器或 Gateway 网关），你必须将 Windows 端口转发到当前的 WSL IP。WSL IP 会在重启后变化，因此你可能需要刷新转发规则。
示例（**以管理员身份**在 PowerShell 中运行）：
示例（在 PowerShell 中**以管理员身份**运行）：
```powershell
$Distro = "Ubuntu-24.04"
@ -177,18 +173,16 @@ netsh interface portproxy add v4tov4 listenport=$ListenPort listenaddress=0.0.0.
connectaddress=$WslIp connectport=$TargetPort | Out-Null
```
说明：
注意：
- 从另一台机器发起 SSH 时，目标应为 **Windows 主机 IP**（例如：`ssh user@windows-host -p 2222`）。
- 远程节点必须指向一个**可访问的** Gateway 网关 URL（不能是 `127.0.0.1`）；请使用
`openclaw status --all` 进行确认。
- 使用 `listenaddress=0.0.0.0` 可供 LAN 访问；使用 `127.0.0.1` 则仅限本地。
- 如果你想自动完成此操作，可以注册一个 Scheduled Task，在登录时运行刷新
步骤。
- 从另一台机器发起 SSH 时，目标应为**Windows 主机 IP**（例如：`ssh user@windows-host -p 2222`）。
- 远程节点必须指向一个**可访问的** Gateway 网关 URL（不能是 `127.0.0.1`）；可使用 `openclaw status --all` 进行确认。
- 若需通过局域网访问，请使用 `listenaddress=0.0.0.0`；使用 `127.0.0.1` 则仅限本机访问。
- 如果你希望这一过程自动化，可注册一个计划任务，在登录时运行刷新步骤。
## 分步 WSL2 安装
### 1）安装 WSL2 + Ubuntu
### 1) 安装 WSL2 + Ubuntu
打开 PowerShell（管理员）：
@ -201,7 +195,7 @@ wsl --install -d Ubuntu-24.04
如果 Windows 提示，请重启。
### 2）启用 systemd（Gateway 网关安装所必需）
### 2) 启用 systemd（安装 Gateway 网关所必需）
在你的 WSL 终端中：
@ -224,22 +218,30 @@ wsl --shutdown
systemctl --user status
```
### 3）安装 OpenClaw（在 WSL 内）
### 3) 安装 OpenClaw（在 WSL 内）
在 WSL 内按照 Linux 入门指南流程进行：
如果你是在 WSL 内进行首次常规安装，请遵循 Linux 的入门指南流程：
```bash
git clone https://github.com/openclaw/openclaw.git
cd openclaw
pnpm install
pnpm ui:build # 首次运行时会自动安装 UI 依赖
pnpm build
openclaw onboard
pnpm ui:build
pnpm openclaw onboard --install-daemon
```
完整指南： [入门指南](/start/getting-started)
如果你是在从源码进行开发，而不是首次新手引导，请使用[设置](/zh-CN/start/setup)中的源码开发循环：
```bash
pnpm install
# 仅首次运行时需要（或在重置本地 OpenClaw 配置/工作区之后）
pnpm openclaw setup
pnpm gateway:watch
```
完整指南：[入门指南](/zh-CN/start/getting-started)
## Windows 配套应用
我们目前还没有 Windows 配套应用。如果你希望
推动这件事发生，欢迎贡献代码。
我们目前还没有 Windows 配套应用。如果你愿意推动这件事，欢迎贡献代码。

115
docs/zh-CN/start/setup.md
View File

@ -1,14 +1,14 @@
---
read_when:
- 设置一台新机器
- 你想使用“最新 + 最强”版本，同时又不破坏你的个人设置
- 设置新机器
- 你希望获得“最新且最强”的体验，同时又不破坏你的个人设置
summary: OpenClaw 的高级设置与开发工作流
title: 设置
x-i18n:
generated_at: "2026-04-05T10:09:48Z"
generated_at: "2026-04-19T06:50:01Z"
model: gpt-5.4
provider: openai
source_hash: be4e280dde7f3a224345ca557ef2fb35a9c9db8520454ff63794ac6f8d4e71e7
source_hash: 773cdbef5f38b069303b5e13fca5fcdc28f082746869f17b8b92aab1610b95a8
source_path: start/setup.md
workflow: 15
---
@ -16,27 +16,27 @@ x-i18n:
# 设置
<Note>
如果你是第一次设置，请先阅读 [入门指南](/zh-CN/start/getting-started)。
有关新手引导的详细信息，请参阅 [设置向导（CLI）](/zh-CN/start/wizard)。
如果这是你第一次设置，请先阅读 [入门指南](/zh-CN/start/getting-started)。
如需了解新手引导详情，请参阅 [新手引导（CLI）](/zh-CN/start/wizard)。
</Note>
## TL;DR
- **个性化配置位于仓库之外：** `~/.openclaw/workspace`（工作区）+ `~/.openclaw/openclaw.json`（配置）。
- **个性化配置保存在仓库之外：** `~/.openclaw/workspace`（工作区）+ `~/.openclaw/openclaw.json`（配置）。
- **稳定工作流：** 安装 macOS 应用；让它运行内置的 Gateway 网关。
- **前沿工作流：** 通过 `pnpm gateway:watch` 自行运行 Gateway 网关，然后让 macOS 应用在本地模式下连接。
## 前置条件（从源码运行）
## 先决条件（从源码开始）
- 推荐使用 Node 24（仍支持 Node 22 LTS，目前为 `22.14+`）
- 推荐使用 `pnpm`（或者，如果你有意使用 [Bun 工作流](/zh-CN/install/bun)，也可以使用 Bun）
- Docker（可选；仅用于容器化设置/e2e —— 参见 [Docker](/zh-CN/install/docker)）
- 推荐使用 Node 24（也仍支持 Node 22 LTS，目前为 `22.14+`）
- 优先使用 `pnpm`（或者如果你有意使用 [Bun 工作流](/zh-CN/install/bun)，也可使用 Bun）
- Docker（可选；仅用于容器化设置 / e2e —— 参见 [Docker](/zh-CN/install/docker)）
## 个性化策略（这样更新时不会受影响）
## 个性化策略（这样更新就不会伤到你）
如果你既想要“100% 按自己需求定制”，又想轻松更新，请将你的自定义内容保存在：
如果你想要“100% 为我量身定制”，_同时_ 又想轻松更新，请把你的自定义内容放在：
- **配置：** `~/.openclaw/openclaw.json`（JSON/类似 JSON5）
- **配置：** `~/.openclaw/openclaw.json`（类似 JSON / JSON5）
- **工作区：** `~/.openclaw/workspace`（skills、提示词、记忆；建议将其设为私有 git 仓库）
初始化一次：
@ -45,13 +45,13 @@ x-i18n:
openclaw setup
```
在这个仓库中，请使用本地 CLI 入口：
在这个仓库内，使用本地 CLI 入口：
```bash
openclaw setup
```
如果你还没有全局安装，请通过 `pnpm openclaw setup` 运行（如果你使用的是 Bun 工作流，则使用 `bun run openclaw setup`）。
如果你还没有全局安装，请通过 `pnpm openclaw setup` 运行（如果你使用 Bun 工作流，则使用 `bun run openclaw setup`）。
## 从这个仓库运行 Gateway 网关
@ -63,114 +63,119 @@ node openclaw.mjs gateway --port 18789 --verbose
## 稳定工作流（优先使用 macOS 应用）
1. 安装并启动 **OpenClaw.app**（菜单栏）。
2. 完成新手引导/权限检查清单（TCC 提示）。
3. 确保 Gateway 网关处于**本地**模式并正在运行（由应用管理）。
4. 连接各个界面（例如：WhatsApp）：
1. 安装并启动 **OpenClaw.app**（菜单栏应用）。
2. 完成新手引导 / 权限检查清单（TCC 提示）。
3. 确保 Gateway 网关处于 **Local** 模式并正在运行（由应用管理）。
4. 关联各个渠道（例如：WhatsApp）：
```bash
openclaw channels login
```
5. 完整性检查：
5. 进行安装完整性检查：
```bash
openclaw health
```
如果你的构建中没有新手引导：
如果你的构建中没有提供新手引导：
- 运行 `openclaw setup`，然后运行 `openclaw channels login`，再手动启动 Gateway 网关（`openclaw gateway`）。
- 运行 `openclaw setup`，然后运行 `openclaw channels login`，接着手动启动 Gateway 网关（`openclaw gateway`）。
## 前沿工作流（在终端中运行 Gateway 网关）
目标：开发 TypeScript Gateway 网关、获得热重载，并保持 macOS 应用 UI 处于连接状态。
目标：开发 TypeScript Gateway 网关、获得热重载，同时保持 macOS 应用 UI 已连接。
### 0）（可选）也从源码运行 macOS 应用
### 0) （可选）也从源码运行 macOS 应用
如果你也想让 macOS 应用使用前沿版本：
如果你也想使用前沿版本的 macOS 应用：
```bash
./scripts/restart-mac.sh
```
### 1）启动开发版 Gateway 网关
### 1) 启动开发版 Gateway 网关
```bash
pnpm install
# 仅首次运行时需要（或在重置本地 OpenClaw 配置 / 工作区后）
pnpm openclaw setup
pnpm gateway:watch
```
`gateway:watch` 会以 watch 模式运行 gateway，并在相关源码、
配置和内置插件元数据发生变化时重新加载。
`gateway:watch` 会以监视模式运行 Gateway 网关，并在相关源码、配置以及内置插件元数据发生变化时重新加载。
`pnpm openclaw setup` 是针对全新检出的代码仓库执行的一次性本地配置 / 工作区初始化步骤。
`pnpm gateway:watch` 不会重建 `dist/control-ui`，因此在 `ui/` 发生变更后，请重新运行 `pnpm ui:build`，或者在开发 Control UI 时使用 `pnpm ui:dev`。
如果你有意使用 Bun 工作流，对应命令为：
如果你有意使用 Bun 工作流，对应命令是：
```bash
bun install
# 仅首次运行时需要（或在重置本地 OpenClaw 配置 / 工作区后）
bun run openclaw setup
bun run gateway:watch
```
### 2）让 macOS 应用连接到你正在运行的 Gateway 网关
### 2) 让 macOS 应用指向你正在运行的 Gateway 网关
在 **OpenClaw.app** 中：
- 连接模式：**本地**
应用将连接到配置端口上正在运行的 gateway。
- 连接模式：**Local**
应用会连接到配置端口上正在运行的 Gateway 网关。
### 3）验证
### 3) 验证
- 应用内的 Gateway 网关状态应显示为 **“Using existing gateway …”**
- 或通过 CLI：
- 或者通过 CLI：
```bash
openclaw health
```
### 常见坑点
### 常见易错点
- **端口错误：** Gateway 网关 WS 默认为 `ws://127.0.0.1:18789`；确保应用和 CLI 使用相同端口。
- **状态存储位置：**
- 渠道/provider 状态：`~/.openclaw/credentials/`
- 模型认证配置文件：`~/.openclaw/agents/<agentId>/agent/auth-profiles.json`
- **端口错误：** Gateway 网关 WS 默认是 `ws://127.0.0.1:18789`；请确保应用和 CLI 使用同一个端口。
- **状态数据存放位置：**
- 渠道 / 提供商状态：`~/.openclaw/credentials/`
- 模型凭证配置：`~/.openclaw/agents/<agentId>/agent/auth-profiles.json`
- 会话：`~/.openclaw/agents/<agentId>/sessions/`
- 日志：`/tmp/openclaw/`
## 凭证存储映射
在调试认证问题或决定要备份哪些内容时，请参考这一节：
在调试认证问题或决定要备份哪些内容时，请参考这里：
- **WhatsApp**：`~/.openclaw/credentials/whatsapp/<accountId>/creds.json`
- **Telegram 机器人令牌**：配置/环境变量或 `channels.telegram.tokenFile`（仅允许常规文件；拒绝符号链接）
- **Discord 机器人令牌**：配置/环境变量或 SecretRef（env/file/exec providers）
- **Slack 令牌**：配置/环境变量（`channels.slack.*`）
- **配对 allowlist**：
- `~/.openclaw/credentials/<channel>-allowFrom.json`（默认账户）
- `~/.openclaw/credentials/<channel>-<accountId>-allowFrom.json`（非默认账户）
- **模型认证配置文件**：`~/.openclaw/agents/<agentId>/agent/auth-profiles.json`
- **Telegram 机器人令牌**：配置 / 环境变量，或 `channels.telegram.tokenFile`（仅允许常规文件；拒绝符号链接）
- **Discord 机器人令牌**：配置 / 环境变量，或 SecretRef（env / file / exec 提供商）
- **Slack 令牌**：配置 / 环境变量（`channels.slack.*`）
- **配对允许列表**：
- `~/.openclaw/credentials/<channel>-allowFrom.json`（默认账号）
- `~/.openclaw/credentials/<channel>-<accountId>-allowFrom.json`（非默认账号）
- **模型凭证配置**：`~/.openclaw/agents/<agentId>/agent/auth-profiles.json`
- **基于文件的 secrets 负载（可选）**：`~/.openclaw/secrets.json`
- **旧版 OAuth 导入**：`~/.openclaw/credentials/oauth.json`
更多详情： [安全](/zh-CN/gateway/security#credential-storage-map)。
## 更新（不破坏你的设置）
- 将 `~/.openclaw/workspace` 和 `~/.openclaw/` 视为“你自己的内容”；不要把个人提示词/配置放进 `openclaw` 仓库。
- 更新源码：`git pull` + 你选择的包管理器安装步骤（默认是 `pnpm install`；如果使用 Bun 工作流则为 `bun install`）+ 持续使用对应的 `gateway:watch` 命令。
- 将 `~/.openclaw/workspace` 和 `~/.openclaw/` 视为“你的东西”；不要把个人提示词 / 配置放进 `openclaw` 仓库。
- 更新源码：`git pull` + 你选择的包管理器安装步骤（默认 `pnpm install`；Bun 工作流则使用 `bun install`）+ 继续使用对应的 `gateway:watch` 命令。
## Linux（systemd 用户服务）
Linux 安装使用 systemd **用户**服务。默认情况下，systemd 会在用户注销/空闲时停止用户服务，这会终止 Gateway 网关。新手引导会尝试为你启用 lingering（可能会提示输入 sudo）。如果它仍未启用，请运行：
Linux 安装使用 systemd **用户**服务。默认情况下，systemd 会在你登出 / 空闲时停止用户服务，这会终止 Gateway 网关。新手引导会尝试为你启用 lingering（可能会提示输入 sudo）。如果它仍未启用，请运行：
```bash
sudo loginctl enable-linger $USER
```
对于常开或多用户服务器，请考虑使用 **系统**服务而不是用户服务（无需 lingering）。有关 systemd 说明，请参阅 [Gateway 网关运行手册](/zh-CN/gateway)。
对于始终在线或多用户服务器，建议考虑使用 **系统**服务，而不是用户服务（无需 lingering）。有关 systemd 的说明，请参阅 [Gateway 网关运行手册](/zh-CN/gateway)。
## 相关文档
- [Gateway 网关运行手册](/zh-CN/gateway)（标志、监管、端口）
- [Gateway 网关配置](/zh-CN/gateway/configuration)（配置模式 + 示例）
- [Discord](/zh-CN/channels/discord) 和 [Telegram](/zh-CN/channels/telegram)（回复标签 + replyToMode 设置）
- [Gateway 网关配置](/zh-CN/gateway/configuration)（配置 schema + 示例）
- [Discord](/zh-CN/channels/discord) 和 [Telegram](/zh-CN/channels/telegram)（回复标签 + `replyToMode` 设置）
- [OpenClaw 助手设置](/zh-CN/start/openclaw)
- [macOS 应用](/zh-CN/platforms/macos)（gateway 生命周期）
- [macOS 应用](/zh-CN/platforms/macos)（Gateway 网关生命周期）