OpenClaw 在 Ubuntu 22.04 上的安装与初始化指南

系统会提示安全风险。如果你是个人本地使用且理解风险，选择 Yes 继续；如果是团队或多用户场景，建议选择 No，先完成安全加固和权限隔离。

2. 部署模式选择

这是初始化流程中的关键决策点，主要有两种模式：

• 优先选 Quickstart：首次接触 OpenClaw，仅需本地测试 AI 代理的文件操作、命令执行等基础能力，或部署环境为本地隔离环境。
• 必须选 Manual：计划将 OpenClaw 暴露至公网、局域网，或供多用户/团队使用，需自定义安全策略。

后续操作指引

• 选择 Quickstart 后：部署完成后，执行 openclaw configure 补全 API 密钥、工具启用列表及安全审计规则。
• 选择 Manual 后：跟随交互式提示依次完成网关配置、大模型参数、工具权限及安全配置，无需后续补配。

3. 模型/认证提供商选择

根据需求选择合适的大模型服务：

• 国际主流：OpenAI (Codex QAUTH + API key)、Anthropic (Claude)、xAI (Grok)、Google (Gemini)。
• 国内主流：BytePlus、Moonshot AI (Kimi K2.5)、Qwen、Z.AI、Qianfan、Xiaomi 等。
• 聚合网关：OpenRouter、Cloudflare AI Gateway、Vercel AI Gateway。
• 自定义：Custom Provider（支持私有部署）。
• 暂时跳过：Skip for now（后续通过 openclaw configure 补全）。

选型建议：个人快速体验优先选 OpenAI 或 OpenRouter；国内环境可选 Moonshot 或 Qwen；已有统一网关的团队直接选对应选项。

4. 对接通义千问（Qwen）的 OAuth 授权

若选择 Qwen，需完成 OAuth 授权流程：

1. 完成授权：登录通义千问账号，输入用户码或直接确认授权。
2. 等待连接：终端显示 "Waiting for Qwen OAuth approval…"，自动获取访问令牌。

打开授权链接：

https://chat.qwen.ai/authorize?user_code=CEEGL6GX&client=qwen-code

常见问题：链接无法访问请检查网络；授权超时需重新发起；确保账号已开通 API 访问权限。

5. 配置界面解读

授权完成后，界面会显示配置状态：

• Qwen OAuth complete：授权成功。
• Model configured：默认模型为 qwen-portal/coder-model。
• Token 自动刷新：令牌会自动刷新，失败需重新登录。
• Default model：可选择保持当前代码模型，或手动输入私有模型名称。

6. 频道（Channels）工作原理

OpenClaw 支持多种通讯渠道接入，核心是安全机制和各渠道特点：

• DM 安全：陌生私信要求配对码，防止未授权访问。公网部署建议关闭 allowFrom=["*"]，改用白名单。
• 多用户 DM：通过配置隔离会话，避免跨用户权限泄露。

常见渠道接入方式：

7. 插件安装（以飞书为例）

配置飞书频道时，有三种插件安装选项：

• Download from npm：从官方仓库下载最新版，适合首次安装。
• Use local plugin path：使用本地已存在的插件目录，适合调试。
• Skip for now：暂时跳过，后续补全。

选型建议：首次使用选 Download from npm；本地开发调试选 Use local plugin path。

凭证配置步骤

1. 访问 飞书开放平台，创建自建应用。
2. 获取 App ID 和 App Secret。
3. 启用必要权限（如 im:message, im:chat）。
4. 发布应用或加入测试组。
5. 在 OpenClaw 中配置环境变量或交互式输入。

安全加固建议

• 显式信任插件：设置 plugins.allow，仅允许飞书插件加载。
• 权限最小化：仅启用所需的最小权限集。
• 凭证保护：不要硬编码 App Secret，优先使用环境变量。

8. App Secret 存储方式

• Enter App Secret：直接存储在配置文件中，适合个人测试，安全性较低。
• Use external secret provider：使用外部密钥管理服务（如 Vault），适合生产环境，安全性高。

9. 连接模式选择

