配置

环境变量

通过环境变量配置 xiantong

环境变量为自动化和服务器部署场景提供配置和凭证。

支持的变量#

ANTHROPIC_API_KEY / XIANTONG_ANTHROPIC_API_KEY#

提供 Anthropic API 密钥，无需本地存储。两种名称都支持；如果两者都设置，则 XIANTONG_ANTHROPIC_API_KEY 优先。

export ANTHROPIC_API_KEY="sk-ant-api03-..."
xiantong -p "Check my tasks"

XIANTONG_CLAUDE_OAUTH_TOKEN#

提供 Claude OAuth 令牌（适用于 Claude Pro/Max 订阅），无需本地存储。

export XIANTONG_CLAUDE_OAUTH_TOKEN="your-oauth-token"

ANTHROPIC_BASE_URL#

覆盖 API 端点 URL。当你通过 UI 为非 Anthropic 提供商（OpenRouter、Vercel AI Gateway、Ollama 或自定义端点）配置时，xiantong 会自动设置此项。

export ANTHROPIC_BASE_URL="https://openrouter.ai/api"

也可以手动设置，将所有 API 调用通过自定义端点路由：

# 使用 OpenRouter
export ANTHROPIC_BASE_URL="https://openrouter.ai/api"

# 使用本地 Ollama
export ANTHROPIC_BASE_URL="http://localhost:11434"

根据你的 API 提供商配置，xiantong 通常会管理此变量。只有在自动化或 CI 场景下才需要手动设置。

AWS 凭证（Bedrock）#

当使用 authType: "environment" 的 AWS Bedrock 时，子进程会继承来自 shell 的标准 AWS 环境变量：

export AWS_ACCESS_KEY_ID="AKIA..."
export AWS_SECRET_ACCESS_KEY="..."
export AWS_SESSION_TOKEN="..." # 可选，用于 STS 临时凭证
export AWS_REGION="us-east-1" # 或在连接配置中设置 awsRegion
export AWS_PROFILE="my-profile" # 使用 ~/.aws/credentials 中的命名配置

这些遵循标准的 AWS SDK 凭证链——~/.aws/credentials、SSO 会话、IAM 角色和实例配置文件都有效。

使用 authType: "iam_credentials" 时，凭证在 UI 中输入并自动注入子进程。此情况下无需设置这些环境变量。

XIANTONG_CONFIG_DIR#

覆盖默认配置目录。默认情况下，xiantong 将配置存储在 ~/.xiantong/。

export XIANTONG_CONFIG_DIR="/custom/path/to/config"

这会影响以下位置：

config.json
preferences.json
credentials.enc
工作区配置

XIANTONG_LOCAL_MCP_ENABLED#

启用或禁用本地 MCP 服务器支持（stdio 子进程服务器）。

export XIANTONG_LOCAL_MCP_ENABLED="false"

值	行为
`"true"`	启用本地 MCP 服务器（未设置时默认）
其他任意值	禁用本地 MCP 服务器

该变量要求使用全小写字符串 "true" 才能启用。像 "True"、"TRUE"、"yes" 或 "1" 将视为禁用。

此项也可以在工作区设置中逐个配置。

XIANTONG_DEBUG#

启用调试日志以便排查问题。设置后，日志文件会写入更多诊断信息。

export XIANTONG_DEBUG="true"

服务器模式变量#

这些变量用于在独立或嵌入模式下运行远程服务器。

XIANTONG_SERVER_TOKEN#

服务器认证的 Bearer 令牌。服务器和客户端均需。

export XIANTONG_SERVER_TOKEN=$(openssl rand -hex 32)

XIANTONG_SERVER_URL#

客户端连接的服务器 URL。在客户端设置此项以连接远程服务器。

export XIANTONG_SERVER_URL=wss://your-server:9100

XIANTONG_RPC_HOST#

服务器的绑定地址。默认为 127.0.0.1（仅限本地）。设置为 0.0.0.0 可接受远程连接。

export XIANTONG_RPC_HOST=0.0.0.0

XIANTONG_RPC_PORT#

服务器端口。默认 9100。

export XIANTONG_RPC_PORT=9100

XIANTONG_RPC_TLS_CERT / XIANTONG_RPC_TLS_KEY#

用于 TLS 的 PEM 证书和私钥文件。远程连接（wss://）需要。开发 localhost 时可省略。

export XIANTONG_RPC_TLS_CERT=/path/to/cert.pem
export XIANTONG_RPC_TLS_KEY=/path/to/key.pem

XIANTONG_RPC_TLS_CA#

可选的自定义证书颁发机构的 PEM CA 链文件。

export XIANTONG_RPC_TLS_CA=/path/to/ca.pem

开发变量#

这些变量主要用于开发和多实例场景。

XIANTONG_VITE_PORT#

覆盖 Vite 开发服务器端口。运行于编号实例文件夹时会自动设置。

export XIANTONG_VITE_PORT="5173"

XIANTONG_APP_NAME#

覆盖应用显示名称。用于区分多个实例。

export XIANTONG_APP_NAME="xiantong [Dev]"

XIANTONG_INSTANCE_NUMBER#

多实例支持的实例标识。设置后会在 Dock 图标上添加徽章。

export XIANTONG_INSTANCE_NUMBER="1"

XIANTONG_DEEPLINK_SCHEME#

自定义深度链接 URL 方案。默认值为 xiantong。

export XIANTONG_DEEPLINK_SCHEME="xiantong1"

VITE_DEV_SERVER_URL#

Vite 开发服务器的 URL。开发过程中内部使用。

export VITE_DEV_SERVER_URL="http://localhost:5173"

优先级#

对于 API 凭证，查找顺序为：

XIANTONG_ANTHROPIC_API_KEY 或 ANTHROPIC_API_KEY 环境变量
XIANTONG_CLAUDE_OAUTH_TOKEN 环境变量（用于 OAuth）
存储在 ~/.xiantong/credentials.enc 中的凭证
（若以交互方式运行）交互提示

对于 API 基础 URL：

ANTHROPIC_BASE_URL 环境变量
连接基础 URL（在 LLM 连接中配置）
默认值 (https://api.anthropic.com)

对于模型选择：

LLM 连接默认模型（若设置）
应用级模型默认值（按提供商）
系统默认（Claude Sonnet）

对于配置目录：

XIANTONG_CONFIG_DIR 环境变量
默认 ~/.xiantong/

使用示例#

CI/CD 管道#

#!/bin/bash
export ANTHROPIC_API_KEY="${SECRETS_ANTHROPIC_KEY}"

xiantong -w "Work" -p "Generate release notes from recent commits"

Docker 容器#

ENV ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}
ENV XIANTONG_CONFIG_DIR=/app/config

CMD ["xiantong", "-w", "default", "-p", "..."]

临时覆盖#

为单个命令使用不同的 API 密钥：

ANTHROPIC_API_KEY="sk-ant-different-key" xiantong -p "Quick check"

自定义配置目录#

export XIANTONG_CONFIG_DIR="/home/user/.config/xiantong"
xiantong -p "Using custom config location"

安全说明#

避免将 API 密钥直接写入 shell 历史或脚本。请使用密钥管理器或安全的环境注入。

安全替代方案：

# 从文件读取
export ANTHROPIC_API_KEY=$(cat ~/.secrets/anthropic-key)

# 从密钥管理器读取
export ANTHROPIC_API_KEY=$(aws secretsmanager get-secret-value --secret-id anthropic-key --query SecretString --output text)

# 使用 .env 文件（不提交到 git）
source .env && xiantong -p "..."