AI Agent 工具实训重点汇总

发布于 1 小时前 3 次阅读

AI Agent 工具实训重点汇总

整合来源：Claude Code 安装、Codex CLI、Hermes 微信&飞书接入、OpenClaw 安装、Hermes（爱马仕）安装 整理日期：2026-07-08

目录

  1. Claude Code 安装与配置
  2. Codex CLI 安装与使用
  3. Codex Desktop vs Claude Code 对比
  4. Hermes（爱马仕）安装与配置
  5. Hermes 微信与飞书接入
  6. OpenClaw 安装与配置
  7. API Key 与模型服务商

1. Claude Code 安装与配置

方式1：脚本安装（推荐 ）

Windows PowerShell 安装

步骤1：打开PowerShell

  • 按 Win 键
  • 输入 PowerShell
  • 按 Ctrl + Shift + Enter（以管理员身份运行）

步骤2：执行安装命令

irm https://claude.ai/install.ps1 | iex

macOS / Linux / WSL 安装

打开终端，复制粘贴以下命令：

curl -fsSL https://claude.ai/install.sh | bash

一行命令解释：

部分 作用
curl -fsSL 下载安装脚本（-f失败继续，-s静默，-S显示错误，-L跟随重定向）
https://claude.ai/install.sh Anthropic官方安装脚本地址
| bash

安装过程：

[终端显示]
Downloading Claude Code...
Installing to /home/你的用户名/.local/bin/claude
✓ Installation complete!
✓ Added to PATH

Run 'claude --version' to verify.

验证安装：

claude --version
# 预期输出：Claude Code v2.1.x (native)

方式2：NPM安装（标准兼容路径）

前提条件：需要先安装 Node.js 18 或更高版本。

# 检查 Node.js 版本（需要 18+）
node --version

# 通过 NPM 全局安装 Claude Code
npm install -g @anthropic-ai/claude-code

各平台安装细节：

Windows（CMD 或 PowerShell）：

# 直接全局安装
npm install -g @anthropic-ai/claude-code

# 验证
claude --version
# 预期输出：Claude Code v2.1.x (npm)  ← 注意这里显示 npm 而非 native

macOS/Linux：

# 全局安装（不要用 sudo！）
npm install -g @anthropic-ai/claude-code

# 如果提示权限错误，修复 npm 全局目录权限
mkdir -p ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.zshrc
source ~/.zshrc

# 然后重新安装
npm install -g @anthropic-ai/claude-code

配置 PATH 环境变量（Windows 必读）

💡 为什么需要配置 PATH？ Claude Code 通过 PowerShell 脚本安装后，可执行文件位于 C:\Users\你的用户名\.local\bin\，但该目录可能不在系统的 PATH 环境变量中。不配置 PATH，终端就找不到 claude 命令，会报 'claude' 不是内部或外部命令 的错误。

方法1：PowerShell 命令配置（推荐）

# 将 Claude Code 安装目录添加到用户 PATH 环境变量
[System.Environment]::SetEnvironmentVariable(
    'Path',
    [System.Environment]::GetEnvironmentVariable('Path', 'User') + ';' + "$env:USERPROFILE\.local\bin",
    'User'
)

⚠️ 配置完成后，必须重启 PowerShell / CMD 窗口才能生效！

验证 PATH 是否配置成功：

# 重启终端后执行
claude --version
# 如果显示版本号（如 Claude Code v2.1.x (native)），说明配置成功

方法2：通过系统设置（图形界面）

  1. 按下 Win + R 打开”运行”对话框
  2. 输入 sysdm.cpl，按回车，打开”系统属性”
  3. 点击 “高级” 选项卡
  4. 点击底部的 “环境变量” 按钮
  5. 在 “用户变量” 区域找到 Path，双击编辑
  6. 点击 “新建”，添加：%USERPROFILE%\.local\bin
  7. 点击 “确定” 保存所有对话框
  8. 重启所有终端窗口

macOS / Linux 用户

脚本安装通常会自动将 ~/.local/bin 添加到 PATH。如果安装后 claude 命令不可用，手动添加：

