Skill Seekers 环境变量完全参考：配置、优先级与实战场景详解

• 人工智能
• AI 应用
• AI 技能
• RAG
• MCP 服务
• 网页爬虫

版本：3.7.0（本文基于当前仓库docs/zh-CN/reference/ENVIRONMENT_VARIABLES.md与源码实现整理）

导读

环境变量是 Skill Seekers 的核心配置入口之一：它承载 API 身份验证（Claude、Gemini、OpenAI、Moonshot、GitHub）、配置路径、输出目录、抓取行为、增强行为、调试开关以及 MCP 服务器设置。本文以官方环境变量参考文档为骨架，逐项说明每个变量的用途、默认值、格式与使用场景，并结合仓库源码（如 agent_client.py 中的API_PROVIDERS注册表与超时映射逻辑）解释其底层工作原理，最后给出开发、生产、CI/CD 与多平台四种典型配置示例。读完本文，你将能够熟练地为 Skill Seekers 配置认证、调整抓取与增强行为、接入任意 OpenAI 兼容提供商，并避开常见的优先级与路径陷阱。

概述

Skill Seekers 使用环境变量来实现：

• API 身份验证（Claude、Gemini、OpenAI、GitHub）
• 配置路径
• 输出目录
• 行为自定义
• 调试设置

这些变量在运行时被读取，并覆盖默认设置（命令行标志仍拥有最高优先级，见文末「优先级顺序」一节）。仓库源码中大量使用os.environ.get(...)在运行时读取这些变量，例如 agent_client.py 中的get_provider_api_keys()与detect_api_target()就是直接从环境变量推导可用提供商与 API 密钥的。

API 密钥

ANTHROPIC_API_KEY

用途：Claude AI API 访问，用于增强和上传。

格式：sk-ant-api03-...

使用者：

• skill-seekers enhance（API 模式）
• skill-seekers upload（Claude 目标）
• AI 增强功能
• 视频场景处理（见 video_scraper.py）

示例：

export ANTHROPIC_API_KEY=sk-ant-api03-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

替代方式：在每个命令中使用--api-key标志。

注意：从源码看，enhance_skill.py 在读取ANTHROPIC_API_KEY时还会回退到ANTHROPIC_AUTH_TOKEN，即 Anthropic 的两种凭据形式都被支持。

GOOGLE_API_KEY

用途：Google Gemini API 访问，用于上传（以及增强/视觉处理）。

格式：AIza...

使用者：

• skill-seekers upload（Gemini 目标）
• 支持图片输入的提供商之一（supports_images: True，见 agent_client.py）

示例：

export GOOGLE_API_KEY=AIzaSyxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

OPENAI_API_KEY

用途：OpenAI（以及 OpenAI 兼容）API 访问，用于增强、上传和 embeddings。

格式：sk-...

使用者：

• skill-seekers create/scan/enhance（AI 增强，API 模式）
• skill-seekers upload（OpenAI 目标）
• 向量数据库的 embedding 生成（参见 adaptors/base.py）

示例：

export OPENAI_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

与OPENAI_BASE_URL+OPENAI_MODEL配合使用，可将增强请求路由到任意 OpenAI 兼容提供商（OpenRouter、Groq、Cerebras、Mistral、NVIDIA NIM）。参见下文「LLM 提供商选择」。

MOONSHOT_API_KEY

用途：Moonshot AI（Kimi）API 访问，用于增强（API 模式）。

格式：sk-...

使用者：

• skill-seekers create/scan/enhance（增强，Kimi/Moonshot）

示例：

export MOONSHOT_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

易混淆点：Moonshot 密钥同样以sk-开头，若同时设置了OPENAI_API_KEY可能被误判。此时应使用SKILL_SEEKER_PROVIDER=moonshot强制指定（详见「增强设置」一节）。另外从 agent_client.py 可以看到，Moonshot 走的是anthropic线协议（protocol: "anthropic"），且不支持图片输入。

GITHUB_TOKEN

用途：GitHub API 身份验证，用于获得更高的速率限制，以及提交社区注册表配置。

格式：ghp_...（个人访问令牌）或github_pat_...（细粒度令牌）

使用者：

