命令参数

TIP

Xray 使用 Go 风格的命令及参数

获取基本命令

您可以运行 xray help 来获得所有 xray 最基础的用法, 以及可用的命令及说明。

Xray is a platform for building proxies.

Usage:

        xray <command> [arguments]

The commands are:

        run          Run Xray with config, the default command
        version      Show current version of Xray
        api          Call an API in an Xray process
        convert      Convert configs
        tls          TLS tools
        uuid         Generate UUIDv4 or UUIDv5 (VLESS)
        x25519       Generate key pair for X25519 key exchange (REALITY, VLESS Encryption)
        wg           Generate key pair for X25519 key exchange (WireGuard)
        mldsa65      Generate key pair for ML-DSA-65 post-quantum signature (REALITY)
        mlkem768     Generate key pair for ML-KEM-768 post-quantum key exchange (VLESS Encryption)
        vlessenc     Generate decryption/encryption json pair (VLESS Encryption)

Use "xray help <command>" for more information about a command.

xray run

指定一个或多个配置文件，并运行。

使用方法:

xray run [-c config.json] [-confdir dir] [-format auto|json|yaml|toml|protobuf] [-test] [-dump] [-json-to-yaml] [-yaml-to-json] [-src file|dir] [-dst file|dir] [-yaml-flip n] [-yaml-no-alias] [-multi]

参数说明：

-config= / -c=

指定一个或多个配置文件（可重复指定）。当 -format=auto（默认）时，Xray 会按文件扩展名识别格式：

• *.json / *.jsonc -> JSON（jsonc 允许注释）
• *.yaml / *.yml -> YAML
• *.toml -> TOML
• *.pb -> Protobuf（仅允许单文件）

-confdir=

指定一个包含多个配置文件的目录。Xray 会按文件名排序读取并合并（见 多文件配置）。

WARNING

confdir 同时包含 JSON（*.json/*.jsonc）与 YAML（*.yaml/*.yml）文件会直接报错。

-format=

指定配置文件格式：auto（默认）、json、yaml、toml、protobuf。当指定为非 auto 时，将强制所有 -c/-config 文件按该格式解析。

-test

仅测试配置文件是否合法（会加载并创建核心实例，但不启动服务）。

-dump

打印合并后的配置并退出（不启动服务）。会执行订阅拉取与合并（会展开 subscription {}，输出中不会保留该区块）。注意：-dump 仅对 json/yaml/toml 有意义。

-json-to-yaml

将合并后的配置输出为 YAML 并退出（不启动服务）。需要同时指定 -src 与 -dst。行为类似 -dump，同样会执行订阅拉取与合并（输出中不会保留 subscription {} 区块）。

默认输出为 block style（-yaml-flip=0，尽量不使用 {} 形式）。

示例：

# 指定输入/输出（文件或目录）
xray --json-to-yaml --src config.json --dst config.yaml

# 输出到目录（会写入 out/config.yaml）
xray --json-to-yaml --src config.json --dst ./out

# 源为目录（confdir），输出到目录（会写入 out/config.yaml）
xray --json-to-yaml --src ./confs --dst ./out

# 从 STDIN 读取（需显式指定 stdin:）
cat config.json | xray --json-to-yaml --src stdin: --dst config.yaml

配置文件自动发现顺序

当未指定 -c/-config 且未通过 -confdir/环境变量提供目录时，Xray 会按顺序尝试：

• 工作目录中的 config.json / config.jsonc / config.toml / config.yaml / config.yml
• 环境变量 xray.location.config（或 XRAY_LOCATION_CONFIG）目录下的 config.json
• 从 STDIN 读取（等价于使用 stdin: 作为配置源）

 xray run -dump

用以输出多文件配置融合之后的结果。

xray version

输出 Xray 版本、 Golang 版本等信息。

使用方法:

 xray version

xray api

调用 Xray 的 gRPC API，需要在配置文件中开启。

使用方法:

xray api <command> [arguments]

        restartlogger Restart the logger
        stats         Get statistics
        statsquery    Query statistics
        statssys      Get system statistics
        adi           Add inbounds
        ado           Add outbounds
        rmi           Remove inbounds
        rmo           Remove outbounds

xray convert

把配置文件转换成 protobuf 或者把 typedMessage 转换成 JSON

使用方法：

xray convert <command> [arguments]

The commands are:

        pb           Convert multiple json configs to protobuf
        json         Convert typedMessage to json

pb 子命令使用示例：

# 用法：xray convert pb [-outpbfile out.pb] [-debug] [-type] [json file] [json file] ...

# 把三个配置合并成 mix.pb
xray convert pb -outpbfile mix.pb c1.json c2.json c3.json

# 使用 -debug 选项查看 mix.pb 的内容
xray convert pb -debug mix.pb

# 使用 mix.pb 启动 Xray-core
xray -c mix.pb

# 详细说明
xray help convert pb

json 子命令使用示例：

# 用法：xray convert json [-type] [stdin:] [typedMessage file]

tmsg='{
  "type": "xray.proxy.shadowsocks.Account",
  "value": "CgMxMTEQBg=="
}'

echo ${tmsg} | xray convert json stdin:

# 上面这个命令的输出结果是：
'{
  "cipherType": "AES_256_GCM",
  "password": "111"
}'

# 详细说明
xray help convert json

xray tls

一些与 TLS 相关的工具。

使用方法:

xray tls <command> [arguments]

        cert          Generate TLS certificates
        ping          Ping the domain with TLS handshake
        certChainHash Calculate TLS certificates hash.

xray uuid

生成 UUID。

使用方法:

xray uuid [-i "example"]

xray x25519

生成 x25519 密钥对。

使用方法:

xray x25519 [-i "(base64.RawURLEncoding)" --std-encoding ]

xray wg

生成 wireguard curve25519 密钥对。

使用方法:

xray wg [-i "(base64.StdEncoding)"]

xray mldsa65

生成用于 REALITY 的 MLDSA-65 后量子签名密钥对。

使用方法:

xray mldsa65 [-i "seed (base64.StdEncoding)"]

xray mlkem768

生成用于 VLESS Encryption 的 ML-KEM-768 后量子密钥交换用密钥对。

使用方法:

xray mlkem768 [-i "seed (base64.StdEncoding)"]

xray vlessenc

生成可以直接用于 VLESS Encryption 的 encryption/decryption 选项内容。生成配置中 X25519 以及 ML-KEM-768 两种认证方式选一种使用即可，但是服务端及客户端必须采用同一种认证方式。临时密钥交换仍后量子安全，不受认证方式影响。

使用方法:

xray vlessenc