X API + Hermes via xurl skill 完整配置指南

✍ Developers🕐 2026-05-20📦 10.5 KB 🟢 已读 𝕏 文章列表

本文详细介绍如何将开源 AI Agent Hermes 与 X API 结合使用。通过安装 xurl 技能，用户可以在终端通过自然语言控制 X 账号，实现发帖、搜索、管理书签、回复等操作。文章涵盖了从安装 Hermes、配置 xAI Grok 模型、安装 xurl CLI 到完成 OAuth 认证的全过程。

Hermes AI Agent X API xurl Grok OAuth 终端工具自动化设置教程

# X API + Hermes via xurl skill **作者**: Developers **日期**: 2026-05-19T22:55:02.000Z **来源**: [https://x.com/XDevelopers/status/2056871280599847054](https://x.com/XDevelopers/status/2056871280599847054) --- ![Image](/doc/2111/image/img_4988b83f1438.jpg) Hermes is an open-source AI agent from Nous Research that runs in your terminal. Out of the box it comes with a skill called xurl that lets the agent read and write to X on your behalf — posting, searching, pulling bookmarks, managing lists, and more — all through natural language. This guide walks through the full setup: installing Hermes, connecting it to a model provider, installing xurl, authenticating with the X API, and using the two together. ## Prerequisites - macOS or Linux - A terminal (iTerm2, Ghostty, the default Terminal app, etc.) - An active SuperGrok subscription (sign up at x.ai/grok) - (Optional fallback) An xAI API key only if you encounter tier restrictions on OAuth - An X developer app with OAuth 2.0 credentials (console.x.com) ## 1. Install Hermes Run the one-line installer: ``` curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash ``` This downloads the Hermes binary and places it on your PATH. Once it finishes, run hermes to confirm it installed correctly and start the setup wizard. ## 2. Run the Setup Wizard On first launch Hermes walks you through configuration. You can re-run this at any time with hermes setup. Choose a setup mode ``` How would you like to set up Hermes? → (●) Quick setup — provider, model & messaging (recommended) (○) Full setup — configure everything ``` Quick setup is the fastest path. It covers the three things you need: a model provider, a default model, and an optional messaging integration (Telegram, Discord, etc.). Pick this unless you want to tune every setting up front. Select a provider Hermes supports a long list of inference providers. For this guide we'll use xAI to run Grok models. Select the xAI Grok OAuth option. ``` Select provider: (○) OpenRouter (100+ models, pay-per-use) ... → (●) **xAI Grok OAuth (SuperGrok Subscription)** (○) xAI (direct API key – legacy) ... ``` When you select xAI Grok OAuth, Hermes automatically opens your browser to https://accounts.x.ai. - Sign in with the X account tied to your SuperGrok subscription. - Approve the requested permissions. Hermes receives the tokens via a local callback and stores them in ~/.hermes/auth.json (tokens auto-refresh in the background). Pick a default model Hermes fetches the available models from the provider and presents them: ``` Select default model: -> grok-4.3 ... ``` Pick whichever model you prefer. You can change this later with hermes setup model. Messaging (optional) ``` Connect a messaging platform? (Telegram, Discord, etc.) (○) Set up messaging now (recommended) → (●) Skip — set up later with 'hermes setup gateway' ``` If you want Hermes available as a Telegram or Discord bot, set that up now. Otherwise skip it — you can always come back with hermes setup gateway. Done After the wizard finishes you'll see a summary: ``` ✓ Setup complete! You're ready to go. Configure all settings: hermes setup Connect Telegram/Discord: hermes setup gateway Switch model/provider: hermes model ``` Along with a tool availability report showing which tool categories are active and which need additional API keys. ## 3. Install xurl xurl is a standalone CLI for the X API. Hermes uses it under the hood when you invoke the xurl skill. Install it with whichever method works for your system: Shell script (no sudo, installs to ~/.local/bin): ``` curl -fsSL https://raw.githubusercontent.com/xdevplatform/xurl/main/install.sh | bash ``` Homebrew (macOS): ``` brew install --cask xdevplatform/tap/xurl ``` npm (requires Node.js): ``` npm install -g @xdevplatform/xurl ``` Go (requires Go): ``` go install github.com/xdevplatform/xurl@latest ``` If you used the shell script, you may need to add ~/.local/bin to your PATH: ``` echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc source ~/.zshrc ``` Verify it's installed: ``` xurl --help ``` ## 4. Authenticate xurl with the X API xurl needs OAuth 2.0 credentials from an X developer app. Do this setup in your terminal directly — not inside Hermes. Create an X developer app 1. Go to developer.x.com/en/portal/dashboard 2. Create a new app (or use an existing one) 3. Under User authentication settings, set the redirect URI to: http://localhost:8080/callback 4. Copy the Client ID and Client Secret Register the app with xurl ``` xurl auth apps add my-app \ --client-id YOUR_CLIENT_ID \ --client-secret YOUR_CLIENT_SECRET ``` Authenticate via OAuth ``` xurl auth oauth2 --app my-app ``` This opens your browser for the OAuth flow. Authorize the app with your X account. Important: Keep the --app my-app flag. If you skip --app, the token may be saved to the default profile instead of the app that holds your client credentials, causing later API calls to fail with 401 errors. Current xurl releases warn you when they detect this and suggest the exact --app flag to use. Once you've authenticated, if you need to link a specific username: ``` xurl auth oauth2 --app my-app YOUR_USERNAME ``` Set the default app and verify ``` xurl auth default my-app xurl auth status xurl whoami ``` xurl whoami should print your X username and confirm everything is wired up. ## 5. Launch Hermes Start a chat session: ``` hermes ``` If Hermes offers to launch after setup, type Y. Otherwise just run hermes from any terminal. Once inside, type /help to see available commands. You'll notice /xurl in the list — that's the skill we want. ## 6. Use the xurl Skill Type /xurl in the Hermes chat to load the skill. Hermes will verify that xurl is installed and authenticated. From here, just tell Hermes what you want to do in plain English. It translates your requests into xurl commands, runs them, and presents the results. Post to X ``` post "Hello from Hermes" ``` Hermes runs xurl post "Hello from Hermes" and returns the post ID and link: ``` Posted successfully! Your new post: - ID: 2047107136023650625 - Text: "Hello from Hermes" - Link: https://x.com/yourhandle/status/2047107136023650625 ``` Get your bookmarks ``` get all of my bookmarks ``` Hermes runs xurl bookmarks -n 100 and gives you a summarized, readable list of your bookmarked posts — with metrics, media types, and usernames — instead of raw JSON. Other things you can do The xurl skill gives Hermes access to the full X API surface. Some examples: - Search posts: "search for posts about Hermes AI" - Get a user's profile: "look up @elonmusk" - Reply to a post: "reply to post 2047107136023650625 with 'great thread'" - Quote a post: "quote post 2047107136023650625 with my thoughts" - Like / unlike: "like post 2047107136023650625" - Manage bookmarks: "unbookmark 2047107136023650625" - Get your timeline: "show my latest timeline" - Post with media: "post this image with the caption 'sunset'" Because Hermes is an agent, you can also chain actions together conversationally. Ask it to search for posts about a topic, summarize them, and then draft a reply — all in one go. ## Configuration Reference All Hermes config lives under ~/.hermes/: - config.yaml: Main settings (model, provider, agent behavior) - auth.json: OAuth tokens (xAI Grok OAuth, etc.) — automatically managed - .env: API keys (XAI_API_KEY, etc.) - cron/: Scheduled tasks - sessions/: Chat history - logs/: Logs Useful commands for managing your setup: ``` hermes setup # Re-run the full wizard hermes setup model # Change model/provider hermes setup gateway # Configure messaging (Telegram, Discord) hermes setup tools # Configure tool providers hermes config # View current settings hermes config edit # Open config in your editor hermes doctor # Check for issues hermes model # Change model or switch to xAI Grok OAuth hermes auth add xai-oauth # Manual OAuth login (if needed) hermes auth list # View stored credentials hermes auth logout xai-oauth # Remove OAuth credentials ``` ## Troubleshooting xurl: command not found inside Hermes Make sure xurl is on your PATH. If you installed via the shell script, add ~/.local/bin to your PATH and restart Hermes. OAuth flow doesn't complete Confirm the redirect URI in your X developer app is exactly http://localhost:8080/callback. Make sure nothing else is running on port 8080 when you run xurl auth oauth2 --app my-app. OAuth succeeds, but API calls fail with 401 Make sure you authenticated with the same app that holds your client credentials: ``` xurl auth oauth2 --app my-app xurl auth default my-app ``` Run xurl auth status to confirm which app is active. Current xurl releases warn when you run OAuth without --app and another credentialed app is available. API key has non-ASCII characters This happens when copying from PDFs or rich-text editors. Hermes will warn you and auto-strip the bad characters, but if auth still fails, re-copy the key directly from the provider's dashboard. xurl auth status shows no active session Re-run xurl auth oauth2 --app my-app to re-authenticate, then xurl auth default my-app. ## Summary 1. Install Hermes with the one-line script 2. Run the setup wizard (or hermes model) — select xAI Grok OAuth (SuperGrok Subscription), complete the one-time browser login, choose a model 3. Install xurl separately 4. Authenticate xurl with your X developer app credentials Launch Hermes, load /xurl, and start interacting with X in plain English That's it. You now have an AI agent in your terminal that can read and write to X on your behalf, summarize your timeline, manage bookmarks, and anything else the X API supports — all through conversation. ## 相关链接 - [Developers](https://x.com/XDevelopers) - [@XDevelopers](https://x.com/XDevelopers) - [337K](https://x.com/XDevelopers/status/2056871280599847054/analytics) - [x.ai/grok](http://x.ai/grok) - [console.x.com](https://console.x.com/) - [https://accounts.x.ai](https://accounts.x.ai/) - [developer.x.com/en/portal/dashboard](https://developer.x.com/en/portal/dashboard) - [@elonmusk](https://x.com/@elonmusk) - [Upgrade to Premium](https://x.com/i/premium_sign_up) - [6:55 AM · May 20, 2026](https://x.com/XDevelopers/status/2056871280599847054) - [337.9K Views](https://x.com/XDevelopers/status/2056871280599847054/analytics) - [View quotes](https://x.com/XDevelopers/status/2056871280599847054/quotes) --- *导出时间: 2026/5/20 16:16:19* --- ## 中文翻译 # X API + Hermes 通过 xurl skill 实现 **作者**: Developers **日期**: 2026-05-19T22:55:02.000Z **来源**: [https://x.com/XDevelopers/status/2056871280599847054](https://x.com/XDevelopers/status/2056871280599847054) --- ![Image](/doc/2111/image/img_4988b83f1438.jpg) Hermes 是来自 Nous Research 的开源 AI 代理，运行在你的终端中。它开箱即用，自带一个名为 xurl 的技能，允许代理代表你读写 X（发帖、搜索、拉取书签、管理列表等）—— 所有这些都通过自然语言完成。本指南将介绍完整的设置流程：安装 Hermes、连接到模型提供商、安装 xurl、使用 X API 进行身份验证，以及结合使用这两者。 ## 前置条件 - macOS 或 Linux - 一个终端（iTerm2、Ghostty、默认终端应用等） - 一个有效的 SuperGrok 订阅（在 x.ai/grok 注册） - （可选的备用方案）仅当你在 OAuth 上遇到层级限制时，才需要 xAI API 密钥 - 一个具有 OAuth 2.0 凭证的 X 开发者应用 ## 1. 安装 Hermes 运行单行安装程序： ``` curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash ``` 这将下载 Hermes 二进制文件并将其放置在你的 PATH 中。完成后，运行 hermes 以确认安装正确并启动设置向导。 ## 2. 运行设置向导首次启动时，Hermes 会引导你完成配置。你可以随时通过 hermes setup 重新运行此程序。选择设置模式 ``` How would you like to set up Hermes? → (●) Quick setup — provider, model & messaging (recommended) (○) Full setup — configure everything ``` 快速设置是最快的路径。它涵盖了你需要的三件事：模型提供商、默认模型和可选的消息集成（Telegram、Discord 等）。选择此项，除非你想预先调整每个设置。选择提供商 Hermes 支持大量的推理提供商。在本指南中，我们将使用 xAI 来运行 Grok 模型。选择 xAI Grok OAuth 选项。 ``` Select provider: (○) OpenRouter (100+ models, pay-per-use) ... → (●) **xAI Grok OAuth (SuperGrok Subscription)** (○) xAI (direct API key – legacy) ... ``` 当你选择 xAI Grok OAuth 时，Hermes 会自动在浏览器中打开 https://accounts.x.ai。 - 使用与你的 SuperGrok 订阅关联的 X 账户登录。 - 批准请求的权限。 Hermes 通过本地回调接收令牌，并将其存储在 ~/.hermes/auth.json 中（令牌会在后台自动刷新）。选择默认模型 Hermes 从提供商获取可用模型并展示它们： ``` Select default model: -> grok-4.3 ... ``` 选择你喜欢的任何模型。你可以稍后使用 hermes setup model 进行更改。消息传递（可选） ``` Connect a messaging platform? (Telegram, Discord, etc.) (○) Set up messaging now (recommended) → (●) Skip — set up later with 'hermes setup gateway' ``` 如果你希望 Hermes 作为 Telegram 或 Discord 机器人使用，请立即设置。否则跳过它—— 你随时可以使用 hermes setup gateway 返回设置。完成向导完成后，你将看到一个摘要： ``` ✓ Setup complete! You're ready to go. Configure all settings: hermes setup Connect Telegram/Discord: hermes setup gateway Switch model/provider: hermes model ``` 以及一份工具可用性报告，显示哪些工具类别处于活动状态，哪些需要额外的 API 密钥。 ## 3. 安装 xurl xurl 是用于 X API 的独立 CLI。当你调用 xurl 技能时，Hermes 在底层使用它。使用适用于你系统的任何方法安装它： Shell 脚本（无需 sudo，安装到 ~/.local/bin）： ``` curl -fsSL https://raw.githubusercontent.com/xdevplatform/xurl/main/install.sh | bash ``` Homebrew (macOS)： ``` brew install --cask xdevplatform/tap/xurl ``` npm（需要 Node.js）： ``` npm install -g @xdevplatform/xurl ``` Go（需要 Go）： ``` go install github.com/xdevplatform/xurl@latest ``` 如果你使用了 shell 脚本，可能需要将 ~/.local/bin 添加到你的 PATH 中： ``` echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc source ~/.zshrc ``` 验证已安装： ``` xurl --help ``` ## 4. 使用 X API 对 xurl 进行身份验证 xurl 需要 X 开发者应用的 OAuth 2.0 凭证。请直接在你的终端中进行此设置—— 而不是在 Hermes 内部。创建 X 开发者应用 1. 前往 developer.x.com/en/portal/dashboard 2. 创建一个新应用（或使用现有应用） 3. 在用户身份验证设置下，将重定向 URI 设置为： http://localhost:8080/callback 4. 复制客户端 ID 和客户端密钥使用 xurl 注册应用 ``` xurl auth apps add my-app \ --client-id YOUR_CLIENT_ID \ --client-secret YOUR_CLIENT_SECRET ``` 通过 OAuth 进行身份验证 ``` xurl auth oauth2 --app my-app ``` 这会打开浏览器进行 OAuth 流程。使用你的 X 账户授权该应用。重要提示：保留 --app my-app 标志。如果你跳过 --app，令牌可能会保存到默认配置文件，而不是持有你的客户端凭证的应用，导致后续 API 调用因 401 错误而失败。当前的 xurl 版本会在检测到此情况时发出警告，并建议使用确切的 --app 标志。完成身份验证后，如果需要链接特定的用户名： ``` xurl auth oauth2 --app my-app YOUR_USERNAME ``` 设置默认应用并验证 ``` xurl auth default my-app xurl auth status xurl whoami ``` xurl whoami 应该会打印你的 X 用户名并确认一切已连接。 ## 5. 启动 Hermes 启动聊天会话： ``` hermes ``` 如果 Hermes 提议在设置后启动，请输入 Y。否则只需在任何终端运行 hermes。进入后，输入 /help 查看可用命令。你会注意到列表中有 /xurl —— 这就是我们想要的技能。 ## 6. 使用 xurl 技能在 Hermes 聊天中输入 /xurl 以加载该技能。Hermes 将验证 xurl 是否已安装并经过身份验证。在这里，只需用简单的英语告诉 Hermes 你想做什么。它将你的请求转换为 xurl 命令，运行它们，并展示结果。发布到 X ``` post "Hello from Hermes" ``` Hermes 运行 xurl post "Hello from Hermes" 并返回帖子 ID 和链接： ``` Posted successfully! Your new post: - ID: 2047107136023650625 - Text: "Hello from Hermes" - Link: https://x.com/yourhandle/status/2047107136023650625 ``` 获取你的书签 ``` get all of my bookmarks ``` Hermes 运行 xurl bookmarks -n 100 并为你提供收藏帖子的汇总、可读列表 —— 包含指标、媒体类型和用户名 —— 而不是原始 JSON。你可以做的其他事情 xurl 技能赋予 Hermes 访问完整 X API 的能力。一些示例： - 搜索帖子："search for posts about Hermes AI" - 获取用户资料："look up @elonmusk" - 回复帖子："reply to post 2047107136023650625 with 'great thread'" - 引用帖子："quote post 2047107136023650625 with my thoughts" - 点赞 / 取消点赞："like post 2047107136023650625" - 管理书签："unbookmark 2047107136023650625" - 获取时间线："show my latest timeline" - 发布媒体："post this image with the caption 'sunset'" 因为 Hermes 是一个代理，你还可以在对话中链接一系列操作。让它搜索关于某个主题的帖子，总结它们，然后起草回复 —— 一气呵成。 ## 配置参考所有 Hermes 配置都位于 ~/.hermes/ 下： - config.yaml：主设置（模型、提供商、代理行为） - auth.json：OAuth 令牌（xAI Grok OAuth 等）—— 自动管理 - .env：API 密钥（XAI_API_KEY 等） - cron/：计划任务 - sessions/：聊天历史 - logs/：日志用于管理设置的有用命令： ``` hermes setup # Re-run the full wizard hermes setup model # Change model/provider hermes setup gateway # Configure messaging (Telegram, Discord) hermes setup tools # Configure tool providers hermes config # View current settings hermes config edit # Open config in your editor hermes doctor # Check for issues hermes model # Change model or switch to xAI Grok OAuth hermes auth add xai-oauth # Manual OAuth login (if needed) hermes auth list # View stored credentials hermes auth logout xai-oauth # Remove OAuth credentials ``` ## 疑难解答 Hermes 内部提示 xurl: command not found 确保 xurl 在你的 PATH 中。如果你是通过 shell 脚本安装的，请将 ~/.local/bin 添加到你的 PATH 中并重启 Hermes。 OAuth 流程未完成确认 X 开发者应用中的重定向 URI 确切为 http://localhost:8080/callback。确保在运行 xurl auth oauth2 --app my-app 时，端口 8080 上没有运行其他内容。 OAuth 成功，但 API 调用失败并显示 401 确保你使用的是持有你的客户端凭证的同一应用进行了身份验证： ``` xurl auth oauth2 --app my-app xurl auth default my-app ``` 运行 xurl auth status 以确认哪个应用处于活动状态。当前的 xurl 版本会在没有 --app 的情况下运行 OAuth 且存在其他有凭证的应用时发出警告。 API 密钥包含非 ASCII 字符从 PDF 或富文本编辑器复制时会发生这种情况。Hermes 会警告你并自动去除错误字符，但如果身份验证仍然失败，请直接从提供商的控制面板重新复制密钥。 xurl auth status 显示没有活动会话重新运行 xurl auth oauth2 --app my-app 以重新进行身份验证，然后运行 xurl auth default my-app。 ## 总结 1. 使用单行脚本安装 Hermes 2. 运行设置向导（或 hermes model）—— 选择 xAI Grok OAuth (SuperGrok Subscription)，完成一次性浏览器登录，选择一个模型 3. 单独安装 xurl 4. 使用你的 X 开发者应用凭证对 xurl 进行身份验证启动 Hermes，加载 /xurl，并开始用简单的英语与 X 交互就是这样。你现在有了一个运行在终端中的 AI 代理，它可以代表你读写 X、总结你的时间线、管理书签以及 X API 支持的任何其他操作 —— 全部通过对话完成。 ## 相关链接 - [Developers](https://x.com/XDevelopers) - [@XDevelopers](https://x.com/XDevelopers) - [337K](https://x.com/XDevelopers/status/2056871280599847054/analytics) - [x.ai/grok](http://x.ai/grok) - [console.x.com](https://console.x.com/) - [https://accounts.x.ai](https://accounts.x.ai/) - [developer.x.com/en/portal/dashboard](https://developer.x.com/en/portal/dashboard) - [@elonmusk](https://x.com/@elonmusk) - [Upgrade to Premium](https://x.com/i/premium_sign_up) - [6:55 AM · May 20, 2026](https://x.com/XDevelopers/status/2056871280599847054) - [337.9K Views](https://x.com/XDevelopers/status/2056871280599847054/analytics) - [View quotes](https://x.com/XDevelopers/status/2056871280599847054/quotes) --- *导出时间: 2026/5/20 16:16:19*

🔗 相关文档