• skill-seekers create（GitHub 仓库）
• skill-seekers create --config（统一多源）
• skill-seekers scan（本地代码库）
• skill-seekers scan—— 向社区注册表提交 AI 生成的配置时必需（扫描本身无需该令牌即可运行；只是发布提示会被跳过并给出提示信息）

好处：

• 每小时 5000 次请求（未认证为 60 次）
• 访问私有仓库
• 更高的 GraphQL API 限额
• 允许从scan打开社区配置 GitHub issue

示例：

export GITHUB_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

从源码看，scan_command.py、github_fetcher.py 与 github_scraper.py 都会读取GITHUB_TOKEN；config_manager.py 也用它来拉取社区配置。创建令牌请前往 GitHub 设置页面的 Personal Access Tokens 区域。

平台配置

ANTHROPIC_BASE_URL

用途：自定义 Claude API 端点。

默认值：https://api.anthropic.com

使用场景：代理服务器、企业部署、区域端点。

示例：

export ANTHROPIC_BASE_URL=https://custom-api.example.com

源码中的AgentClient在构造时即会读取该变量（agent_client.py），因此它对所有经由AgentClient的 Claude 调用全局生效。

OPENAI_BASE_URL

用途：用于增强的自定义 OpenAI 兼容 API 端点。

默认值：https://api.openai.com/v1

使用场景：任意 OpenAI 兼容提供商 —— OpenRouter、Groq、Cerebras、Mistral、NVIDIA NIM、本地服务器（Ollama、vLLM、LM Studio）、代理。

示例：

export OPENAI_BASE_URL=https://openrouter.ai/api/v1

由 OpenAI SDK 自动读取。请与OPENAI_API_KEY和OPENAI_MODEL配对使用（否则默认模型gpt-4o在其他提供商上通常不存在）。

LLM 提供商选择

AI增强步骤（create、scan、enhance）通过一个抽象层（AgentClient—— 每次 API 增强调用都经由它路由）支持多个提供商。

提供商的自动检测与优先级

提供商由找到的第一个API 密钥决定，顺序按照cli/agent_client.py中API_PROVIDERS注册表的定义：

ANTHROPIC_API_KEY→ANTHROPIC_AUTH_TOKEN→GOOGLE_API_KEY→OPENAI_API_KEY→MOONSHOT_API_KEY

从源码看，agent_client.py 中的API_PROVIDERS是一个有序元组注册表，每个条目声明了provider（提供商名）、target（CLI/适配器使用的平台名）、env_vars（对应的环境变量）、protocol（线上协议）与supports_images（是否支持图片输入）；detect_api_target()（agent_client.py）按注册表顺序返回第一个设置了密钥的目标。注册表目前还包含minimax（通过MINIMAX_API_KEY启用，支持区域与协议覆盖），enhance_command的模式选择与enhance_skill_local的目标检测均消费该注册表——这也是文档中"单一事实来源"的设计。

如果所有密钥均未设置，则回退到LOCAL 代理模式（--agent，无需 API 密钥 —— 使用你的 Claude Pro / ChatGPT Plus 订阅）。

当密钥前缀有歧义时（Moonshot 密钥同样以sk-开头，可能被误判为 OpenAI），可通过将SKILL_SEEKER_PROVIDER设置为anthropic、google、openai、moonshot（别名：kimi）来强制指定提供商：

export SKILL_SEEKER_PROVIDER=moonshot

对应源码实现位于 agent_client.py，它会把强制指定的提供商名规范化（kimi→moonshot），并据此完成客户端初始化。

任意 OpenAI 兼容提供商（OpenRouter、Groq、Cerebras、Mistral、NVIDIA NIM）

export OPENAI_API_KEY="<provider key>" export OPENAI_BASE_URL="https://api.groq.com/openai/v1" # provider endpoint export OPENAI_MODEL="llama-3.3-70b-versatile" # a model that provider offers skill-seekers create <source>

请务必设置OPENAI_MODEL—— OpenAI 的默认模型（gpt-4o）在其他提供商上不存在。 确保没有设置更高优先级的密钥（如ANTHROPIC_API_KEY），否则它会胜出。

