> ## Documentation Index
> Fetch the complete documentation index at: https://docs2.openclaw.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Tailscale

OpenClaw có thể tự động cấu hình Tailscale **Serve** (tailnet) hoặc **Funnel** (công khai) cho
bảng điều khiển Gateway và cổng WebSocket. Điều này giữ Gateway được bind vào loopback trong khi
Tailscale cung cấp HTTPS, định tuyến và (đối với Serve) các header danh tính.

## Chế độ

* `serve`: Serve chỉ dành cho tailnet qua `tailscale serve`. Gateway vẫn ở `127.0.0.1`.
* `funnel`: HTTPS công khai qua `tailscale funnel`. OpenClaw yêu cầu mật khẩu dùng chung.
* `off`: Mặc định (không có tự động hóa Tailscale).

Đầu ra trạng thái và kiểm tra dùng **mức phơi bày Tailscale** cho chế độ OpenClaw Serve/Funnel
này. `off` nghĩa là OpenClaw không quản lý Serve hoặc Funnel; điều đó không có nghĩa là
daemon Tailscale cục bộ đã dừng hoặc đã đăng xuất.

## Xác thực

Đặt `gateway.auth.mode` để kiểm soát quá trình bắt tay:

* `none` (chỉ ingress riêng tư)
* `token` (mặc định khi `OPENCLAW_GATEWAY_TOKEN` được đặt)
* `password` (bí mật dùng chung qua `OPENCLAW_GATEWAY_PASSWORD` hoặc cấu hình)
* `trusted-proxy` (reverse proxy nhận biết danh tính; xem [Xác thực Trusted Proxy](/vi/gateway/trusted-proxy-auth))

Khi `tailscale.mode = "serve"` và `gateway.auth.allowTailscale` là `true`,
xác thực Giao diện điều khiển/WebSocket có thể dùng các header danh tính Tailscale
(`tailscale-user-login`) mà không cần cung cấp token/mật khẩu. OpenClaw xác minh
danh tính bằng cách phân giải địa chỉ `x-forwarded-for` qua daemon Tailscale
cục bộ (`tailscale whois`) và đối chiếu với header trước khi chấp nhận.
OpenClaw chỉ xem một yêu cầu là Serve khi yêu cầu đó đến từ loopback với các
header `x-forwarded-for`, `x-forwarded-proto`, và `x-forwarded-host` của
Tailscale.
Đối với các phiên vận hành Giao diện điều khiển có bao gồm danh tính thiết bị trình duyệt, đường dẫn Serve
đã xác minh này cũng bỏ qua vòng ghép đôi thiết bị. Nó không bỏ qua
danh tính thiết bị trình duyệt: các client không có thiết bị vẫn bị từ chối, và các kết nối
WebSocket `node-role` hoặc không phải Giao diện điều khiển vẫn đi theo quy trình ghép đôi và
kiểm tra xác thực thông thường.
Các endpoint HTTP API (ví dụ `/v1/*`, `/tools/invoke`, và `/api/channels/*`)
**không** dùng xác thực bằng header danh tính Tailscale. Chúng vẫn đi theo chế độ
xác thực HTTP thông thường của gateway: xác thực bằng bí mật dùng chung theo mặc định, hoặc một thiết lập
trusted-proxy / ingress riêng tư `none` được cấu hình có chủ ý.
Luồng không cần token này giả định máy chủ gateway là đáng tin cậy. Nếu mã cục bộ không đáng tin cậy
có thể chạy trên cùng máy chủ, hãy tắt `gateway.auth.allowTailscale` và yêu cầu
xác thực bằng token/mật khẩu thay vào đó.
Để yêu cầu thông tin xác thực bí mật dùng chung rõ ràng, đặt `gateway.auth.allowTailscale: false`
và dùng `gateway.auth.mode: "token"` hoặc `"password"`.

## Ví dụ cấu hình

### Chỉ tailnet (Serve)

```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  gateway: {
    bind: "loopback",
    tailscale: { mode: "serve" },
  },
}
```

Mở: `https://<magicdns>/` (hoặc `gateway.controlUi.basePath` bạn đã cấu hình)

Để phơi bày Giao diện điều khiển qua một Tailscale Service có tên thay vì
hostname của thiết bị, đặt `gateway.tailscale.serviceName` thành tên Service:

```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  gateway: {
    bind: "loopback",
    tailscale: { mode: "serve", serviceName: "svc:openclaw" },
  },
}
```

Với ví dụ trên, khi khởi động sẽ báo cáo URL Service là
`https://openclaw.<tailnet-name>.ts.net/` thay vì hostname của thiết bị.
Tailscale Services yêu cầu host là một nút đã gắn thẻ được phê duyệt trong
tailnet của bạn. Hãy cấu hình thẻ và phê duyệt Service trong Tailscale trước khi bật
tùy chọn này, nếu không `tailscale serve --service=...` sẽ thất bại trong lúc
khởi động gateway.

### Chỉ tailnet (bind vào IP Tailnet)

