xAI Grok OAuth (SuperGrok / X Premium+)

Hermes Agent hỗ trợ xAI Grok thông qua luồng đăng nhập OAuth dựa trên trình duyệt dựa trên accounts.x.ai, sử dụng đăng ký SuperGrok (grok.com) hoặc đăng ký X Premium+ (tài khoản X được liên kết). Không cần `XAI_API_KEY

• đăng nhập một lần và Hermes tự động làm mới phiên của bạn trong nền.

Khi bạn đăng nhập bằng tài khoản X có Premium+, xAI sẽ tự động liên kết trạng thái đăng ký với phiên xAI của bạn, do đó, luồng OAuth hoạt động giống như đối với những người đăng ký SuperGrok trực tiếp.

Quá trình truyền tải sử dụng lại bộ điều hợp Codex_responses (xAI hiển thị điểm cuối kiểu Phản hồi), do đó lý luận, gọi công cụ, phát trực tuyến và bộ nhớ đệm nhắc nhở hoạt động mà không cần bất kỳ thay đổi bộ điều hợp nào.

Mã thông báo mang OAuth tương tự cũng được sử dụng lại bởi mọi bề mặt trực tiếp tới xAI trong Hermes — TTS, tạo hình ảnh, tạo video và chép lời — vì vậy, một lần đăng nhập sẽ bao gồm cả bốn.

Tổng quan

Mục	Giá trị
ID nhà cung cấp

xai-OAuth | | Tên hiển thị | xAI Grok OAuth (SuperGrok / X Premium+) | | Loại xác thực | Trình duyệt OAuth 2.0 PKCE (gọi lại vòng lặp) | | Vận tải | API phản hồi xAI (Codex_responses

) | | Mô hình mặc định |

grok-4.3 ` | | Điểm cuối |

https://API.x.ai/v1 ` | | Máy chủ xác thực |

https://accounts.x.ai | | Yêu cầu env var | Không (XAI_API_KEY ` không được sử dụng cho nhà cung cấp này) | | Đăng ký | SuperGrok hoặc X Premium+ - xem ghi chú bên dưới |

Điều kiện tiên quyết

• Python 3.9+
• Đã cài đặt Đại lý Hermes
• Đăng ký SuperGrok đang hoạt động trên tài khoản xAI của bạn, hoặc đăng ký X Premium+ trên tài khoản X mà bạn đăng nhập (xAI tự động liên kết đăng ký)
• Trình duyệt có sẵn trên máy cục bộ (hoặc sử dụng

--no-browser ` cho các phiên từ xa)

xAI may restrict OAuth API access by tier

Phần phụ trợ của xAI thực thi danh sách cho phép của riêng mình trên bề mặt API OAuth và được cho là đã từ chối những người đăng ký SuperGrok tiêu chuẩn bằng HTTP 403 (xem vấn đề #26847) ngay cả khi đăng ký trong ứng dụng đang hoạt động. Nếu đăng nhập OAuth thành công trong trình duyệt nhưng suy luận trả về 403, hãy đặt XAI_API_KEY và chuyển sang đường dẫn khóa API ( `provider: xai

) — bề mặt đó không phải tuân theo cùng một cổng ngày nay.

Bắt đầu nhanh

# Launch the provider and model picker
Hermes model
# → Select "xAI Grok OAuth (SuperGrok / X Premium+)" from the provider list
# → Hermes opens your browser to accounts.x.ai
# → Approve access in the browser
# → Pick a model (grok-4.3 is at the top)
# → Start chatting

Hermes

`
``Sau lần đăng nhập đầu tiên, thông tin đăng nhập được lưu trữ trong 

~/.Hermes/auth.JSON
` và tự động được làm mới trước khi hết hạn.

## Đăng nhập thủ công

Bạn có thể kích hoạt đăng nhập mà không cần thông qua bộ chọn mô hình:

``` bash
Hermes auth add xai-OAuth

`

### Phiên từ xa / không đầu

Trên máy chủ, vùng chứa hoặc phiên SSH không có trình duyệt, Hermes sẽ phát hiện môi trường từ xa và in URL ủy quyền thay vì mở trình duyệt.

**Quan trọng:** trình nghe vòng lặp vẫn chạy trên máy từ xa tại 
`127.0.0.1:56121

. Chuyển hướng xAI cần tiếp cận người nghe *đó*, vì vậy việc mở URL trên máy tính xách tay của bạn sẽ không thành công (
`Could not establish connection. We couldn't reach your app.

) trừ khi bạn chuyển tiếp cổng:

`bash

# In a separate terminal on your local machine:
SSH -N -L 56121:127.0.0.1:56121 user@remote-host

# Then in your SSH session on the remote machine:
Hermes auth add xai-OAuth --no-browser
# Open the printed authorize URL in your local browser.

`
``Thông qua hộp nhảy / pháo đài: thêm 

-J jump-user@jump-host

.

Xem [OAuth over SSH / Remote Hosts](./OAuth-over-SSH.md) để biết đầy đủ từng bước, bao gồm chuỗi ProxyJump, mosh/tmux và các gotcha của ControlMaster.

### Điều khiển từ xa chỉ dành cho trình duyệt (Cloud Shell, Codespaces, EC2 Instance Connect)

Nếu bạn không có ứng dụng khách SSH thông thường (ví dụ: bạn đang chạy Hermes bên trong GCP Cloud Shell, GitHub Codespaces, AWS EC2 Instance Connect, Gitpod hoặc bảng điều khiển dựa trên trình duyệt khác), thì công thức 
`SSH -L
` ở trên sẽ không khả dụng. Thay vào đó, hãy sử dụng 

--manual-paste

 - Hermes bỏ qua trình nghe vòng lặp và cho phép bạn dán URL gọi lại không thành công ngay từ trình duyệt của mình:

``` bash
Hermes auth add xai-OAuth --manual-paste

# Or via the model picker:
Hermes model --manual-paste

`
``Xem [OAuth over SSH / Remote Hosts](./OAuth-over-SSH.md#browser-only-remote-cloud-shell--codespaces--ec2-instance-connect) để biết hướng dẫn đầy đủ. Sửa lỗi hồi quy cho [#26923](https://GitHub.com/NousResearch/Hermes-agent/issues/26923).

## Cách đăng nhập hoạt động
1. Hermes mở trình duyệt của bạn tới 
`accounts.x.ai

.
2. Bạn đăng nhập (hoặc xác nhận phiên hiện tại của bạn) và phê duyệt quyền truy cập.
3. xAI chuyển hướng trở lại Hermes và mã thông báo được lưu vào 

~/.Hermes/auth.JSON

.
4. Từ đó trở đi, Hermes làm mới mã thông báo truy cập ở chế độ nền — bạn duy trì trạng thái đăng nhập cho đến khi 
`Hermes auth remove xai-OAuth
` hoặc thu hồi quyền truy cập từ cài đặt tài khoản xAI của bạn.

## Kiểm tra trạng thái đăng nhập

``` bash
Hermes doctor

`
``Phần 

◆ Auth Providers
` sẽ hiển thị trạng thái hiện tại của mọi nhà cung cấp, bao gồm 
`xai-OAuth

.

## Chuyển đổi mô hình

`bash
Hermes model

# → Select "xAI Grok OAuth (SuperGrok / X Premium+)"
# → Pick from the model list (grok-4.3 is pinned to the top)

`
``Hoặc đặt mô hình trực tiếp:

``` bash
Hermes config set model.default grok-4.3
Hermes config set model.provider xai-OAuth

`

## Tham khảo cấu hìnhSau khi đăng nhập, 

~/.Hermes/config.yaml
` sẽ chứa:

`YAML
model:
  default: grok-4.3
  provider: xai-OAuth
  base_url: https://API.x.ai/v1

`

### Bí danh của nhà cung cấp

Tất cả những điều sau đây đều giải quyết được 
`xai-OAuth

:

`bash
Hermes --provider xai-OAuth        # canonical
Hermes --provider grok-OAuth       # alias
Hermes --provider x-ai-OAuth       # alias
Hermes --provider xai-grok-OAuth   # alias

`

## Công cụ Direct-to-xAI (TTS / Hình ảnh / Video / Phiên âm / Tìm kiếm X)

Sau khi bạn đăng nhập qua OAuth, mọi công cụ chuyển trực tiếp tới xAI sẽ tự động sử dụng lại cùng một mã thông báo mang — không có **thiết lập riêng** trừ khi bạn muốn sử dụng khóa API.

Để chọn phần phụ trợ cho từng công cụ:

`bash
Hermes tools

# → Text-to-Speech       → "xAI TTS"
# → Image Generation     → "xAI Grok Imagine (image)"
# → Video Generation     → "xAI Grok Imagine"
# → X (Twitter) Search   → "xAI Grok OAuth (SuperGrok / X Premium+)"

`
``Nếu mã thông báo OAuth đã được lưu trữ, bộ chọn sẽ xác nhận mã đó và bỏ qua lời nhắc xác thực. Nếu cả OAuth và 
`XAI_API_KEY
` đều không được đặt, bộ chọn sẽ cung cấp menu 3 lựa chọn: đăng nhập OAuth, dán khóa API hoặc bỏ qua.

:::note[Video generation is off by default]
Bộ công cụ 
`video_gen
` bị tắt theo mặc định. Kích hoạt nó trong 
`Hermes tools
` → 

🎬 Video Generation
` (nhấn dấu cách) trước khi tổng đài viên có thể gọi 
`video_generate

. Nếu không, tác nhân có thể quay lại sử dụng kỹ năng ComfyUI đi kèm, kỹ năng này cũng được gắn thẻ để tạo video.
:::

:::note[X search auto-enables when xAI credentials are present]
Bộ công cụ 
`x_search
` tự động kích hoạt bất cứ khi nào thông tin xác thực xAI (mã thông báo SuperGrok / X Premium+ OAuth hoặc 
`XAI_API_KEY

) được định cấu hình. Tắt rõ ràng thông qua 
`Hermes tools
` → 