使用订阅而非 API 额度（LOCAL 模式）

skill-seekers create <source> --agent codex # ChatGPT Plus via Codex CLI skill-seekers create <source> --agent claude # Claude Pro/Max via Claude Code

LOCAL 模式下增强实际由本地编码代理 CLI 完成，可通过SKILL_SEEKER_AGENT指定默认代理、SKILL_SEEKER_AGENT_CMD自定义命令模板（详见「增强设置」）。

路径与目录

SKILL_SEEKERS_HOME

用途：Skill Seekers 数据的基础目录。

默认值：

• Linux/macOS：~/.config/skill-seekers/
• Windows：%APPDATA%\skill-seekers\

用于：

• 配置文件
• 工作流预设
• 缓存数据
• 检查点

示例：

export SKILL_SEEKERS_HOME=/opt/skill-seekers

对应源码可参考 config_manager.py：Windows 下使用APPDATA环境变量推导基础目录，进度文件则存放在LOCALAPPDATA下的progress目录。

SKILL_SEEKERS_OUTPUT

用途：技能的默认输出目录。

默认值：./output/

使用者：

• 所有抓取命令
• 打包输出
• 技能生成

示例：

export SKILL_SEEKERS_OUTPUT=/var/skills/output

SKILL_SEEKERS_CONFIG_DIR

用途：包含预设配置的目录。

默认值：configs/（相对于工作目录）

示例：

export SKILL_SEEKERS_CONFIG_DIR=/etc/skill-seekers/configs

仓库根目录下的 configs/ 目录即此类预设配置的典型示例，其中包含astrovalley_unified.json、blender-unified.json、claude-code-unified.json、godot_unified.json、react.json、unity-addressables.json等按技术栈组织的统一配置。

抓取行为

SKILL_SEEKERS_RATE_LIMIT

用途：HTTP 请求的默认速率限制。

默认值：0.5（秒）

单位：请求之间的间隔秒数

示例：

# More aggressive (faster) export SKILL_SEEKERS_RATE_LIMIT=0.2 # More conservative (slower) export SKILL_SEEKERS_RATE_LIMIT=1.0

覆盖方式：在每个命令中使用--rate-limit标志。

SKILL_SEEKERS_MAX_PAGES

用途：默认的最大抓取页数。

默认值：500

示例：

export SKILL_SEEKERS_MAX_PAGES=1000

覆盖方式：使用--max-pages标志或配置文件。

SKILL_SEEKERS_WORKERS

用途：默认并行工作者数量。

默认值：1

最大值：10

示例：

export SKILL_SEEKERS_WORKERS=4

覆盖方式：使用--workers标志。

SKILL_SEEKERS_TIMEOUT

用途：HTTP 请求超时。

默认值：30（秒）

示例：

# For slow servers export SKILL_SEEKERS_TIMEOUT=60

SKILL_SEEKERS_USER_AGENT

用途：自定义 User-Agent 请求头。

默认值：Skill-Seekers/3.7.0

示例：

export SKILL_SEEKERS_USER_AGENT="MyBot/1.0 (contact@example.com)"

提示：部分站点会拦截默认 UA，设置一个带联系方式的自定义 UA 有助于提升抓取成功率与合规性。

增强设置

SKILL_SEEKER_AGENT

用途：用于增强以及 scan 检测/生成的默认本地编码代理。

默认值：claude

可选值：claude、codex、copilot、opencode、kimi、custom，以及 IDE 模式别名（cursor、windsurf、cline、continue）

使用者：

• skill-seekers enhance
• skill-seekers scan（可在单次调用中通过--agent覆盖）

示例：

export SKILL_SEEKER_AGENT=cursor

源码中该变量的读取点非常多：enhance_command.py（L272/L300）、enhance_skill_local.py（L173）、execution_context.py（L328）、unified_scraper.py（L2175）以及多个 argument 定义文件（如 create.py）的 help 文本。解析优先级为「命令行参数 → 环境变量 → 默认值claude」。

SKILL_SEEKER_AGENT_CMD

用途：--agent custom（LOCAL 模式）的自定义 CLI 命令模板。

使用者：当SKILL_SEEKER_AGENT=custom时的skill-seekers create/scan/enhance。

