Chuyển tới nội dung chính

OAuth qua SSH / Máy chủ từ xa

Một số nhà cung cấp Hermes — hiện xAI Grok OAuth và Spotify — sử dụng luồng chuyển hướng vòng lặp OAuth. Máy chủ xác thực (xAI, Spotify) chuyển hướng trình duyệt của bạn đến http://127.0.0.1:<port/callback để một trình nghe HTTP nhỏ được khởi động bằng lệnh Hermes auth ... có thể lấy mã ủy quyền.

Điều này hoạt động hoàn hảo khi Hermes và trình duyệt của bạn ở trên cùng một máy. Nó phá vỡ khoảnh khắc thực tế không như vậy: trình duyệt trên máy tính xách tay của bạn cố gắng truy cập 127.0.0.1 trên máy tính xách tay của bạn, nhưng người nghe bị ràng buộc với 127.0.0.1 trên máy chủ từ xa.

Bản sửa lỗi là chuyển tiếp cục bộ SSH một dòng — hoặc, khi bạn không có ứng dụng khách SSH thực sự (GCP Cloud Shell, GitHub Codespaces, EC2 Instance Connect, Gitpod, IDE web dựa trên trình duyệt), cờ

--manual-paste mới được giới thiệu trong [#26923](https://GitHub.com/NousResearch/Hermes-agent/issues/26923).##TL;DR


# On your local machine (laptop), in a separate terminal:
SSH -N -L 56121:127.0.0.1:56121 user@remote-host

# In your existing SSH session on the remote machine:
Hermes auth add xai-OAuth --no-browser
# → Hermes prints an authorize URL. Open it in a browser on your laptop.
# → Your browser redirects to 127.0.0.1:56121/callback, the tunnel forwards
#   the request to the remote listener, login completes.

`
``Cổng 
`56121
` là cổng mà xAI OAuth sử dụng. Đối với Spotify, thay thế bằng 
`43827

. Hermes in cổng chính xác mà nó liên kết trên dòng 
`Waiting for callback on ...

 - sao chép nó từ đó.

## Đ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 — chẳng hạn vì 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ì đường hầm SSH ở trên sẽ không khả dụng. Thay vào đó hãy sử dụng 

--manual-paste

:

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

# → Hermes prints an authorize URL. Open it in a browser on your laptop.
# → Approve in the browser. The redirect to 127.0.0.1:56121/callback fails
#   to load — that's expected.
# → Copy the FULL URL from the failed page's address bar.
# → Paste it back into the terminal at the "Callback URL:" prompt.

`
``Cờ tương tự hoạt động trên 
`Hermes model --manual-paste
` cho bộ chọn mô hình tích hợp. Một đoạn truy vấn 

?code=...&state=...
` trần cũng được chấp nhận nếu bạn không muốn dán toàn bộ URL.

Hermes sử dụng **cùng một trình xác minh PKCE, trạng thái và nonce** cho cả hai đường dẫn, vì vậy luồng OAuth ngược dòng giống hệt byte — 

--manual-paste
` hoàn toàn là một thay đổi vận chuyển cho bước nhảy gọi lại và không phải là hạ cấp bảo mật.

## Nhà cung cấp nào cần điều này

| Nhà cung cấp | Cổng vòng lặp | Đường hầm cần thiết? |
|----------|--------------|-------|
| 
`xai-OAuth
` (Grok SuperGrok) | 
`56121
` | Vâng, khi Hermes ở xa |
| Spotify |

43827
` | Vâng, khi Hermes ở xa |
| 
`Anthropic
` (Claude Pro/Max) | không có | Không - luồng dán mã |
| 
`OpenAI-Codex
` (ChatGPT Plus/Pro) | không có | Không — luồng mã thiết bị |
| 
`MiniMax

, 
`nous-portal
` | không có | Không — luồng mã thiết bị |

Nếu nhà cung cấp của bạn không có trong bảng thì bạn không cần đường hầm.

## Tại sao người nghe không thể liên kết 0.0.0.0`xAI và Spotify đều xác thực thông số 
`redirect_uri
` dựa trên danh sách cho phép. Cả hai đều yêu cầu biểu mẫu loopback (
`http://127.0.0.1:<exact-port/callback

). Việc liên kết trình nghe với 
`0.0.0.0
` hoặc một cổng khác sẽ khiến máy chủ xác thực từ chối yêu cầu do redirect_uri không khớp. Đường hầm SSH giữ nguyên URI loopback từ đầu đến cuối.

## Từng bước một: bước nhảy SSH đơn

### 1. Bắt đầu đường hầm từ máy cục bộ của bạn

``` bash

# xAI Grok OAuth (port 56121)
SSH -N -L 56121:127.0.0.1:56121 user@remote-host

# Or for Spotify (port 43827)
SSH -N -L 43827:127.0.0.1:43827 user@remote-host

`

-N
` có nghĩa là "không mở shell từ xa, chỉ cần giữ đường hầm mở." Giữ terminal này chạy trong suốt thời gian đăng nhập.

### 2. Trong một phiên SSH riêng biệt, hãy chạy lệnh xác thực

``` bash
SSH user@remote-host
Hermes auth add xai-OAuth --no-browser

# or for Spotify:
# Hermes auth add spotify --no-browser

`
``Hermes phát hiện phiên SSH, bỏ qua quá trình tự động mở trình duyệt và in URL ủy quyền cùng với dòng 
`Waiting for callback on http://127.0.0.1:<port/callback

.

### 3. Mở URL trong trình duyệt cục bộ của bạn

Sao chép URL ủy quyền từ terminal từ xa và dán nó vào trình duyệt trên máy tính xách tay của bạn. Phê duyệt màn hình đồng ý. Máy chủ xác thực chuyển hướng đến 
`http://127.0.0.1:<port/callback

. Trình duyệt của bạn truy cập vào đường hầm, yêu cầu được chuyển tiếp đến người nghe từ xa và Hermes in 
`Login successful!

.

Bạn có thể phá bỏ đường hầm (Ctrl+C trong terminal đầu tiên) khi bạn nhìn thấy dòng thành công.

## Từng bước một: thông qua hộp nhảy

Nếu bạn tiếp cận Hermes thông qua máy chủ pháo đài / nhảy, hãy sử dụng 

-J
` (ProxyJump) tích hợp của SSH:

``` bash
SSH -N -L 56121:127.0.0.1:56121 -J jump-user@jump-host user@final-host

`
``Điều này xâu chuỗi kết nối SSH thông qua máy chủ nhảy mà không đặt cổng loopback trên hộp nhảy. 
`127.0.0.1:56121
` cục bộ trên máy tính xách tay của bạn chuyển thẳng tới 
`127.0.0.1:56121
` trên máy chủ từ xa cuối cùng.

Đối với OpenSSH cũ hơn không hỗ trợ 

`
-J

, dạng dài là:

``` bash
SSH -N \

    -o "ProxyCommand=SSH -W %h:%p jump-user@jump-host" \
    -L 56121:127.0.0.1:56121 \
    user@final-host

`

## Mosh, tmux, SSH ControlMasterĐường hầm là thuộc tính của kết nối SSH cơ bản. Nếu bạn đang chạy Hermes bên trong 
`tmux
` qua phiên mosh thì chuyển vùng mosh không mang chuyển tiếp 

-L

. Mở một phiên SSH đơn giản *riêng* chỉ** cho đường hầm 

-L
` — đó là kết nối phải duy trì hoạt động trong luồng xác thực. Phiên mosh/tmux tương tác của bạn có thể tiếp tục chạy Hermes bình thường.

Nếu bạn sử dụng 
`SSH -o ControlMaster=auto

, cổng chuyển tiếp trên kết nối đa kênh sẽ chia sẻ thời gian hoạt động của cổng chính. Khởi động lại bản gốc nếu đường hầm không xuất hiện:

``` bash
SSH -O exit user@remote-host
SSH -N -L 56121:127.0.0.1:56121 user@remote-host

`

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

### 
`bind [127.0.0.1]:56121: Address already in use
``Một cái gì đó trên máy tính xách tay của bạn đã sử dụng cổng đó. Hoặc là đường hầm trước đó chưa được đóng hoàn toàn, hoặc một chiếc Hermes địa phương cũng đang nghe lén nó. Tìm và tiêu diệt kẻ phạm tội:

`bash

# macOS / Linux
lsof -iTCP:56121 -sTCP:LISTEN
kill <PID

`
``Sau đó thử lại lệnh 
`SSH -L

.

### "Không thể thiết lập kết nối. Chúng tôi không thể truy cập ứng dụng của bạn." (xAI)

Trang ủy quyền của xAI hiển thị điều này khi chuyển hướng đến 
`127.0.0.1:<port/callback
` không đến được người nghe. Đường hầm không chạy, cổng sai hoặc bạn đang sử dụng cổng Hermes được in trong lần chạy trước (cổng có thể tự động bị lỗi nếu cổng ưu tiên bận - luôn đọc dòng 
`Waiting for callback on ...
` mới nhất).

###
`xAI authorization timed out waiting for the local callback
``Nguyên nhân gốc rễ tương tự như trên — chuyển hướng không bao giờ quay trở lại. Kiểm tra đường hầm vẫn còn hoạt động (
`SSH -N
` không hiển thị đầu ra, vì vậy hãy xem terminal mà bạn đã khởi động nó), khởi động lại nếu cần và chạy lại 
`Hermes auth add xai-OAuth --no-browser

.

### Token rơi vào sai 

~/.Hermes
``Mã thông báo được viết theo người dùng Linux chạy 
`Hermes auth add ...

. Nếu dịch vụ cổng / systemd của bạn chạy với tư cách một người dùng khác (ví dụ: 
`root
` hoặc người dùng 
`Hermes
` chuyên dụng), hãy xác thực là **người dùng đó** để mã thông báo rơi vào 

~/.Hermes/auth.JSON
` của họ. 
`sudo -u Hermes -i
` hoặc tương đương.

## Xem thêm
- [xAI Grok OAuth](./xai-grok-OAuth.md)
- [Spotify (XPROTECTX55XPROTECTX)](../user-guide/features/spotify.md#running-over-SSH--in-a-headless-environment)
- [SSH XPROTECTX56XPROTECTX / ProxyJump (man page)](https://man.openbsd.org/SSH#J)