# 添加到 shell 配置文件（zsh 用户）
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

# bash 用户
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

验证安装成功

无论用哪种方式，安装完成后验证：

# 检查版本
claude --version
# 预期输出：Claude Code v2.1.x (native)

# 检查帮助
claude --help
# 应该显示完整帮助信息

# 检查安装位置
where claude     # Windows
which claude     # macOS/Linux

成功的标志：

  • ✅ 显示版本号（带 native 标识）
  • ✅ 命令可以直接运行（不提示找不到命令）
  • ✅ --help 能显示帮助信息

API Key 配置问题

问题：环境变量未生效

echo $ANTHROPIC_API_KEY
# 显示为空

解决方案：

# macOS/Linux：确认配置文件
cat ~/.zshrc | grep ANTHROPIC
# 应该看到：export ANTHROPIC_API_KEY="sk-ant-..."

# 如果没有，手动添加
echo 'export ANTHROPIC_API_KEY="你的key"' >> ~/.zshrc
source ~/.zshrc

Windows：

# 检查是否配置
[System.Environment]::GetEnvironmentVariable('ANTHROPIC_API_KEY', 'User')

# 如果为空，重新配置
[System.Environment]::SetEnvironmentVariable('ANTHROPIC_API_KEY', 'sk-ant-api03-你的key', 'User')

# 重启PowerShell

问题：Key无效或过期

{
  "error": {
    "type": "authentication_error",
    "message": "invalid x-api-key"
  }
}

解决方法：

  1. 登录 console.anthropic.com
  2. Settings → API Keys
  3. 检查Key是否被删除或禁用
  4. 如果无效，创建新Key
  5. 更新环境变量

问题3：Key格式错误

症状：Key看起来不完整或有空格

正确格式检查（PowerShell 7）：

# Key应该满足：
# 1. 以"sk-ant-api03-"开头
# 2. 后面跟长串字母数字
# 3. 总长度约95字符
# 4. 无空格、无换行

# 验证长度
$env:ANTHROPIC_API_KEY.Length
# 应该输出：95左右

# 验证格式
$env:ANTHROPIC_API_KEY -match '^sk-ant-api03-[A-Za-z0-9_-]+$'
# 应该输出：True

常见格式错误：

❌ sk-ant-XXXXX （缺少api03）
❌ sk-XXXXX （缺少ant-api03）
❌ 有空格或换行符
❌ 复制时多复制/少复制字符

常见报错

安装与配置类

Q1：运行 code --version 报错说找不到命令？

A1：你可能在Cursor里运行的！

  • code 是 VS Code 的命令
  • cursor 是 Cursor 的命令

正确做法：

  • 在Cursor里运行：cursor --version
  • 在VS Code里运行：code --version
  • 查看Claude Code版本：claude --version

Q2：找不到settings.json文件在哪儿？

A2：不同编辑器位置不同！

Cursor位置：

  • Windows: C:\Users\你的用户名\AppData\Roaming\Cursor\User\settings.json
  • Mac: ~/Library/Application Support/Cursor/User/settings.json

VS Code位置：

  • Windows: C:\Users\你的用户名\AppData\Roaming\Code\User\settings.json
  • Mac: ~/Library/Application Support/Code/User/settings.json

快速打开方法：

  1. 按 Ctrl/Cmd + Shift + P
  2. 输入：open user settings json
  3. 选择：Preferences: Open User Settings (JSON)

Q3：配置后还是报错，怎么办？

A3：按照这个检查清单逐项排查：

□ settings.json文件保存了吗？（看文件名有没有*号）
□ JSON格式正确吗？（大括号、逗号、引号都对吗）
□ 重启了终端吗？（配置需要重启终端才生效）
□ 重启了编辑器吗？（有时需要完全重启）

还是不行？ 把错误信息截图，群里问老金！

Q4：zsh、PowerShell、bash 有什么区别？我该用哪个？

A4：它们都是Shell（命令行翻译器），选对应你系统的就行！