示例：

export SKILL_SEEKER_AGENT=custom export SKILL_SEEKER_AGENT_CMD="my-llm-cli --prompt-file {prompt_file}"

若选择了custom但未设置该变量，源码会输出警告（agent_client.py 与 enhance_skill_local.py），提示Custom agent requires --agent-cmd or SKILL_SEEKER_AGENT_CMD to be set.。模板中的{prompt_file}占位符会被替换为实际的提示文件路径。

SKILL_SEEKER_PROVIDER

用途：当密钥前缀检测有歧义时强制指定 API 提供商（Moonshot 密钥同样以sk-开头，否则会被识别为 OpenAI）。

可选值：anthropic、google、openai、moonshot（别名：kimi）

示例：

export SKILL_SEEKER_PROVIDER=moonshot

SKILL_SEEKER_MODEL

用途：API 模式增强的全局模型覆盖（优先于下方所有按提供商的模型变量）。

示例：

export SKILL_SEEKER_MODEL=llama-3.3-70b-versatile

源码实现位于 agent_client.py：先读取SKILL_SEEKER_MODEL，未设置时才回退到各提供商专属的模型环境变量。

按提供商的模型覆盖

仅在未设置SKILL_SEEKER_MODEL时使用。每个变量都会回退到对应提供商的默认值。

export OPENAI_MODEL=llama-3.3-70b-versatile

上述默认模型列表与 agent_client.py 中的DEFAULT_MODELS映射一致。

SKILL_SEEKER_ENHANCE_TIMEOUT

用途：AI 增强操作的超时时间（秒）。

默认值：2700（45 分钟）

特殊值：unlimited、none或0会映射为 24 小时上限。

示例：

# For large skills export SKILL_SEEKER_ENHANCE_TIMEOUT=3600 # No practical limit export SKILL_SEEKER_ENHANCE_TIMEOUT=unlimited

源码中get_default_timeout()（agent_client.py）实现了这套映射：unlimited/none/0及非正数值统一返回UNLIMITED_TIMEOUT = 86400（24 小时），无法解析的非法值回退到DEFAULT_ENHANCE_TIMEOUT = 2700。之所以有 24 小时上限，是因为底层 subprocess 需要一个有限数值。

SKILL_SEEKER_ENHANCE_ACTIVE

用途：LOCAL 代理增强的递归保护。Skill Seekers 会在它生成的每个本地代理的环境中将此变量设置为1（所有生成路径都如此）；当该变量已被设置时，LOCAL 增强会拒绝再生成嵌套代理。通常你不需要自己设置它 —— 仅当你将 Skill Seekers 包装在另一个代理内、且希望抑制增强时才需要。

示例：

export SKILL_SEEKER_ENHANCE_ACTIVE=1 # suppress nested local-agent spawns

源码在 agent_client.py 与 enhance_skill_local.py 两处检查该变量是否为"1"，从而阻止嵌套的本地代理生成，避免代理递归失控。

GitHub 配置

GITHUB_API_URL

用途：自定义 GitHub API 端点。

默认值：https://api.github.com

使用场景：GitHub Enterprise Server。

示例：

export GITHUB_API_URL=https://github.company.com/api/v3

GITHUB_ENTERPRISE_TOKEN

用途：GitHub Enterprise 的独立令牌。

使用场景：为 github.com 和企业实例使用不同的令牌。

示例：

export GITHUB_TOKEN=ghp_... # github.com export GITHUB_ENTERPRISE_TOKEN=... # enterprise

这一组变量让同一套配置可以同时对接 GitHub 公共实例与企业私有实例，是混合办公/内网部署的常见做法。

向量数据库设置

以下变量服务于技能上传到向量数据库的场景（skill-seekers upload --target <db>以及对应的 MCP 导出工具）。

CHROMA_URL

用途：ChromaDB 服务器 URL。

默认值：http://localhost:8000

使用者：

• skill-seekers upload --target chroma
• export_to_chromaMCP 工具

示例：

export CHROMA_URL=http://chroma.example.com:8000

CHROMA_PERSIST_DIRECTORY

用途：ChromaDB 持久化的本地目录。

