# OpenClaw 配置指南 **多平台 AI 编程代理，支持终端 TUI、Web Dashboard 和 Telegram Bot** 📋 简介 OpenClaw 是一款功能丰富的 AI 编程代理工具，支持终端 TUI 交互、Web Dashboard 管理和 Telegram Bot 远程访问。适合需要在服务器环境中运行 AI 编程助手的开发者。 ⚠️ 适用环境 此教程适合 **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" } 1 2 3 4 * `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 耐心等待安装流程结束。 ### 第二步：初始化配置 安装过程中会依次出现以下选项，按照说明操作： 步骤| 选择| 说明 ---|---|--- 启动方式| **QuickStart**| 快速开始模式 供应商设置| **Skip for now**| 先跳过，后续手动编辑配置文件 适配器选择| **anthropic**| 选择 Anthropic 适配器 模型选择| **opus-4.5**| 或选择你需要的模型 社交适配器| 按需选择| 如 Telegram（可选） Skill 安装| 跳过| 后续可通过 Dashboard 安装 Hook 选择| 全选| 使用空格键全选后回车确认 打开方式| 跳过| 先跳过 Shell 补全| **yes**| 安装命令行自动补全 ## ⚙️ 渠道与模型配置 ### 第一步：编辑配置文件 打开 OpenClaw 的配置文件进行编辑： bash vim ~/.openclaw/openclaw.json 1 参照下方 完整配置实例 填入你的供应商和模型信息。 ### 第二步：填入 API Key 在 `models.providers` 中配置供应商信息，将 `apiKey` 和 `headers.Authorization` 替换为你在 [IkunCode 控制台]() 创建的 API Key。 💡 支持的分组 OpenClaw 使用 **逆向分组** 的 API Key。 ![只允许逆向分组](`+a+`) 请在 [创建专属 Key]() 时选择逆向分组。 ### 第三步：重启网关 bash openclaw gateway restart 1 ### 第四步：验证配置 运行以下命令进入 TUI 界面测试模型是否正常： bash openclaw tui 1 测试成功后输入 `/quit` 退出 TUI。 ## 🌐 浏览器访问 Dashboard ### 获取 Dashboard URL 在控制台运行命令获取 Dashboard URL，在浏览器中访问即可进入管理面板。 ⚠️ 服务器用户注意 如果你在远程服务器运行 OpenClaw，需要： **1\. 配置反向代理** 使用 Nginx 或其他反向代理工具反代 OpenClaw 服务，并设置 SSL 证书。 **2\. 修改配置文件** 编辑 `~/.openclaw/openclaw.json`，在 `gateway` 字段下添加： json "controlUi": { "allowInsecureAuth": true } 1 2 3 **3\. 重启网关** bash openclaw gateway restart 1 访问带有 Token 的 Dashboard URL 即可进入后台界面。 ## 🤖 配置 Telegram Bot（可选） 如果安装时选择了 Telegram 适配器，可以通过以下步骤配置 Bot 访问权限： ### 第一步：与 Bot 对话 在 Telegram 中找到你通过 **@BotFather** 创建的机器人，发起对话。 ### 第二步：获取 Pairing Code 首次对话后会收到一个 **Pairing Code** 。 ### 第三步：授权配对 在控制台运行以下命令完成授权： bash openclaw pairing approve telegram 你的Pairing_Code 1 配对成功后，即可通过 Telegram Bot 与 OpenClaw 进行远程对话。 ## 📄 完整配置实例 以下是一份接入 IkunCode 渠道的 `openclaw.json` 完整配置参考（路径：`~/.openclaw/openclaw.json`）： 💡 说明 配置中的 `sk-xxxx` 和 `xxxxx` 为占位符，请替换为你自己的 API Key 和 Bot Token。 json { "messages": { "ackReactionScope": "group-mentions" }, "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" } }, "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 } } ] } } }, "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 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" } 1 2 3 4 🚨 重要 * `headers` 中的 `Authorization` 值必须与 `apiKey` 一致，格式为 `Bearer sk-你的密钥` * `User-Agent` 必须保持示例格式，否则请求会被拦截 * 配置完成后执行 `openclaw gateway restart` 重启网关 ### Gateway 重启后模型仍不可用？ * 检查 API Key 是否正确填入 * 确认 Key 对应的分组支持你选择的模型 * 查看 OpenClaw 日志排查具体错误 ### 更多问题 请查看 [FAQ]() 或联系[售后支持]()。