Dùng chế độ này khi bạn muốn Gateway lắng nghe trực tiếp trên IP Tailnet (không Serve/Funnel).

```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  gateway: {
    bind: "tailnet",
    auth: { mode: "token", token: "your-token" },
  },
}
```

Kết nối từ một thiết bị Tailnet khác:

* Giao diện điều khiển: `http://<tailscale-ip>:18789/`
* WebSocket: `ws://<tailscale-ip>:18789`

<Note>
  Loopback (`http://127.0.0.1:18789`) sẽ **không** hoạt động trong chế độ này.
</Note>

### Internet công khai (Funnel + mật khẩu dùng chung)

```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  gateway: {
    bind: "loopback",
    tailscale: { mode: "funnel" },
    auth: { mode: "password", password: "replace-me" },
  },
}
```

Ưu tiên `OPENCLAW_GATEWAY_PASSWORD` thay vì commit mật khẩu vào đĩa.

## Ví dụ CLI

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
openclaw gateway --tailscale serve
openclaw gateway --tailscale funnel --auth password
```

## Ghi chú

* Tailscale Serve/Funnel yêu cầu CLI `tailscale` đã được cài đặt và đã đăng nhập.
* `tailscale.mode: "funnel"` từ chối khởi động trừ khi chế độ xác thực là `password` để tránh phơi bày công khai.
* `gateway.tailscale.serviceName` chỉ áp dụng cho chế độ Serve và được truyền cho
  `tailscale serve --service=<name>`. Giá trị phải dùng định dạng tên Service
  `svc:<dns-label>` của Tailscale, ví dụ `svc:openclaw`.
  Tailscale yêu cầu host Service là các nút đã gắn thẻ, và Service có thể cần
  được phê duyệt trong bảng điều khiển quản trị trước khi Serve có thể phát hành nó.
* Đặt `gateway.tailscale.resetOnExit` nếu bạn muốn OpenClaw hoàn tác cấu hình `tailscale serve`
  hoặc `tailscale funnel` khi tắt.
* Đặt `gateway.tailscale.preserveFunnel: true` để giữ một route
  `tailscale funnel` được cấu hình bên ngoài tiếp tục hoạt động qua các lần khởi động lại gateway. Khi bật và
  gateway chạy ở `mode: "serve"`, OpenClaw kiểm tra `tailscale funnel status`
  trước khi áp dụng lại Serve và bỏ qua khi một route Funnel đã bao phủ
  cổng gateway. Chính sách Funnel do OpenClaw quản lý chỉ dùng mật khẩu vẫn không đổi.
* `gateway.bind: "tailnet"` là bind Tailnet trực tiếp (không HTTPS, không Serve/Funnel).
* `gateway.bind: "auto"` ưu tiên loopback; dùng `tailnet` nếu bạn muốn chỉ dùng Tailnet.
* Serve/Funnel chỉ phơi bày **Giao diện điều khiển Gateway + WS**. Các nút kết nối qua
  cùng endpoint Gateway WS, vì vậy Serve có thể hoạt động cho truy cập nút.

## Điều khiển trình duyệt (Gateway từ xa + trình duyệt cục bộ)

Nếu bạn chạy Gateway trên một máy nhưng muốn điều khiển trình duyệt trên một máy khác,
hãy chạy một **máy chủ nút** trên máy có trình duyệt và giữ cả hai trong cùng tailnet.
Gateway sẽ proxy các thao tác trình duyệt đến nút; không cần máy chủ điều khiển riêng hoặc URL Serve riêng.

Tránh Funnel cho điều khiển trình duyệt; xem việc ghép đôi nút như quyền truy cập của người vận hành.

## Điều kiện tiên quyết + giới hạn của Tailscale

* Serve yêu cầu HTTPS được bật cho tailnet của bạn; CLI sẽ nhắc nếu thiếu.
* Serve chèn các header danh tính Tailscale; Funnel thì không.
* Funnel yêu cầu Tailscale v1.38.3+, MagicDNS, HTTPS được bật, và một thuộc tính nút funnel.
* Funnel chỉ hỗ trợ các cổng `443`, `8443`, và `10000` qua TLS.
* Funnel trên macOS yêu cầu biến thể ứng dụng Tailscale mã nguồn mở.

## Tìm hiểu thêm

* Tổng quan Tailscale Serve: [https://tailscale.com/kb/1312/serve](https://tailscale.com/kb/1312/serve)
* Lệnh `tailscale serve`: [https://tailscale.com/kb/1242/tailscale-serve](https://tailscale.com/kb/1242/tailscale-serve)
* Tổng quan Tailscale Funnel: [https://tailscale.com/kb/1223/tailscale-funnel](https://tailscale.com/kb/1223/tailscale-funnel)
* Lệnh `tailscale funnel`: [https://tailscale.com/kb/1311/tailscale-funnel](https://tailscale.com/kb/1311/tailscale-funnel)

## Liên quan

* [Truy cập từ xa](/vi/gateway/remote)
* [Khám phá](/vi/gateway/discovery)
* [Xác thực](/vi/gateway/authentication)