操作系统 推荐Shell 为什么
Windows PowerShell 系统自带，功能强大
Mac zsh 2019年后的系统默认
Linux bash 通用标准

网络与性能类

Q5：Claude Code响应很慢，怎么优化？

A5：检查网络和上下文大小！

网络检查：

# 测试到Anthropic的延迟
ping api.anthropic.com
# 延迟<500ms = 正常，>1000ms = 慢

优化方法：

  1. ✅ 使用代理（国内用户必需）
  2. ✅ 减少上下文（不要让AI读太多文件）
  3. ✅ 使用 .claudeignore 排除无关文件

Q6：国内网络访问Anthropic API很慢？

A6：配置代理！

临时代理（当前终端生效）：

# macOS/Linux
export HTTPS_PROXY=http://127.0.0.1:7890

# Windows PowerShell
$env:HTTPS_PROXY="http://127.0.0.1:7890"

永久代理（推荐）： 在 ~/.zshrc 或 ~/.bashrc 添加：

export HTTPS_PROXY=http://127.0.0.1:7890
export HTTP_PROXY=http://127.0.0.1:7890

错误信息类

Q7：启动时报错 claude: command not found？

A7：Claude Code没安装或PATH未配置！

解决步骤：

  1. 检查是否安装：

    claude --version

  2. 如果提示命令找不到：

    macOS/Linux:

    # 检查安装位置
ls ~/.local/bin/claude

# 如果存在，添加到PATH
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

    Windows:

    # 检查安装位置
Test-Path "$env:USERPROFILE\.local\bin\claude.exe"

# 如果返回 True，手动添加到 PATH
# 系统设置 → 环境变量 → 用户变量的 Path → 添加：
# %USERPROFILE%\.local\bin

  3. 如果确实没安装：

    macOS/Linux:

    curl -fsSL https://claude.ai/install.sh | bash

    Windows:

    irm https://claude.ai/install.ps1 | iex

Q8：启动时报错 API key not found？

A8：没配置ANTHROPIC_API_KEY环境变量！

快速检查：

# 查看环境变量是否存在
echo $ANTHROPIC_API_KEY  # macOS/Linux
echo $env:ANTHROPIC_API_KEY  # Windows

如果显示空 → 没配置，回到第四部分重新配置。

Q9：我之前用npm安装过Claude Code，怎么办？

A9：官方提供了迁移命令！

# 一键迁移到原生版本
claude install

这个命令会：

  1. 下载并安装原生版本
  2. 保留你的所有配置
  3. 自动卸载旧的npm版本

验证迁移成功：

claude --version
# 应显示：Claude Code v2.1.x (native)
# 而不是：(npm)

如果迁移失败，手动卸载npm版本：

npm uninstall -g @anthropic-ai/claude-code
# 然后重新运行原生安装

2. Codex CLI 安装与使用