🐦 X (Twitter) Search
` (nhấn phím cách) nếu bạn không muốn điều này. Công cụ này định tuyến thông qua API phản hồi 
`x_search
` tích hợp của xAI — công cụ này hoạt động với **** ** thông tin đăng nhập SuperGrok / X Premium+ OAuth của bạn hoặc 
`XAI_API_KEY
` trả phí và ưu tiên OAuth khi cả hai đều được định cấu hình (sử dụng hạn mức đăng ký của bạn thay vì chi tiêu API). Lược đồ công cụ bị ẩn khỏi mô hình khi không có thông tin xác thực xAI nào được định cấu hình, bất kể bộ công cụ có được bật hay không.
:::

### Người mẫu

| Công cụ | Người mẫu | Ghi chú |
|------|-------|-------|
| Trò chuyện |

grok-4.3
` | Mặc định; tự động được chọn khi bạn đăng nhập qua OAuth |
| Trò chuyện |

grok-4.20-0309-reasoning
` | Biến thể lý luận |
| Trò chuyện |

grok-4.20-0309-non-reasoning
` | Biến thể không lý luận |
| Trò chuyện |

grok-4.20-multi-agent-0309
` | Biến thể đa tác nhân |
| Hình ảnh |

grok-imagine-image
` | Mặc định; ~5–10 giây |
| Hình ảnh |

grok-imagine-image-quality
` | Độ trung thực cao hơn; ~10–20 giây |
| Video |

grok-imagine-video
` | Chuyển văn bản thành video và hình ảnh thành video; tối đa 7 hình ảnh tham khảo |
| TTS | (giọng mặc định) | Điểm cuối xAI 

/v1/tts
` |

Danh mục trò chuyện được lấy trực tiếp từ bộ đệm 
`models.dev
` trên đĩa; bản phát hành xAI mới tự động xuất hiện sau khi bộ nhớ đệm đó được làm mới. 
`grok-4.3
` luôn được ghim lên đầu danh sách.

## Biến môi trường

| Biến | Hiệu ứng |
|----------|--------|
| 
`XAI_BASE_URL
` | Ghi đè điểm cuối 
`https://API.x.ai/v1
` mặc định (hiếm khi cần thiết). |

Để chọn xAI làm nhà cung cấp đang hoạt động, hãy đặt 
`model.provider: xai-OAuth
` trong 
`config.yaml
` (sử dụng 
`Hermes setup
` cho luồng được hướng dẫn) hoặc chuyển 

--provider xai-OAuth
` cho một lệnh gọi duy nhất.

## Khắc phục sự cố

### Mã thông báo đã hết hạn — không tự động đăng nhập lại

Hermes làm mới mã thông báo trước mỗi phiên và phản ứng lại trên 401. Nếu làm mới không thành công với 
`invalid_grant
` (mã thông báo làm mới đã bị thu hồi hoặc tài khoản đã được xoay), Hermes sẽ hiển thị thông báo xác thực lại đã nhập thay vì gặp sự cố.