默认值：./chroma_db/

示例：

export CHROMA_PERSIST_DIRECTORY=/var/lib/chroma

WEAVIATE_URL

用途：Weaviate 服务器 URL。

默认值：http://localhost:8080

使用者：

• skill-seekers upload --target weaviate
• export_to_weaviateMCP 工具

示例：

export WEAVIATE_URL=https://weaviate.example.com

WEAVIATE_API_KEY

用途：用于身份验证的 Weaviate API 密钥。

使用者：

• Weaviate Cloud
• 启用认证的 Weaviate 实例

示例：

export WEAVIATE_API_KEY=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

QDRANT_URL

用途：Qdrant 服务器 URL。

默认值：http://localhost:6333

示例：

export QDRANT_URL=http://qdrant.example.com:6333

QDRANT_API_KEY

用途：用于身份验证的 Qdrant API 密钥。

示例：

export QDRANT_API_KEY=xxxxxxxxxxxxxxxx

仓库同时提供了这些向量数据库的端到端示例脚本，例如 examples/qdrant-example/、examples/weaviate-example/ 与 examples/chroma-example/，可配合上述变量直接运行参考。

调试与开发

SKILL_SEEKERS_DEBUG

用途：启用调试日志。

可选值：1、true、yes

等效于：--verbose标志

示例：

export SKILL_SEEKERS_DEBUG=1

SKILL_SEEKERS_LOG_LEVEL

用途：设置日志级别。

默认值：INFO

可选值：DEBUG、INFO、WARNING、ERROR、CRITICAL

示例：

export SKILL_SEEKERS_LOG_LEVEL=DEBUG

SKILL_SEEKERS_LOG_FILE

用途：将日志写入文件而非 stdout。

示例：

export SKILL_SEEKERS_LOG_FILE=/var/log/skill-seekers.log

SKILL_SEEKERS_CACHE_DIR

用途：自定义缓存目录。

默认值：~/.cache/skill-seekers/

示例：

export SKILL_SEEKERS_CACHE_DIR=/tmp/skill-seekers-cache

源码中的 services/git_repo.py 会读取SKILL_SEEKERS_CACHE_DIR作为 Git 仓库缓存的基础目录，未设置时回退到平台默认缓存位置。

SKILL_SEEKERS_NO_CACHE

用途：禁用缓存。

可选值：1、true、yes

示例：

export SKILL_SEEKERS_NO_CACHE=1

这一开关在 CI/CD 中尤为有用，可确保每次构建都是全新抓取，避免缓存导致的过期数据。

MCP 服务器设置

以下变量控制 Skill Seekers MCP 服务器的传输模式与监听地址（对应 src/skill_seekers/mcp/ 目录下的服务实现）。

MCP_TRANSPORT

用途：默认的 MCP 传输模式。

默认值：stdio

可选值：stdio、http

示例：

export MCP_TRANSPORT=http

覆盖方式：使用--transport标志。

MCP_PORT

用途：默认的 MCP HTTP 端口。

默认值：8765

示例：

export MCP_PORT=8080

覆盖方式：使用--port标志。

MCP_HOST

用途：默认的 MCP HTTP 主机。

默认值：127.0.0.1

示例：

export MCP_HOST=0.0.0.0

覆盖方式：使用--host标志。

安全提示：0.0.0.0会让 MCP 服务监听所有网络接口，仅在受信网络或配合鉴权时使用。更多 MCP 使用细节可参阅 docs/zh-CN/advanced/mcp-server.md。

示例

开发环境

# Debug mode export SKILL_SEEKERS_DEBUG=1 export SKILL_SEEKERS_LOG_LEVEL=DEBUG # Custom paths export SKILL_SEEKERS_HOME=./.skill-seekers export SKILL_SEEKERS_OUTPUT=./output # Faster scraping for testing export SKILL_SEEKERS_RATE_LIMIT=0.1 export SKILL_SEEKERS_MAX_PAGES=50

生产环境