任务15：Codex CLI——OpenAI的智能体助手

  • 目标：安装并体验OpenAI的Codex CLI。

  • 要求：

    1. 完成Codex CLI的安装和ChatGPT账号登录

    2. 验证任务：用自然语言下达任务，例如：

      1. “分析当前目录下所有Python文件的代码复杂度，生成报告”
      2. “帮我写一个单元测试，覆盖这个文件里所有函数”

    3. 对比Codex与Claude Code在相同任务上的表现差异

      Codex Desktop vs Claude Code 对比表

      对比维度 Codex Desktop Claude Code + NVIDIA NIM
      任务1：复杂度分析 Plan Mode先行，一次性输出完整Markdown表格+重构建议 直接输出文字摘要，需追问才补充详细数据
      任务2：单元测试生成 100%函数覆盖（含异常/Mock），自动保存文件，主动询问是否运行 50-60%覆盖（以正常路径为主），需手动保存
      输出质量 结构化、完整、可直接使用 需多轮对话完善
      主动辅助 主动给建议、问下一步 需用户主导引导
      自动化程度 自动保存、自动生成报告 需手动操作
      单次任务完成度 一次性完成 需多次对话达到同等效果
      执行速度 较慢 较快
      适用场景 生成报告/文档/完整测试套件 日常编码问答、快速探索
      费用 按量付费（中转站） 完全免费（NVIDIA NIM）
      上下文窗口 ~200K 1M

    Codex Desktop = 一次到位产出完整成果，适合生成报告和测试 Claude Code = 快速响应渐进细化，适合日常编码和深度理解

    两者互补使用效率最高

    基于 Codex Desktop + 中转站 + cc-switch 的实践记录

    一、为什么选择 Codex Desktop？

    由于国内直接访问 ChatGPT 官方服务比较困难（网络限制、支付门槛等），我采用了 中转站（API Proxy）+ cc-switch 的方式接入 Codex 能力。

    实际使用的是 Codex Desktop App 的 API 模式，而非原生 ChatGPT 登录方式。

    选型理由：

    组件 选择 原因
    客户端 Codex Desktop（macOS/Windows） 图形界面友好、支持多Agent并行、有Browser Use能力
    认证方式 OpenAI API Key（通过中转站获取） 避免ChatGPT账号的网络限制和支付门槛
    代理工具 cc-switch 国内中转站，自动切换可用节点，降低延迟

    二、安装与配置

    2.1 安装 Codex Desktop

    下载地址：

    • macOS：从 OpenAI 官网 下载 .dmg 安装包

    • Windows：可以通过微软商店安装

      • 系统要求：

        Windows 10 19041 以上，需联网

    • Linux：目前官方未提供，需使用 CLI 版本

    2.2 配置中转站 + cc-switch

    下载cc-switchRelease CC Switch v3.16.5 · farion1231/cc-switch · GitHub

    我用的中转站是https://www.right.codes/

    点击令牌管理 ——> 创建密钥 ——> 创建完成后点击导入，选择cc-switch

    选择codex

    它会自动跳转到cc-switch，点击导入，然后使用它，重启客户端

    再打开Codex Desktop，会自动登录，就可以开始使用了

    Codex++ Agnes 模型配置指南

    1. 概述

    本指南说明如何在 Codex++ 中配置 Agnes 模型。配置完成后，你可以直接在 Codex++ 中使用 Agnes 模型进行聊天、代码生成和 Agent 任务，无需登录 GPT 账户。

    2. 前置条件

    在开始之前，请确保你已具备：

    1. 一个 Agnes API Key。
    2. 能够访问 Agnes API 网关的网络连接。
    3. 目标模型名称。
    4. 已下载或准备安装 Codex++。

    推荐模型：agnes-2.0-flashAPI Base URL：https://apihub.agnes-ai.com/v1

    3. 下载 Codex++

    打开 Codex++ 下载页面：https://github.com/BigPizzaV3/CodexPlusPlus你也可以直接打开最新发布页面：https://github.com/BigPizzaV3/CodexPlusPlus/releases/latest下载与你的设备匹配的版本：

    设备类型 下载文件
    Windows windows-x64-setup.exe
    Intel 芯片 Mac macos-x64.dmg
    Apple 芯片 Mac macos-arm64.dmg

    如果你不确定你的 Mac 使用的是 Intel 芯片还是 Apple 芯片，点击左上角的 Apple 图标并选择 关于本机。

    4. 安装 Codex++

    5. 打开 Codex++ 管理工具

    6. 添加 Agnes 提供商

    填写以下字段：

    字段 值
    名称 Agnes
    访问模式 API Only
    测试模型 agnes-2.0-flash
    Base URL https://apihub.agnes-ai.com/v1
    Key 输入你的 Agnes API Key
    上游协议 Chat Completions

    7. 配置注意事项

    请仔细检查以下内容：

    1. 只输入以 sk- 开头的 API 密钥。不要包含 Bearer。
    2. Base URL 应以 /v1 结尾。不要输入 /chat/completions。
    3. 上游协议必须为 Chat Completions。
    4. 模型名称应为：
    agnes-2.0-flash
    1. 完成配置后，点击：
    Save

    8. 启用 Agnes 提供商

    保存配置后，返回提供商列表并选择：

    Agnes

    如果你看到以下任一按钮，点击它以启用 Agnes 提供商：

    Use
