xiantong 文档
配置

凭证

xiantong 如何安全存储敏感数据

xiantong 将 API 密钥、OAuth 令牌及其他敏感凭证存储在本机的加密文件中。

位置#

~/.xiantong/credentials.enc

加密#

凭证采用以下方式加密：

  • 算法：AES-256-GCM
  • 密钥派生：带有机器特定种子的 PBKDF2
  • 安全模型：与操作系统密钥链相同的保护级别，无需交互提示

加密密钥由机器特定标识符派生，意味着凭证文件只能在创建它的同一台机器上解密。

键格式#

凭证存储时，其键的格式取决于范围：全局凭证（2 部分键）：

{type}::global

来源凭证（3 部分键）：

{type}::{workspaceId}::{sourceId}

LLM 连接凭证（2 部分键）：

{type}::{connectionSlug}

其中 type 表示凭证类型，workspaceId 是工作区 UUID，sourceId 是来源标识符。

凭证类型#

类型描述范围
anthropic_api_keyAI 提供商（Anthropic、OpenRouter、Vercel 或自定义）的 API 密钥全局
claude_oauthClaude OAuth 令牌（Pro/Max 订阅）全局
llm_api_keyLLM 连接的 API 密钥每个连接
llm_oauthLLM 连接的 OAuth 令牌每个连接
llm_iam用于 Bedrock 的 AWS IAM 凭证每个连接
llm_service_accountVertex 的 GCP 服务账号 JSON每个连接
source_oauth来源 OAuth 令牌每个来源
source_bearer来源承载令牌每个来源
source_apikey来源 API 密钥每个来源
source_basic来源基本认证每个来源

anthropic_api_key 与 claude_oauth 是遗留的全局凭证。新安装将凭证存储在各自的 LLM 连接下。

示例#

anthropic_api_key::global
claude_oauth::global
llm_api_key::anthropic-api
llm_oauth::claude-max
llm_iam::bedrock
source_oauth::ws-abc123::github
source_bearer::ws-abc123::api-service

凭证范围#

凭证分两个层级范围：

LLM 连接（2 部分键）
llm_api_key::anthropic-api
llm_oauth::claude-max

来源（3 部分键：type::workspaceId::sourceId）
source_oauth::ws-abc123::github
source_bearer::ws-abc123::exa

这表示：

  • LLM 连接凭证与特定的连接 slug 绑定
  • 来源凭证针对工作区内的某个来源，采用 3 部分键格式

遗留的全局凭证会自动迁移至 LLM 连接凭证：

  • anthropic_api_key::global → llm_api_key::anthropic-api
  • claude_oauth::global → llm_oauth::claude-max

查看已存凭证#

可以查看已存凭证（但不能查看其值）：

> /debug

会显示凭证标识，例如：

Credentials:
anthropic_api_key::global
source_oauth::ws-abc123::github

管理凭证#

添加凭证#

以下操作会自动添加凭证：

  • 完成设置向导（API 密钥或 OAuth）
  • 连接需要身份验证的来源
  • 与 MCP 服务器进行身份验证

删除凭证#

要清除所有凭证，请删除凭证文件：

rm ~/.xiantong/credentials.enc

这会移除所有已存凭证。下次启动时需重新验证。

安全注意事项#

文件权限

凭证文件以受限权限创建（仅用户自己可读）。可通过以下命令验证：

ls -la ~/.xiantong/credentials.enc
# 应显示 -rw-------

备份注意事项

如果备份主目录，凭证文件虽会被包含但已加密。在其他机器上无法解密。

机器迁移

迁移到新机器时需要重新输入凭证。旧机器上的加密文件无法使用。

共享账户

多个用户共享系统账户时会共享同一凭证文件。建议使用独立用户账户以确保隔离。

环境变量覆盖#

在自动化或 CI 环境中，可以通过环境变量提供凭证：

变量用途
ANTHROPIC_API_KEYAnthropic API 密钥
XIANTONG_ANTHROPIC_API_KEYAnthropic API 密钥（优先于 ANTHROPIC_API_KEY）
XIANTONG_CLAUDE_OAUTH_TOKENClaude OAuth 令牌（用于 Claude Max 订阅）

环境变量优先于存储的凭证。

疑难解答#

凭证未找到错误

凭证可能已被删除或损坏。请重新输入：

  • API 密钥：打开设置并重新输入密钥
  • OAuth：在提示时重新验证

无法解密凭证

通常表示文件从另一台机器复制而来。删除凭证文件并重新输入凭证：

rm ~/.xiantong/credentials.enc

文件权限错误

修复权限：

chmod 600 ~/.xiantong/credentials.enc
上一页配置文件