From 53e1357203f4108c303a80d99ec6066d4377885d Mon Sep 17 00:00:00 2001 From: zyc123 <2594064239@qq.com> Date: Thu, 14 May 2026 11:34:40 +0800 Subject: [PATCH] 125 --- apps/openclaw.md | 667 ++++++++++++++++++----------------------------- 1 file changed, 254 insertions(+), 413 deletions(-) diff --git a/apps/openclaw.md b/apps/openclaw.md index 12a8c1d..28291b3 100644 --- a/apps/openclaw.md +++ b/apps/openclaw.md @@ -1,498 +1,339 @@ -# OpenClaw 配置指南 +# OpenClaw 配置指南 **多平台 AI 编程代理，支持终端 TUI、Web Dashboard 和 Telegram Bot** -📋 简介 +## 📋 简介 OpenClaw 是一款功能丰富的 AI 编程代理工具，支持终端 TUI 交互、Web Dashboard 管理和 Telegram Bot 远程访问。适合需要在服务器环境中运行 AI 编程助手的开发者。 -⚠️ 适用环境 +> ⚠️ **适用环境** +> 本教程适用于 **Linux 云服务器** 和 **macOS** 系统用户。 -此教程适合 **Linux 云服务器** 和 **macOS** 系统用户。 +> 🚨 **遇到 403 Your request was blocked？** +> 使用 oneinai 渠道时，**必须**在供应商配置中添加 `headers` 字段，否则请求会被拦截返回 403： +> +> ```json +> "headers": { +> "User-Agent": "claude-cli/2.0.76 (external, cli)", +> "Authorization": "Bearer sk-xxxx" +> } +> ``` +> +> - `Authorization` 的值必须与 `apiKey` 一致，格式为 `Bearer sk-你的密钥` +> - `User-Agent` 必须保持示例中的格式，不可省略或随意修改 +> - 修改后执行 `openclaw gateway restart` 重启网关生效 +> +> 详见下方[完整配置实例](#-完整配置实例)。 -🚨 遇到 403 Your request was blocked？ +## 🔗 相关链接 -使用 OneinAI 渠道时，**必须** 在供应商配置中添加 `headers` 字段，否则请求会被拦截返回 403： +| 资源 | 地址 | +| --- | --- | +| OpenClaw 官网 | | +| oneinai 控制台 | | -json - - - "headers": { - "User-Agent": "claude-cli/2.0.76 (external, cli)", - "Authorization": "Bearer sk-xxxx" - } +## ✨ 功能特点 -1 -2 -3 -4 +- ✅ **终端 TUI**：命令行交互界面，适合 SSH 环境 +- ✅ **Web Dashboard**：浏览器可视化管理面板 +- ✅ **Telegram Bot**：支持通过 Telegram 远程对话 +- ✅ **多模型支持**：Claude、GPT、Gemini 等多种模型 +- ✅ **Gateway 网关**：内置网关服务，支持反向代理 +- ✅ **Skill 扩展**：可通过 Dashboard 安装扩展技能 - * `Authorization` 的值必须与 `apiKey` 一致，格式为 `Bearer sk-你的密钥` - * `User-Agent` 必须保持示例中的格式，不可省略或随意修改 - * 修改后执行 `openclaw gateway restart` 重启网关生效 +## 🛠️ 安装与初始化 -详见下方 完整配置实例。 - -## 🔗 相关链接 - -资源| 地址 ----|--- -OpenClaw 官网| - -## ✨ 功能特点 - - * ✅ **终端 TUI** ：命令行交互界面，适合 SSH 环境 - * ✅ **Web Dashboard** ：浏览器可视化管理面板 - * ✅ **Telegram Bot** ：支持通过 Telegram 远程对话 - * ✅ **多模型支持** ：Claude、GPT、Gemini 等多种模型 - * ✅ **Gateway 网关** ：内置网关服务，支持反向代理 - * ✅ **Skill 扩展** ：可通过 Dashboard 安装扩展技能 - -## 🛠️ 安装与初始化 - -### 第一步：运行安装脚本 +### 第一步：运行安装脚本 登录服务器 SSH 或在 macOS 终端中运行以下命令： -bash - - - curl -fsSL https://openclaw.ai/install.sh | bash - -1 +```bash +curl -fsSL https://openclaw.ai/install.sh | bash +``` 耐心等待安装流程结束。 -### 第二步：初始化配置 +### 第二步：初始化配置 -安装过程中会依次出现以下选项，按照说明操作： +安装过程中会依次出现以下选项，按说明选择： -步骤| 选择| 说明 ----|---|--- -启动方式| **QuickStart**| 快速开始模式 -供应商设置| **Skip for now**| 先跳过，后续手动编辑配置文件 -适配器选择| **anthropic**| 选择 Anthropic 适配器 -模型选择| **opus-4.5**| 或选择你需要的模型 -社交适配器| 按需选择| 如 Telegram（可选） -Skill 安装| 跳过| 后续可通过 Dashboard 安装 -Hook 选择| 全选| 使用空格键全选后回车确认 -打开方式| 跳过| 先跳过 -Shell 补全| **yes**| 安装命令行自动补全 - -## ⚙️ 渠道与模型配置 +| 步骤 | 选择 | 说明 | +| --- | --- | --- | +| 启动方式 | **QuickStart** | 快速开始模式 | +| 供应商设置 | **Skip for now** | 先跳过，后续手动编辑配置文件 | +| 适配器选择 | **anthropic** | 选择 Anthropic 适配器 | +| 模型选择 | **opus-4.5** | 或选择你需要的模型 | +| 社交适配器 | 按需选择 | 如 Telegram（可选） | +| Skill 安装 | 跳过 | 后续可通过 Dashboard 安装 | +| Hook 选择 | 全选 | 使用空格键全选后回车确认 | +| 打开方式 | 跳过 | 先跳过 | +| Shell 补全 | **yes** | 安装命令行自动补全 | -### 第一步：编辑配置文件 +## ⚙️ 渠道与模型配置 + +### 第一步：编辑配置文件 打开 OpenClaw 的配置文件进行编辑： -bash - - - vim ~/.openclaw/openclaw.json +```bash +vim ~/.openclaw/openclaw.json +``` -1 +参照下方[完整配置实例](#-完整配置实例)填入供应商和模型信息。 -参照下方 完整配置实例 填入你的供应商和模型信息。 +### 第二步：填入 API Key -### 第二步：填入 API Key +在 `models.providers` 中配置供应商信息，将 `apiKey` 和 `headers.Authorization` 替换为你在 [oneinai 控制台](https://api.oneinai.com/console/token) 创建的 API Key。 -在 `models.providers` 中配置供应商信息，将 `apiKey` 和 `headers.Authorization` 替换为你在 [IkunCode 控制台]() 创建的 API Key。 +> 💡 **支持的分组** +> OpenClaw 使用 **逆向分组** 的 API Key。请在[创建专属 Key](/guide/create-key) 时选择逆向分组。 -💡 支持的分组 +### 第三步：重启网关 -OpenClaw 使用 **逆向分组** 的 API Key。 +```bash +openclaw gateway restart +``` -![只允许逆向分组](`+a+`) - -请在 [创建专属 Key]() 时选择逆向分组。 - -### 第三步：重启网关 - -bash - - - openclaw gateway restart - -1 - -### 第四步：验证配置 +### 第四步：验证配置 运行以下命令进入 TUI 界面测试模型是否正常： -bash - - - openclaw tui - -1 +```bash +openclaw tui +``` 测试成功后输入 `/quit` 退出 TUI。 -## 🌐 浏览器访问 Dashboard +## 🌐 浏览器访问 Dashboard -### 获取 Dashboard URL +### 获取 Dashboard URL 在控制台运行命令获取 Dashboard URL，在浏览器中访问即可进入管理面板。 -⚠️ 服务器用户注意 +> ⚠️ **服务器用户注意** +> 如果你在远程服务器上运行 OpenClaw，需要完成以下额外步骤。 -如果你在远程服务器运行 OpenClaw，需要： +**1. 配置反向代理** -**1\. 配置反向代理** +使用 Nginx 或其他反向代理工具反代 OpenClaw 服务，并配置 SSL 证书。 -使用 Nginx 或其他反向代理工具反代 OpenClaw 服务，并设置 SSL 证书。 - -**2\. 修改配置文件** +**2. 修改配置文件** 编辑 `~/.openclaw/openclaw.json`，在 `gateway` 字段下添加： -json - - - "controlUi": { - "allowInsecureAuth": true - } +```json +"controlUi": { + "allowInsecureAuth": true +} +``` -1 -2 -3 +**3. 重启网关** -**3\. 重启网关** - -bash - - - openclaw gateway restart - -1 +```bash +openclaw gateway restart +``` 访问带有 Token 的 Dashboard URL 即可进入后台界面。 -## 🤖 配置 Telegram Bot（可选） +## 🤖 配置 Telegram Bot（可选） -如果安装时选择了 Telegram 适配器，可以通过以下步骤配置 Bot 访问权限： +如果安装时选择了 Telegram 适配器，可以通过以下步骤配置 Bot 访问权限。 -### 第一步：与 Bot 对话 +### 第一步：与 Bot 对话 在 Telegram 中找到你通过 **@BotFather** 创建的机器人，发起对话。 -### 第二步：获取 Pairing Code +### 第二步：获取 Pairing Code -首次对话后会收到一个 **Pairing Code** 。 +首次对话后会收到一个 **Pairing Code**。 -### 第三步：授权配对 +### 第三步：授权配对 在控制台运行以下命令完成授权： -bash - - - openclaw pairing approve telegram 你的Pairing_Code - -1 +```bash +openclaw pairing approve telegram 你的Pairing_Code +``` 配对成功后，即可通过 Telegram Bot 与 OpenClaw 进行远程对话。 -## 📄 完整配置实例 +## 📄 完整配置实例 -以下是一份接入 IkunCode 渠道的 `openclaw.json` 完整配置参考（路径：`~/.openclaw/openclaw.json`）： +以下是一份接入 oneinai 渠道的 `openclaw.json` 完整参考（路径：`~/.openclaw/openclaw.json`）： -💡 说明 +> 💡 **说明** +> 配置中的 `sk-xxxx` 和 `xxxxx` 为占位符，请替换为你自己的 API Key 和 Bot Token。 -配置中的 `sk-xxxx` 和 `xxxxx` 为占位符，请替换为你自己的 API Key 和 Bot Token。 - -json - - - { - "messages": { - "ackReactionScope": "group-mentions" +```json +{ + "messages": { + "ackReactionScope": "group-mentions" + }, + "agents": { + "defaults": { + "model": { + "primary": "oneinai-claude/claude-opus-4-5-20251101" }, - "agents": { - "defaults": { - "model": { - "primary": "ikuncode-claude/claude-opus-4-5-20251101" - }, - "maxConcurrent": 4, - "subagents": { - "maxConcurrent": 8 - }, - "compaction": { - "mode": "safeguard" - }, - "workspace": "C:\\\\Users\\\\Administrator\\\\.openclaw\\\\workspace" - } + "maxConcurrent": 4, + "subagents": { + "maxConcurrent": 8 }, - "models": { - "providers": { - "ikuncode-claude": { - "baseUrl": "https://api.oneinai.com/v1", - "apiKey": "sk-xxxx", - "api": "openai-completions", - "headers": { - "User-Agent": "claude-cli/2.0.76 (external, cli)", - "Authorization": "Bearer sk-xxxx" - }, - "models": [ - { - "id": "claude-opus-4-5-20251101", - "name": "claude-opus-4-5-20251101", - "contextWindow": 200000, - "maxTokens": 32000, - "cost": { - "input": 0, - "output": 0, - "cacheRead": 0, - "cacheWrite": 0 - } - } - ] - }, - "ikuncode-codex": { - "baseUrl": "https://api.oneinai.com/v1", - "apiKey": "sk-xxxx", - "api": "openai-completions", - "headers": { - "User-Agent": "codex_cli_rs/0.77.0 (Windows 10.0.26100; x86_64) WindowsTerminal", - "Authorization": "Bearer sk-xxxx" - }, - "models": [ - { - "id": "gpt-5.2-codex", - "name": "gpt-5.2-codex", - "contextWindow": 200000, - "maxTokens": 32000, - "cost": { - "input": 0, - "output": 0, - "cacheRead": 0, - "cacheWrite": 0 - } - } - ] - } - } + "compaction": { + "mode": "safeguard" }, - "gateway": { - "mode": "local", - "auth": { - "mode": "token", - "token": "xxxx" + "workspace": "C:\\\\Users\\\\Administrator\\\\.openclaw\\\\workspace" + } + }, + "models": { + "providers": { + "oneinai-claude": { + "baseUrl": "https://api.oneinai.com/v1", + "apiKey": "sk-xxxx", + "api": "openai-completions", + "headers": { + "User-Agent": "claude-cli/2.0.76 (external, cli)", + "Authorization": "Bearer sk-xxxx" }, - "port": 18789, - "bind": "loopback", - "tailscale": { - "mode": "off", - "resetOnExit": false - } - }, - "auth": { - "profiles": {} - }, - "plugins": { - "entries": { - "telegram": { - "enabled": true + "models": [ + { + "id": "claude-opus-4-5-20251101", + "name": "claude-opus-4-5-20251101", + "contextWindow": 200000, + "maxTokens": 32000, + "cost": { + "input": 0, + "output": 0, + "cacheRead": 0, + "cacheWrite": 0 + } } - } + ] }, - "channels": { - "telegram": { - "enabled": true, - "botToken": "xxxxx" - } - }, - "logging": { - "level": "trace", - "consoleLevel": "debug", - "consoleStyle": "pretty" - }, - "commands": { - "restart": true - }, - "skills": { - "install": { - "nodeManager": "npm" - } + "oneinai-codex": { + "baseUrl": "https://api.oneinai.com/v1", + "apiKey": "sk-xxxx", + "api": "openai-completions", + "headers": { + "User-Agent": "codex_cli_rs/0.77.0 (Windows 10.0.26100; x86_64) WindowsTerminal", + "Authorization": "Bearer sk-xxxx" + }, + "models": [ + { + "id": "gpt-5.2-codex", + "name": "gpt-5.2-codex", + "contextWindow": 200000, + "maxTokens": 32000, + "cost": { + "input": 0, + "output": 0, + "cacheRead": 0, + "cacheWrite": 0 + } + } + ] } } - -1 -2 -3 -4 -5 -6 -7 -8 -9 -10 -11 -12 -13 -14 -15 -16 -17 -18 -19 -20 -21 -22 -23 -24 -25 -26 -27 -28 -29 -30 -31 -32 -33 -34 -35 -36 -37 -38 -39 -40 -41 -42 -43 -44 -45 -46 -47 -48 -49 -50 -51 -52 -53 -54 -55 -56 -57 -58 -59 -60 -61 -62 -63 -64 -65 -66 -67 -68 -69 -70 -71 -72 -73 -74 -75 -76 -77 -78 -79 -80 -81 -82 -83 -84 -85 -86 -87 -88 -89 -90 -91 -92 -93 -94 -95 -96 -97 -98 -99 -100 -101 -102 -103 -104 -105 -106 -107 -108 -109 -110 -111 -112 - -### 关键字段说明 - -字段| 说明 ----|--- -`agents.defaults.model.primary`| 默认使用的模型，格式为 `供应商名/模型ID` -`agents.defaults.maxConcurrent`| 主代理最大并发数 -`agents.defaults.subagents.maxConcurrent`| 子代理最大并发数 -`agents.defaults.compaction.mode`| 上下文压缩模式，`safeguard` 为安全模式 -`agents.defaults.workspace`| 工作区目录路径，按你的系统修改 -`models.providers`| 模型供应商配置，可配置多个供应商 -`models.providers.*.baseUrl`| API 基础地址，IkunCode 统一为 `https://api.oneinai.com/v1` -`models.providers.*.apiKey`| 对应分组的 API Key -`models.providers.*.api`| 接口协议，固定为 `openai-completions` -`models.providers.*.headers`| 请求头，需包含 `User-Agent` 和 `Authorization` -`gateway.port`| 网关监听端口，默认 `18789` -`gateway.bind`| 绑定模式，`loopback` 仅本机访问 -`channels.telegram.botToken`| Telegram Bot Token，通过 @BotFather 获取 -`logging.level`| 日志级别，排查问题时可设为 `trace` - -⚠️ 注意事项 - - * **Headers 中的 Authorization** 必须与 `apiKey` 保持一致，格式为 `Bearer sk-xxxx` - * **User-Agent** 建议保持示例中的格式，确保请求正常识别 - * **workspace 路径** ：Windows 用户使用 `\\\\` 双反斜杠，Linux/macOS 用户使用 `/` 正斜杠（如 `/root/.openclaw/workspace`） - * **cost 全部设为 0** ：通过 IkunCode 中转使用时无需在本地计费 - -## 常见问题 - -### 安装脚本执行失败？ - - * 确认网络连接正常，能访问 `openclaw.ai` - * 确认系统已安装 `curl` 和 `bash` - * 如果在国内服务器，可能需要配置代理 - -### 遇到 403 `Your request was blocked` 怎么办？ - -如果请求返回 `403 Your request was blocked`，说明缺少正确的请求头。**必须** 在供应商配置中添加 `headers` 字段： - -json - - - "headers": { - "User-Agent": "claude-cli/2.0.76 (external, cli)", - "Authorization": "Bearer sk-xxxx" + }, + "gateway": { + "mode": "local", + "auth": { + "mode": "token", + "token": "xxxx" + }, + "port": 18789, + "bind": "loopback", + "tailscale": { + "mode": "off", + "resetOnExit": false } + }, + "auth": { + "profiles": {} + }, + "plugins": { + "entries": { + "telegram": { + "enabled": true + } + } + }, + "channels": { + "telegram": { + "enabled": true, + "botToken": "xxxxx" + } + }, + "logging": { + "level": "trace", + "consoleLevel": "debug", + "consoleStyle": "pretty" + }, + "commands": { + "restart": true + }, + "skills": { + "install": { + "nodeManager": "npm" + } + } +} +``` -1 -2 -3 -4 +### 关键字段说明 -🚨 重要 +| 字段 | 说明 | +| --- | --- | +| `agents.defaults.model.primary` | 默认使用的模型，格式为 `供应商名/模型ID` | +| `agents.defaults.maxConcurrent` | 主代理最大并发数 | +| `agents.defaults.subagents.maxConcurrent` | 子代理最大并发数 | +| `agents.defaults.compaction.mode` | 上下文压缩模式，`safeguard` 为安全模式 | +| `agents.defaults.workspace` | 工作区目录路径，按你的系统修改 | +| `models.providers` | 模型供应商配置，可配置多个供应商 | +| `models.providers.*.baseUrl` | API 基础地址，oneinai 统一为 `https://api.oneinai.com/v1` | +| `models.providers.*.apiKey` | 对应分组的 API Key | +| `models.providers.*.api` | 接口协议，固定为 `openai-completions` | +| `models.providers.*.headers` | 请求头，需包含 `User-Agent` 和 `Authorization` | +| `gateway.port` | 网关监听端口，默认 `18789` | +| `gateway.bind` | 绑定模式，`loopback` 仅本机访问 | +| `channels.telegram.botToken` | Telegram Bot Token，通过 @BotFather 获取 | +| `logging.level` | 日志级别，排查问题时可设为 `trace` | - * `headers` 中的 `Authorization` 值必须与 `apiKey` 一致，格式为 `Bearer sk-你的密钥` - * `User-Agent` 必须保持示例格式，否则请求会被拦截 - * 配置完成后执行 `openclaw gateway restart` 重启网关 +> ⚠️ **注意事项** +> - **Headers 中的 Authorization** 必须与 `apiKey` 保持一致，格式为 `Bearer sk-xxxx` +> - **User-Agent** 必须保持示例中的格式，确保请求正常识别 +> - **workspace 路径**：Windows 用户使用 `\\\\` 双反斜杠，Linux/macOS 用户使用 `/` 正斜杠（如 `/root/.openclaw/workspace`） +> - **cost 全部设为 0**：通过 oneinai 中转使用时无需在本地计费 -### Gateway 重启后模型仍不可用？ +## ❓ 常见问题 - * 检查 API Key 是否正确填入 - * 确认 Key 对应的分组支持你选择的模型 - * 查看 OpenClaw 日志排查具体错误 +### 安装脚本执行失败？ -### 更多问题 +- 确认网络连接正常，能访问 `openclaw.ai` +- 确认系统已安装 `curl` 和 `bash` +- 如果在国内服务器，可能需要配置代理 -请查看 [FAQ]() 或联系[售后支持]()。 +### 遇到 403 `Your request was blocked` 怎么办？ + +如果请求返回 `403 Your request was blocked`，说明缺少正确的请求头。**必须**在供应商配置中添加 `headers` 字段： + +```json +"headers": { + "User-Agent": "claude-cli/2.0.76 (external, cli)", + "Authorization": "Bearer sk-xxxx" +} +``` + +> 🚨 **重要** +> - `headers` 中的 `Authorization` 值必须与 `apiKey` 一致，格式为 `Bearer sk-你的密钥` +> - `User-Agent` 必须保持示例格式，否则请求会被拦截 +> - 配置完成后执行 `openclaw gateway restart` 重启网关 + +### Gateway 重启后模型仍不可用？ + +- 检查 API Key 是否正确填入 +- 确认 Key 对应的分组支持你选择的模型 +- 查看 OpenClaw 日志排查具体错误 + +### 更多问题 + +请查看 [FAQ](/support/faq) 或联系[售后支持](/support/after-sales)。