In Use
Switch to This Provider

    成功启用后，Agnes 将成为当前活动的提供商。

    9. 启动 Codex++

    返回左侧边栏，点击：

    Overview

    然后点击：

    Start Codex++

    你也可以点击右上角的按钮：

    Restart Codex

    启动后，你可以正常使用 Codex++，请求将通过 Agnes 模型路由。

    10. 验证配置

    打开 Codex++ 并创建一个新会话。输入一个简单的测试消息，例如：

    你好，请介绍一下你自己。

    如果 Codex++ 正常响应，Agnes 模型配置成功。

    11. 常见问题

    1. Codex 无法正常响应怎么办？

    请检查以下内容：

    • 确保你是从 Codex++ 或 Codex++ 管理工具 启动 Codex，而不是打开原始的 Codex。
    • 确保 Base URL 为：
    https://apihub.agnes-ai.com/v1
    • 确保 Key 只包含以 sk- 开头的 API 密钥。
    • 确保上游协议为：
    Chat Completions
    • 确保模型为：
    agnes-2.0-flash
    • 确保保存配置后已启用 Agnes 提供商。

    2. 我应该如何输入 API Key？

    只输入 Agnes API Key 本身，例如：

    sk-xxxxxxxxxxxxxxxx

    不要输入：

    Bearer sk-xxxxxxxxxxxxxxxx

    3. 我应该如何输入 Base URL？

    正确：https://apihub.agnes-ai.com/v1错误：https://apihub.agnes-ai.com/v1/chat/completions

    4. 我需要登录 GPT 账户吗？

    不需要。配置完成后，你可以直接使用 Agnes 模型使用 Codex++。

    12. 推荐配置摘要

    提供商名称： Agnes模式： API Only模型： agnes-2.0-flashBase URL： https://apihub.agnes-ai.com/v1API Key： YOUR_AGNES_API_KEY协议： Chat Completions

    13. 完整设置摘要

    1. 下载并安装 Codex++。
    2. 打开 Codex++ 管理工具。
    3. 进入 Provider Configuration。
    4. 添加 Agnes 提供商。
    5. 输入模型、Base URL、API Key 和上游协议。
    6. 保存配置。
    7. 启用 Agnes 提供商。
    8. 启动或重启 Codex++。
    9. 创建新会话以测试 Codex++ 是否正常响应。

    10. 配置完成后，你可以在 Codex++ 中使用 Agnes 模型。

3. Hermes（爱马仕）安装与配置

本教程将指导你在 Windows 系统中通过 WSL2 + Ubuntu 环境安装并配置「爱马仕」。

第一步：开启并配置 WSL2

  1. 以管理员身份运行 PowerShell，输入以下命令开启 WSL 和虚拟机平台功能：

    dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart
dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart

  2. 下载并安装 WSL2 Linux 内核更新包。

  3. 将 WSL 默认版本设置为 2：

    wsl --set-default-version 2

💡 执行完以上步骤后，建议重启电脑，确保功能生效。

第二步：安装 Ubuntu 并配置环境

  1. 在 Microsoft Store 中搜索并安装 Ubuntu（推荐 22.04 或 24.04 LTS 版本）。

  2. 安装完成后首次打开，会自动弹出终端，请按提示设置你的专属 Linux 用户名和密码。

  3. 在 Ubuntu 终端中更新软件包列表并安装 Git：

    sudo apt update && sudo apt upgrade -y
sudo apt install -y git

第三步：一键安装爱马仕

  1. 在 Ubuntu 终端内运行以下一键部署脚本：

    # 一键安装 Hermes（爱马仕）