• WebSocket (default)：OpenClaw 主动建立长连接，无需公网 IP，适合本地测试。
• Webhook：飞书服务器推送 HTTP 请求，需公网 IP 或域名，适合生产环境。

10. 群组聊天策略配置

• Allowlist：仅在白名单群组响应，最安全，适合企业协作。
• Open (requires mention)：所有群组响应但需提及，兼顾便利与安全。
• Disabled：禁用群组响应，仅私信可用，隐私性最高。

11. 群组 ID 白名单

填写多个群组 ID 时用英文逗号分隔，格式通常为 oc_ 开头。需在飞书客户端群设置中复制群 ID。

12. 最终校验与重复插件警告

配置完成后，可能会检测到重复插件 ID 警告（例如 feishu 插件）。这通常是因为重复安装导致的。

解决方案：

1. 停止服务：systemctl stop openclaw-gateway
2. 清理重复插件：删除多余的插件文件夹，保留一个版本。
3. 强制指定信任插件：openclaw config set plugins.allow '["/root/.openclaw/extensions/feishu/index.ts"]'
4. 重启服务：systemctl start openclaw-gateway

13. Web 搜索工具配置

用于让智能体具备联网查询能力：

• Brave Search：结构化结果，隐私友好。
• Gemini (Google Search)：基于 Google 搜索，结果全面。
• Kimi (Moonshot)：对中文内容支持更好。
• Perplexity Search：深度分析，引用来源。

选型建议：中文场景优先 Kimi；精准结构化选 Brave；已用 Gemini 模型则选 Gemini Search。

14. Skills 状态汇总

初始化后的技能状态汇总界面显示：

• Eligible：满足依赖条件的技能数量。
• Missing requirements：缺少依赖的技能数量。
• Unsupported on this OS：不兼容操作系统的技能。

建议：优先启用核心技能（文件操作、代码执行），按需安装缺失依赖。

15. 依赖安装处理

如果安装 github 技能失败，通常是因为缺少 Homebrew 或 gh 命令行工具。OpenClaw 会提示安装 Homebrew 或手动安装 gh。

16. 其他可选技能配置

以下技能可根据需求选择是否配置 API Key：

• goplaces：地点查询和地图功能（需 Google Places API Key）。
• nano-banana-pro：增强 AI 能力（需 Gemini API Key）。
• notion：笔记/知识库交互（需 Notion API Key）。
• openai-image-gen：图像生成（需 OpenAI API Key）。
• openai-whisper-api：语音转文字（需 OpenAI API Key）。
• sag：语音合成（需 ElevenLabs API Key）。

若无特定需求，选择 No 跳过即可，不影响核心功能。

17. Hooks 配置

Hooks 用于在智能体执行命令时自动触发操作：

• boot-md：启动时生成 Markdown 报告。
• command-logger：记录所有执行的命令，便于审计。
• session-memory：保存会话上下文。

建议启用 command-logger 以便追踪操作历史。

18. 启动 Gateway 服务

启动时会进行系统检查：

• Systemd Lingering：确保服务在用户登出后继续运行。
• Node.js 版本：若系统默认版本过低（如 v12），会自动切换至 nvm 管理的 v24+ 版本。建议后续升级系统默认 Node.js 版本以避免兼容性问题。

19. 日志与故障排查

启动日志可能包含两类问题：

1. 重复插件警告：非致命，但建议清理冗余插件文件。
2. 飞书频道启动失败：错误 API error: app do not have bot。解决方法是在飞书开放平台启用'机器人'功能，并确保事件订阅 URL 和权限范围正确。

20. 智能体孵化与 Dashboard

最后一步是选择如何'孵化'智能体：

• Hatch in TUI (recommended)：终端对话方式配置，个性化体验最佳。
• Open the Web UI：浏览器图形化配置。
• Do this later：稍后配置。

Dashboard 访问方式：

• 本地访问：http://127.0.0.1:18789/#token=XXXXXXXXXXX
• 远程访问：建立 SSH 隧道后访问 localhost:18789

ssh -N -L 18789:127.0.0.1:18789 [email protected]

下一步：访问 Dashboard 开始配置，修复飞书频道问题，并根据需要启用更多技能和 Hooks。