# API keys export ANTHROPIC_API_KEY=sk-ant-... export GITHUB_TOKEN=ghp_... # Custom output directory export SKILL_SEEKERS_OUTPUT=/var/www/skills # Conservative scraping export SKILL_SEEKERS_RATE_LIMIT=1.0 export SKILL_SEEKERS_WORKERS=2 # Logging export SKILL_SEEKERS_LOG_FILE=/var/log/skill-seekers.log export SKILL_SEEKERS_LOG_LEVEL=WARNING

CI/CD 环境

# Non-interactive export SKILL_SEEKERS_LOG_LEVEL=ERROR # API keys from secrets export ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY_SECRET} export GITHUB_TOKEN=${GITHUB_TOKEN_SECRET} # Fresh runs (no cache) export SKILL_SEEKERS_NO_CACHE=1

多平台设置

# All API keys export ANTHROPIC_API_KEY=sk-ant-... export GOOGLE_API_KEY=AIza... export OPENAI_API_KEY=sk-... export GITHUB_TOKEN=ghp_... # Vector databases export CHROMA_URL=http://localhost:8000 export WEAVIATE_URL=http://localhost:8080 export WEAVIATE_API_KEY=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

配置文件

环境变量也可以在.env文件中设置：

# .env file ANTHROPIC_API_KEY=sk-ant-... GITHUB_TOKEN=ghp_... SKILL_SEEKERS_OUTPUT=./output SKILL_SEEKERS_RATE_LIMIT=0.5

加载方式：

# Automatically loaded if python-dotenv is installed # Or manually: export $(cat .env | xargs)

若使用export $(cat .env | xargs)手动加载，注意.env中不要出现带空格或特殊字符的值（或改用引号包裹），否则会被 shell 拆分。

优先级顺序

设置按以下顺序应用（后者覆盖前者）：

1. 默认值
2. 环境变量
3. 配置文件
4. 命令行标志

示例：

# Default: rate_limit = 0.5 export SKILL_SEEKERS_RATE_LIMIT=1.0 # Env var overrides default # Config file: rate_limit = 0.2 # Config overrides env skill-seekers create --rate-limit 2.0 # Flag overrides all

这一优先级模型与 docs/zh-CN/reference/CONFIG_FORMAT.md 中描述的 JSON 配置格式互补：环境变量适合部署级覆盖，配置文件适合项目级默认值，命令行标志则用于单次执行的一次性覆盖。

安全最佳实践

切勿提交 API 密钥

# Add to .gitignore echo ".env" >> .gitignore echo "*.key" >> .gitignore

使用密钥管理

# macOS Keychain export ANTHROPIC_API_KEY=$(security find-generic-password -s "anthropic-api" -w) # Linux Secret Service (with secret-tool) export ANTHROPIC_API_KEY=$(secret-tool lookup service anthropic) # 1Password CLI export ANTHROPIC_API_KEY=$(op read "op://vault/anthropic/credential")

文件权限

# Restrict .env file chmod 600 .env

在 CI/CD 中，优先使用平台的 Secret 管理能力注入环境变量（如示例中的${ANTHROPIC_API_KEY_SECRET}），避免将密钥写入仓库或构建日志。

故障排除

变量未被识别

# Check if set echo $ANTHROPIC_API_KEY # Check in Python python -c "import os; print(os.getenv('ANTHROPIC_API_KEY'))"

优先级问题

# See effective configuration skill-seekers config --show

config --show会展示当前生效的配置合并结果，是排查"环境变量为何没生效"的第一手段。

路径展开

# Use full path or expand tilde export SKILL_SEEKERS_HOME=$HOME/.skill-seekers # NOT: ~/.skill-seekers (may not expand in all shells)

在部分 shell（尤其是非交互式脚本环境）中~不会被展开，务必使用$HOME或绝对路径。

另请参阅

• CLI 参考 - 命令参考
• 配置格式 - JSON 配置
• 安装指南 - 平台相关的设置
• MCP 服务器 - MCP 传输与部署细节
• 环境变量参考（英文原版） - 英文版参考文档

本文中的默认值与优先级行为以仓库源码（尤其是 src/skill_seekers/cli/agent_client.py）与官方文档为准，适用于 Skill Seekers 3.7.0。

• 人工智能
• AI 应用
• AI 技能
• RAG
• MCP 服务
• 网页爬虫