bash <(curl -sSL <替换为完整的脚本地址>)

    ⚠️ 注意：请将 <替换为完整的脚本地址> 替换成实际可用的完整下载链接，否则命令无法正常执行。

  2. 首次启动时，系统会提示输入大模型 API Key（如 OpenAI、DeepSeek 或 OpenRouter 等）。

    • 输入正确的 Key 后即可完成初始化；
    • 如果暂时没有 Key，可以先跳过，之后再补充配置。

    完成初始化后，可以选择将爱马仕接入到不同的使用场景中：

  3. 也可以直接在终端（黑窗口）内与爱马仕对话，前提是已配置好 API Key：

配置 API Key

API Key 可以从各大模型服务商处获取，既有免费额度，也可以付费购买，常见选择包括：

  • 免费：Agnes AI、智谱 等
  • 付费：OpenAI、DeepSeek、OpenRouter 等

以 Agnes AI 为例

  1. 注册账号后，进入控制台创建新密钥。

  2. 为密钥填写一个名称，即可生成对应的 API Key。

    💡 提示：免费额度对应的 API Key 响应速度通常较慢，如果对速度有较高要求，建议考虑付费方案。

​

小结

整体流程为：开启 WSL2 → 安装 Ubuntu → 一键部署爱马仕 → 配置 API Key → 开始使用。首次配置时如遇到 API Key 相关问题，可以先跳过初始化步骤，后续随时补充配置即可。

4. Hermes 微信与飞书接入

记录日期：2026-07-07 基于 Hermes Agent 的多平台消息网关配置

一、环境概况

  • 操作系统：Linux (6.1.0-40-amd64)
  • Hermes 版本：0.18.0
  • 模型：agnes-2.0-flash
  • Provider：custom (apihub.agnes-ai.com)
  • Gateway 运行方式：systemd 用户服务（hermes-gateway.service）
  • Linger：已启用（SSH 断开后服务仍持续运行）

二、微信（Weixin）接入

2.1 接入方式

选择 Weixin（个人微信），通过 Baileys 协议桥接，而非企业微信（WeCom）。

2.2 配置步骤

  1. 运行网关配置向导

    hermes gateway setup

    在交互式菜单中选择 Weixin / WeChat 平台进行配置。

  2. 扫码登录

    网关会输出一个二维码，用手机微信扫描完成登录。

  3. 安装 Gateway 为后台服务

    hermes gateway install
hermes gateway start

  4. 启用 Linger（防止 SSH 断开后服务停止）

    sudo loginctl enable-linger $USER

2.3 配置文件

~/.hermes/.env 中写入的微信相关变量：

WEIXIN_ACCOUNT_ID=805e47d2138b@im.bot
WEIXIN_TOKEN=805e47d2138b@im.bot:060000d3df84179398a66cd5268e03c75cce9c
WEIXIN_BASE_URL=https://ilinkai.weixin.qq.com
WEIXIN_CDN_BASE_URL=https://novac2c.cdn.weixin.qq.com/c2c

~/.hermes/config.yaml 中无独立的 weixin 区块配置，全部通过 .env 管理。

2.4 用户审批（Pairing）

微信默认采用配对审批机制。新用户首次发送消息时会生成配对码，管理员需审批后才能通信。

# 查看待审批列表
hermes pairing list

# 审批配对码（格式：hermes pairing approve <platform> <code>）
hermes pairing approve weixin <配对码>

当前已批准的用户： - User ID：o9cq8036BWZYIbOfCLsvic_ErTGg@im.wechat

如需允许所有用户免审批直接通信，可在 .env 中添加：

GATEWAY_ALLOW_ALL_USERS=true

或在 config.yaml 的 weixin 部分设置 dm_policy: open。

2.5 连接状态

Gateway 日志确认连接成功：

2026-07-06 15:50:05,332 INFO gateway.platforms.weixin: [Weixin] Connected account=805e47d2 base=https://ilinkai.weixin.qq.com
2026-07-06 15:50:05,338 INFO gateway.run: ✓ weixin connected

三、飞书（Feishu）接入

3.1 接入方式

通过 Hermes 内置的 Feishu 插件接入，使用 WebSocket 模式连接飞书中国版（域名 feishu）。

3.2 飞书开放平台配置