Khi lỗi làm mới xảy ra ở terminal (HTTP 4xx, 
`invalid_grant

, quyền bị thu hồi, v.v.), Hermes đánh dấu mã thông báo làm mới là đã chết và cách ly nó cục bộ — các lệnh gọi tiếp theo sẽ bỏ qua nỗ lực làm mới bị hủy thay vì phát đi phát lại cùng một mã 401. Tác nhân sẽ hiển thị một thông báo "yêu cầu xác thực lại" và không hiển thị cho đến khi bạn đăng nhập lại.

**Khắc phục:** chạy lại 
`Hermes auth add xai-OAuth
` để bắt đầu đăng nhập mới. Việc kiểm dịch sẽ được xóa trong lần trao đổi thành công tiếp theo.

### Đã hết thời gian ủy quyền

Trình nghe vòng lặp có thời hạn sử dụng hữu hạn (mặc định là 180 giây). Nếu bạn không phê duyệt đăng nhập kịp thời, Hermes sẽ xuất hiện lỗi hết thời gian chờ.

**Khắc phục:** chạy lại 
`Hermes auth add xai-OAuth
` (hoặc 
`Hermes model

). Dòng chảy bắt đầu tươi mới.

### Trạng thái không khớp (có thể là CSRF)

Hermes phát hiện thấy giá trị 
`state
` được máy chủ ủy quyền trả về không khớp với giá trị nó gửi.

**Khắc phục:** chạy lại thông tin đăng nhập. Nếu tình trạng này vẫn tiếp diễn, hãy kiểm tra proxy hoặc chuyển hướng đang sửa đổi phản hồi OAuth.

### Đăng nhập từ máy chủ từ xa

Trên các phiên SSH hoặc vùng chứa, Hermes in URL ủy quyền thay vì mở trình duyệt. Trình nghe gọi lại vòng lặp vẫn liên kết 
`127.0.0.1:56121
` trên máy chủ từ xa — trình duyệt trên máy tính xách tay của bạn không thể truy cập nó nếu không có SSH chuyển tiếp cục bộ:

``` bash

# Local machine, separate terminal:
SSH -N -L 56121:127.0.0.1:56121 user@remote-host

# Remote machine:
Hermes auth add xai-OAuth --no-browser

`
`Hướng dẫn đầy đủ (hộp nhảy, mosh/tmux, xung đột cổng): [OAuth over SSH / Remote Hosts](./OAuth-over-SSH.md).

### HTTP 403 sau khi đăng nhập thành công (cấp/quyền)

OAuth đã hoàn tất trong trình duyệt, mã thông báo được lưu nhưng suy luận hoặc làm mới mã thông báo trả về 
`HTTP 403
` với thông báo tương tự như *"Người gọi không có quyền thực hiện thao tác đã chỉ định"*.

Đây **không phải** là vấn đề về mã thông báo cũ — việc chạy lại 
`Hermes model
` sẽ không thay đổi được vấn đề. Phần phụ trợ của xAI được cho là hạn chế quyền truy cập API OAuth vào các cấp SuperGrok cụ thể mặc dù đăng ký trong ứng dụng đang hoạt động (vấn đề [#26847](https://GitHub.com/NousResearch/Hermes-agent/issues/26847)).

**Khắc phục:** đặt 
`XAI_API_KEY
` và chuyển sang đường dẫn khóa API:

``` bash
 export XAI_API_KEY=xai-...
Hermes config set model.provider xai

`
``Hoặc nâng cấp đăng ký của bạn tại [x.ai/grok](https://x.ai/grok) nếu cần có tuyến OAuth.

### Lỗi "Không tìm thấy thông tin xác thực xAI" khi chạy

Cửa hàng xác thực không có mục 
`xai-OAuth
` và không có 
`XAI_API_KEY
` nào được đặt. Bạn chưa đăng nhập hoặc tệp thông tin xác thực đã bị xóa.

**Khắc phục:** chạy 
`Hermes model
` và chọn nhà cung cấp xAI Grok OAuth hoặc chạy 
`Hermes auth add xai-OAuth

.

## Đăng xuất

Để xóa tất cả thông tin xác thực xAI Grok OAuth được lưu trữ:

`bash
Hermes auth logout xai-OAuth

`
``Thao tác này sẽ xóa cả mục nhập OAuth đơn lẻ trong 
`auth.JSON
` và mọi hàng nhóm thông tin xác thực cho 
`xai-OAuth

. Sử dụng 
`Hermes auth remove xai-OAuth <index|id|label>
` nếu bạn chỉ muốn bỏ một mục nhập nhóm duy nhất (chạy 
`Hermes auth list xai-OAuth
` để xem chúng).

## Xem thêm
- [OAuth over SSH / Remote Hosts](./OAuth-over-SSH.md) - cần đọc nếu Hermes ở trên máy khác với trình duyệt của bạn

- [AI Providers reference](../integrations/providers.md)
- [Environment Variables](../reference/environment-variables.md)
- [Configuration](../user-guide/configuration.md)
- [Voice & TTS](../user-guide/features/tts.md)