在 飞书开放平台 后台完成以下配置：

  1. 创建或选择已有应用
  2. 记录 App ID 和 App Secret
  3. 进入 事件与回调 → 事件订阅
  4. 添加事件：im.message.receive_v1（接收消息）
    • 此步骤至关重要，缺少该事件订阅则机器人无法接收消息
  5. 配置验证 Token（Verification Token）— 用于 HMAC 签名校验
  6. 确保应用已发布上线（开发阶段仅限创建者/管理员使用）

3.3 配置文件

~/.hermes/.env 中写入的飞书相关变量：

FEISHU_APP_ID=cli_aac1d51fa2781be3
FEISHU_APP_SECRET=kppeoDqzqsjlZoQUiU97revcUSSMlP8F

~/.hermes/config.yaml 中的配置：

gateway:
  feishu:
    app_id: cli_aac1d51fa2781be3
    app_secret: kppeoDqzqsjlZoQUiU97revcUSSMlP8F
    enabled: true

plugins:
  enabled:
    - platforms/feishu
  disabled: []

3.4 连接状态

Gateway 日志确认连接成功：

2026-07-06 17:28:08,944 INFO gateway.run: Connecting to feishu...
2026-07-06 17:28:09,450 INFO hermes_plugins.feishu_platform.adapter: [Feishu] Connected in websocket mode (feishu)
2026-07-06 17:28:09,459 INFO gateway.run: ✓ feishu connected

3.5 已知问题

机器人收不到用户消息：

  • 现象：WebSocket 连接成功（日志显示 [Feishu] Connected in websocket mode），但用户发消息后机器人无反应

  • 排查步骤：

    1. 检查 Gateway 日志中是否有 [Feishu] dropping inbound event（DEBUG 级别），有则说明消息到达了但被拒绝
    2. 检查飞书开放平台 事件订阅 是否已添加 im.message.receive_v1 事件
    3. 检查飞书开放平台 权限管理 是否已开启以下权限：
      • im:message:readonly — 读取用户发给机器人的单聊消息
      • 群组中@机器人时接收消息 — 允许在群聊中通过 @提及 触发机器人
    4. 确认应用已发布上线，且你的飞书账号在应用的 可用范围 内
    5. 确认事件接收方式为 长连接（WebSocket），而非 HTTP 回调

  • 原因：没有开启这获取用户发给机器人单条消息和获取群组中用户@机器人消息权限权限

  • 解决：开启上述权限后重新发布应用，Gateway 无需重启即可生效

3.6 Home Channel

首次使用时会收到提示：

No home channel is set for Feishu. A home channel is where Hermes delivers cron job results and cross-platform messages.

解决方法：在飞书聊天中输入 /sethome 将该对话设为主频道，用于接收 Cron 任务结果和跨平台消息。

四、Gateway 服务管理

4.1 常用命令

# 查看状态
hermes gateway status

# 启动 / 停止 / 重启
hermes gateway start
hermes gateway stop
hermes gateway restart

# 查看日志
tail -f ~/.hermes/logs/gateway.log

# 查看特定平台日志
grep -i "feishu\|weixin" ~/.hermes/logs/gateway.log | tail -20

4.2 系统服务信息

● hermes-gateway.service - Hermes Agent Gateway - Messaging Platform Integration
   Loaded: loaded (/root/.config/systemd/user/hermes-gateway.service; enabled)
   Active: active (running)
   Main PID: 3352381 (hermes)

4.3 双平台同时运行

重启后 Gateway 日志显示同时运行两个平台：

2026-07-06 17:28:09,568 INFO gateway.run: Gateway running with 2 platform(s)

五、关键文件路径

文件 用途
~/.hermes/config.yaml 主配置文件（模型、网关、插件等）
~/.hermes/.env 环境变量（API Key、平台凭证）
~/.hermes/logs/gateway.log Gateway 运行日志
~/.hermes/auth.json OAuth 令牌和凭证池
/root/.config/systemd/user/hermes-gateway.service systemd 服务单元文件

六、注意事项

  1. 微信（Weixin） 使用 Baileys 协议，存在一定封号风险，建议谨慎使用
  2. 飞书 必须配置事件订阅 im.message.receive_v1，否则机器人收不到消息
  3. Gateway 服务依赖 systemd linger，确保已执行 sudo loginctl enable-linger $USER
  4. 配对码有过期时间，如审批失败请让用户重新生成
  5. 修改 .env 或 config.yaml 后需重启 Gateway 生效：hermes gateway restart

5. OpenClaw 安装与配置

一、前期准备工作

  1. 安装Node.js，去官网下载最新LTS版本（要求22以上）
  2. 打开终端（CMD或PowerShell都行），验证一下安装有没有成功：
node --version

二、安装OpenClaw（终端操作）

执行下面的命令全局安装：npm install -g openclaw@latest

装完后看一眼版本：openclaw --version

三、初始化配置

先跑这个命令生成基础配置文件：openclaw setup

然后执行配置向导：openclaw onboard --install-daemon

遇到的坑： 在选模型提供商那一步，我一开始没想好要用哪个，就选了”Skip for now”跳过了。结果后面启动服务的时候报错说缺少配置，不让启动。

怎么解决的： 后来我重新运行了 openclaw configure，进去之后选”Model”，然后从列表里找到DeepSeek，选上，填API Key就行了。

选DeepSeek：PowerShell执行安装脚本的时候报错 基础连接已关闭: 接收时发生错误，连不上服务器。Ollama官网下载安装包速度慢。DeepSeek是国内直连，不需要翻墙，注册送一些免费额度，对国内用户比较友好

四、启动网关，遇到一堆报错

第一次尝试启动：

openclaw gateway --port 18789

报错1： Missing config. Run openclaw setup

  • 原因：之前 onboard 的时候把模型配置跳过了，配置文件不完整，网关不认。
  • 解决：执行 openclaw setup 重新生成配置，然后再跑 openclaw configure 把DeepSeek配好。

报错2： gateway.auth: Invalid input

  • 原因：我在配置文件里手动加了 "auth": false 想绕过认证，但OpenClaw不认这个写法，格式不对直接启动失败。
  • 解决：执行 openclaw doctor --fix 自动修复，然后重新启动。

报错3： 浏览器访问 http://127.0.0.1:18789，提示 token missing，连不上

  • 原因：网关默认需要认证令牌，我没配置，浏览器根本连不上WebSocket。
  • 解决：终端执行 openclaw doctor --generate-gateway-token 生成令牌。但这个命令有个坑——它生成完之后不直接在终端显示令牌，需要在配置文件里自己找。我用 findstr token C:\Users\Lenovo\.openclaw\openclaw.json 才把令牌翻出来。

五、拿到令牌，终于连上了

从配置文件里找到的令牌是：

4011c22ae3656ccf64b37ef3b4070b0356444f277df687b1

把它复制到浏览器登录界面的”网关令牌”输入框里，点Connect，就进去了。

至此网关才算真正跑起来，终端日志里能看到 [gateway] ready 和 [heartbeat] started，说明服务正常。

六、目前还存在的问题

进是进去了，但发消息测试的时候发现DeepSeek返回了一个计费错误，意思是我API Key的额度用完了或者余额不足。这个暂时还没处理，后面要么充值，要么换个有免费额度的服务商（比如Groq）重新配一下。

6. API Key 与模型服务商

类型 服务商 特点
免费 Agnes AI、智谱 有免费额度，响应速度可能较慢
付费 OpenAI、DeepSeek、OpenRouter 速度快，需付费
国内直连 DeepSeek 不需要翻墙，注册送额度
免费替代 Groq 有免费额度

各工具支持的模型

工具 支持模型
Claude Code Anthropic Claude 系列
Codex / Codex++ GPT 系列、Agnes (agnes-2.0-flash)
Hermes Agnes、OpenAI、DeepSeek、OpenRouter 等
OpenClaw DeepSeek、Groq 等

本文档由实训素材整合而成，所有图片已内嵌为本地路径，在任何环境下均可直接显示，适合用于 PPT 生成。