人工智能AI Agent代码智能体Agent 编排CLIAI 应用【免费下载链接】gsd-2A powerful meta-prompting, context engineering and spec-driven development system that enables agents to work for long periods of time autonomously without losing track of the big picture项目地址https://gitcode.com/gh_mirrors/gs/gsd-2点击查看免费下载本文是 GSDGitHub 加速计划 gs/gsd-2的 LLM Provider 配置指南覆盖 Anthropic、OpenAI、Google Gemini、OpenRouter、Groq、xAI、Mistral、GitHub Copilot、Amazon Bedrock、Vertex AI、Azure OpenAI 等内置云端厂商以及 Ollama、LM Studio、vLLM、SGLang 等本地推理引擎的完整接入流程。读完本文你将掌握gsd config引导式配置、环境变量与~/.gsd/agent/models.json手工配置、compat兼容项调优、/model会话内切换模型以及常见鉴权与协议兼容性问题的排查方法。一、配置总览与快速参考GSD 支持三类 Provider 接入方式内置云端 ProviderBuilt-in Providers模型已预注册在 GSD 中只需提供 API Key 等凭据即可使用典型如 Anthropic、OpenAI、OpenRouter本地 ProviderLocal Providers运行在本机上的推理服务Ollama、LM Studio、vLLM、SGLang必须通过~/.gsd/agent/models.json告知 GSD 端点地址与可用模型自定义 OpenAI 兼容端点Custom OpenAI-Compatible Endpoints任何实现了 OpenAI Chat Completions API 的服务端LiteLLM、Portkey、Helicone 代理、自托管推理等都可接入。如果你运行过引导向导gsd config并选择了 Provider通常已完成配置——在会话内用/model即可校验。快速参考表Provider认证方式环境变量配置文件AnthropicAPI keyANTHROPIC_API_KEY—OpenAIAPI keyOPENAI_API_KEY—Google GeminiAPI keyGEMINI_API_KEY—OpenRouterAPI keyOPENROUTER_API_KEY可选models.jsonGroqAPI keyGROQ_API_KEY—xAIAPI keyXAI_API_KEY—MistralAPI keyMISTRAL_API_KEY—GitHub CopilotOAuthGH_TOKEN—Amazon BedrockIAM 凭据AWS_PROFILE或AWS_ACCESS_KEY_ID—Vertex AIADCGOOGLE_APPLICATION_CREDENTIALS—Azure OpenAIAPI keyAZURE_OPENAI_API_KEY—Ollama无本地—models.json必需LM Studio无本地—models.json必需vLLM / SGLang无本地—models.json必需从源码看环境变量到 Provider 的映射集中定义在 packages/pi-ai/src/env-api-keys.ts 的envMap中getEnvApiKey()负责解析github-copilot会优先读取COPILOT_GITHUB_TOKENanthropic会优先读取ANTHROPIC_OAUTH_TOKEN并对 Bedrock、Vertex 等使用 ADC / IAM 的 Provider 做了多来源检测。此外 packages/pi-coding-agent/src/config.ts 定义了~/.gsd/agent/models.json与~/.gsd/agent/auth.json等配置路径默认用户目录随 HOME 而定。二、内置云端 Provider 配置内置 Provider 的模型已预注册你只需提供凭据。以下每个小节给出推荐的环境变量写法与gsd config交互式配置路径。Anthropic (Claude)推荐首选。Anthropic 模型拥有最深的集成内置 Web Search、扩展思考extended thinking与提示词缓存prompt caching。方式 A —— API Key推荐export ANTHROPIC_API_KEYsk-ant-...或运行gsd config并在提示时粘贴密钥。可在 console.anthropic.com/settings/keys 获取密钥。方式 B —— Claude Code CLI拥有 Claude Pro 或 Max 订阅时可通过 Anthropic 官方 Claude Code CLI 认证。安装后执行claude登录随后启动 GSD它会自动检测本机 Claude Code 安装并作为已认证的 Anthropic 通道路由# 安装 Claude Code CLI参见 https://docs.anthropic.com/en/docs/claude-code claude # 按提示登录然后启动 GSD gsd这是订阅用户符合 ToS 的接入路径——GSD 从不直接处理你的订阅凭据。源码层面Claude Code CLI 由claude-code扩展实现通过pi.registerProvider(claude-code, ...)注册 ProviderbaseUrl为local://claude-code并基于 Anthropic 官方anthropic-ai/claude-agent-sdk实现见 src/resources/extensions/claude-code-cli/index.ts。注意GSD 不支持基于浏览器的 OAuth 登录 Anthropic请使用 API Key 或 Claude Code CLI。方式 C —— 在 Claude Code 内通过 MCP 使用 GSD如果你已有 Claude Pro/Max 订阅希望在 Claude Code 里直接使用 GSD 的规划、执行与里程碑编排能力可将 GSD 作为 MCP Server 接入 Claude Code。这样 Claude Code 可通过 Model Context Protocol 获得 GSD 的完整工作流工具集。自动配置推荐当 GSD 在启动时检测到 Claude Code 模型会自动在项目根目录写入.mcp.json内置 GSD workflow MCP Server 配置无需手工操作。也可在 GSD 会话内手动触发/gsd mcp init该命令会写入或更新项目.mcp.json中的gsd-workflow条目Claude Code 会在下次会话启动时自动发现。手工配置{ mcpServers: { gsd: { command: npx, args: [gsd-mcp-server], env: { GSD_CLI_PATH: /path/to/gsd } } } }如果gsd-mcp-server已全局安装可简化为{ mcpServers: { gsd: { command: gsd-mcp-server } } }也可将其加入~/.claude/settings.json的mcpServers让 GSD 在所有项目中可用。暴露的能力MCP Server 提供 GSD 完整的工作流工具面——里程碑规划、任务完成、切片管理、路线图重新评估、日志查询等会话管理工具gsd_execute、gsd_status、gsd_result、gsd_cancel让 Claude Code 可以启动并监控 GSD auto 模式会话。完整工具清单参见 Commands → MCP Server Mode。源码侧GSD 以--mode mcp在 stdin/stdout 上运行 MCP 服务docs/user-docs/commands.md命令处理器支持/gsd mcp status|check|test|init等子命令src/resources/extensions/gsd/commands-mcp-status.ts。验证连接在 GSD 会话内执行/gsd mcp status检查 MCP Server 是否可达。OpenAIexport OPENAI_API_KEYsk-...或运行gsd config选择 Paste an API key 后选 OpenAI。可在 platform.openai.com/api-keys 获取密钥。Google Geminiexport GEMINI_API_KEY...可在 aistudio.google.com/app/apikey 获取密钥。OpenRouterOpenRouter 用一个 API Key 聚合多家提供商的 200 模型。Step 1 —— 获取 API Key前往 openrouter.ai/keys 创建密钥。Step 2 —— 设置密钥export OPENROUTER_API_KEYsk-or-...或运行gsd config选择 Paste an API key再选 OpenRouter。Step 3 —— 切换模型在 GSD 会话内输入/model选择 OpenRouter 模型模型 ID 带openrouter/前缀如openrouter/anthropic/claude-sonnet-4。可选 —— 通过models.json添加自定义 OpenRouter 模型若需要不在内置列表中的模型写入~/.gsd/agent/models.json{ providers: { openrouter: { baseUrl: https://openrouter.ai/api/v1, apiKey: OPENROUTER_API_KEY, api: openai-completions, models: [ { id: meta-llama/llama-3.3-70b, name: Llama 3.3 70B (OpenRouter), reasoning: false, input: [text], contextWindow: 131072, maxTokens: 32768, cost: { input: 0.3, output: 0.3, cacheRead: 0, cacheWrite: 0 } } ] } } }注意这里的apiKey字段是环境变量的名字不是字面密钥GSD 会自动解析它。你也可以直接写字面值或用 shell 命令见 Value Resolution。可选 —— 指定上游路由用modelOverrides控制 OpenRouter 使用的上游 Provider{ providers: { openrouter: { modelOverrides: { anthropic/claude-sonnet-4: { compat: { openRouterRouting: { only: [amazon-bedrock] } } } } } } }从源码看OpenRouterRouting支持only仅用指定上游与order按顺序尝试上游其类型定义位于 packages/pi-ai/src/types.ts。Groqexport GROQ_API_KEYgsk_...可在 console.groq.com/keys 获取密钥。xAI (Grok)export XAI_API_KEYxai-...可在 console.x.ai 获取密钥。Mistralexport MISTRAL_API_KEY...可在 console.mistral.ai/api-keys 获取密钥。GitHub Copilot使用 OAuth通过浏览器登录gsd config # 选择 Sign in with your browser → GitHub Copilot需要有效的 GitHub Copilot 订阅。源码中 GitHub Copilot 的凭据解析支持COPILOT_GITHUB_TOKEN、GH_TOKEN、GITHUB_TOKEN三个环境变量packages/pi-ai/src/env-api-keys.ts。Amazon BedrockBedrock 使用 AWS IAM 凭据而非 API Key以下几种任选其一# 方式 1命名 profile export AWS_PROFILEmy-profile # 方式 2IAM keys export AWS_ACCESS_KEY_IDAKIA... export AWS_SECRET_ACCESS_KEY... export AWS_REGIONus-east-1 # 方式 3Bedrock API keybearer token export AWS_BEARER_TOKEN_BEDROCK...ECS task role 与 IRSAKubernetes也会被自动检测——源码中 Bedrock 凭据检测覆盖AWS_PROFILE、IAM keys、AWS_BEARER_TOKEN_BEDROCK、AWS_CONTAINER_CREDENTIALS_RELATIVE_URI、AWS_CONTAINER_CREDENTIALS_FULL_URI、AWS_WEB_IDENTITY_TOKEN_FILE六类来源packages/pi-ai/src/env-api-keys.ts。Anthropic on Vertex AI使用 Google Cloud Application Default Credentialsgcloud auth application-default login export ANTHROPIC_VERTEX_PROJECT_IDmy-project-id或设置GOOGLE_CLOUD_PROJECT并确保 ADC 凭据存在于~/.config/gcloud/application_default_credentials.json。源码层面GSD 会检查ANTHROPIC_VERTEX_PROJECT_ID或GOOGLE_CLOUD_PROJECT/GCLOUD_PROJECT加上 ADC 文件的存在性来判定认证packages/pi-ai/src/env-api-keys.ts。Azure OpenAIexport AZURE_OPENAI_API_KEY...三、本地 Provider 配置本地 Provider 运行在本机必须提供models.json配置文件因为 GSD 需要知道端点 URL 与可用模型。配置文件位置~/.gsd/agent/models.json该文件每次打开/model时都会重新加载——无需重启 GSD。OllamaStep 1 —— 安装并启动 Ollama# macOS brew install ollama ollama serve # 或从 https://ollama.com 下载Step 2 —— 拉取模型ollama pull llama3.1:8b ollama pull qwen2.5-coder:7bStep 3 —— 创建~/.gsd/agent/models.json{ providers: { ollama: { baseUrl: http://localhost:11434/v1, api: openai-completions, apiKey: ollama, compat: { supportsDeveloperRole: false, supportsReasoningEffort: false }, models: [ { id: llama3.1:8b }, { id: qwen2.5-coder:7b } ] } } }apiKey是配置 schema 必需的字段但 Ollama 会忽略它——填任意值即可。Step 4 —— 选择模型在 GSD 内输入/model选择你的 Ollama 模型。Ollama 提示Ollama 不支持developer角色与reasoning_effort——务必设置compat.supportsDeveloperRole: false与compat.supportsReasoningEffort: false若返回空响应检查ollama serve是否运行、模型是否已拉取上下文窗口与最大 token 未指定时默认为 128K / 16K若模型限制不同请覆盖。LM StudioStep 1 —— 安装从 lmstudio.ai 下载。Step 2 —— 启动本地服务在 LM Studio 中打开 Local Server 标签页加载模型并点击 Start Server。默认端口为 1234。Step 3 —— 创建~/.gsd/agent/models.json{ providers: { lm-studio: { baseUrl: http://localhost:1234/v1, api: openai-completions, apiKey: lm-studio, compat: { supportsDeveloperRole: false, supportsReasoningEffort: false }, models: [ { id: your-model-name, name: My Local Model, contextWindow: 32768, maxTokens: 4096 } ] } } }把your-model-name替换为 LM Studio 服务标签页中显示的模型标识。LM Studio 提示models.json中的模型 ID 必须与 LM Studio 服务器 API 报告的完全一致去服务标签页核对字符串LM Studio 默认端口 1234若更改过请同步更新baseUrl若模型支持更大上下文可调大contextWindow与maxTokens。vLLM{ providers: { vllm: { baseUrl: http://localhost:8000/v1, api: openai-completions, apiKey: vllm, compat: { supportsDeveloperRole: false, supportsReasoningEffort: false, supportsUsageInStreaming: false }, models: [ { id: meta-llama/Llama-3.1-8B-Instruct, contextWindow: 128000, maxTokens: 16384 } ] } } }模型id必须与vllm serve的--model参数一致。SGLang{ providers: { sglang: { baseUrl: http://localhost:30000/v1, api: openai-completions, apiKey: sglang, compat: { supportsDeveloperRole: false, supportsReasoningEffort: false }, models: [ { id: meta-llama/Llama-3.1-8B-Instruct } ] } } }四、自定义 OpenAI 兼容端点任何实现 OpenAI Chat Completions API 的服务端都能接入 GSD包括代理LiteLLM、Portkey、Helicone、自托管推理与新 Provider。最快路径 —— 引导向导gsd config # 选择 Paste an API key → Custom (OpenAI-compatible) # 依次输入base URL、API key、模型 ID向导会自动写入~/.gsd/agent/models.json。手工配置{ providers: { my-provider: { baseUrl: https://my-endpoint.example.com/v1, apiKey: MY_PROVIDER_API_KEY, api: openai-completions, models: [ { id: model-id-here, name: Friendly Model Name, reasoning: false, input: [text], contextWindow: 128000, maxTokens: 16384, cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 } } ] } } }为代理添加自定义请求头{ providers: { litellm-proxy: { baseUrl: https://litellm.example.com/v1, apiKey: MY_API_KEY, api: openai-completions, headers: { x-custom-header: value }, models: [...] } } }headers会与 Provider 默认请求头合并可用于覆盖默认头StreamOptions.headers在类型层面同样支持自定义 HTTP 头packages/pi-ai/src/types.ts。Qwen 模型开启思考模式对 Qwen 兼容服务端用thinkingFormat开启思考模式{ compat: { thinkingFormat: qwen, supportsDeveloperRole: false } }若服务端要求chat_template_kwargs.enable_thinking则改用qwen-chat-template。从源码类型看thinkingFormat支持openai | zai | qwen三种取值其中openai用reasoning_effort、zai用thinking: { type: enabled }、qwen用enable_thinking: booleanpackages/pi-ai/src/types.ts仓库内 packages/pi-ai/src/models/custom.ts 中的alibaba-coding-plan、alibaba-dashscope模型正是使用thinkingFormat: qwen的真实案例。compat字段的完整参考、modelOverrides、值解析与高级配置见 Custom Models。五、compat 兼容项速查与原理所有本地与自定义 Provider 的核心在于compat字段。它本质上是OpenAICompletionsCompat类型packages/pi-ai/src/types.ts用来覆盖基于 URL 的自动检测结果字段含义默认行为supportsStore是否支持store字段按 URL 自动检测supportsDeveloperRole是否支持developer角色否则用system按 URL 自动检测supportsReasoningEffort是否支持reasoning_effort按 URL 自动检测reasoningEffortMappi-ai 思考等级到具体reasoning_effort值的映射—supportsUsageInStreaming是否支持stream_options: { include_usage: true }默认 truemaxTokensField使用max_completion_tokens还是max_tokens按 URL 自动检测requiresToolResultName工具结果是否必须带name字段按 URL 自动检测requiresAssistantAfterToolResult工具结果后是否需要 assistant 消息间隔按 URL 自动检测requiresThinkingAsText思考块是否需转成带thinking分隔符的文本按 URL 自动检测stripReasoningContent是否剥离回放的reasoning_content风格 assistant 字段默认 falsethinkingFormat推理参数格式openai/zai/qwen默认openaiopenRouterRoutingOpenRouter 专用上游路由偏好仅当 baseUrl 指向 OpenRoutersupportsStrictMode工具定义是否支持strict字段默认 trueModel接口中还包含contextWindow、maxTokens、cost每百万 token 的输入/输出/缓存读/缓存写价格等字段均由 packages/pi-ai/src/types.ts 定义。模型与配置经ModelRegistry加载~/.gsd/agent/models.json的路径解析在 packages/pi-coding-agent/src/config.ts。六、常见问题与排查Authentication failed 但密钥有效原因密钥设置在 shell 中但 GSD 未读到。修复确保环境变量在运行gsd的同一终端中已 export。或使用gsd config将密钥保存到~/.gsd/agent/auth.json跨会话持久生效。/model中不显示 OpenRouter 模型原因未设置OPENROUTER_API_KEYGSD 会隐藏 OpenRouter 模型。修复设置密钥后重启 GSDexport OPENROUTER_API_KEYsk-or-... gsdOllama 返回空响应原因Ollama 服务未运行或模型未拉取。修复# 验证服务运行 curl http://localhost:11434/v1/models # 若缺失则拉取模型 ollama pull llama3.1:8bLM Studio 模型 ID 不匹配原因models.json的id与 LM Studio API 暴露的标识不一致。修复查看 LM Studio 服务标签页获取精确标识它通常包含文件名或量化级别如lmstudio-community/Meta-Llama-3.1-8B-Instruct-GGUF。本地模型报developer角色错误原因多数本地推理服务不支持 OpenAI 的developer消息角色。修复在 Provider 配置中添加compat.supportsDeveloperRole: falseGSD 会改用system消息{ compat: { supportsDeveloperRole: false, supportsReasoningEffort: false } }本地模型报stream_options错误原因部分服务端不支持stream_options: { include_usage: true }。修复添加compat.supportsUsageInStreaming: false{ compat: { supportsUsageInStreaming: false } }apiKey is required 校验错误原因models.jsonschema 在定义了models时要求apiKey字段。修复对无需认证的本地服务端填占位值apiKey: not-needed自定义模型的成本显示 $0.00符合预期。GSD 对自定义模型默认成本为零。如需准确成本追踪用cost字段覆盖cost: { input: 0.15, output: 0.60, cacheRead: 0.015, cacheWrite: 0.19 }价格单位为每百万 token。七、验证你的配置配置完成一个 Provider 后启动 GSDgsd检查可用模型/model你的 Provider 的模型应出现在列表中。/model是 GSD 的会话内模型切换命令docs/user-docs/commands.md。切换到该模型在/model选择器中选中。发送测试消息输入任意内容确认模型能正常响应。若模型未出现请检查环境变量是否已在当前 shell 中设置models.json是否为合法 JSON可用cat ~/.gsd/agent/models.json | python3 -m json.tool校验服务端是否运行针对本地 Provider。更多帮助参见 Troubleshooting或在会话内运行/gsd doctor。八、结合源码的配置心法凭据解析分层环境变量、~/.gsd/agent/auth.json通过gsd config写入与models.json中的apiKey字段共同构成凭据来源MCP Server 启动时也会从auth.json水合凭据且显式设置的环境变量优先级最高见 packages/mcp-server/README.md。配置即热加载models.json在每次打开/model时重新加载改完配置无需重启即可验证。本地模型三件套supportsDeveloperRole: false、supportsReasoningEffort: false、必要时supportsUsageInStreaming: false是本地推理Ollama、LM Studio、vLLM、SGLang的通用最低配置。模型 ID 严格一致本地模型的id必须与推理服务实际暴露的标识完全一致这是本地接入失败的最常见原因。赞分享人工智能AI Agent代码智能体Agent 编排CLIAI 应用【免费下载链接】gsd-2A powerful meta-prompting, context engineering and spec-driven development system that enables agents to work for long periods of time autonomously without losing track of the big picture项目地址https://gitcode.com/gh_mirrors/gs/gsd-2点击查看免费下载相关推荐CAI 接入 Ollama 完整指南本地自托管与 Ollama Cloud 云端模型双模式配置实战CAI 接入 Ollama 完整指南本地自托管与 Ollama Cloud 云端模型双模式配置实战 导读 本文是 Cybersecurity AI CAI 接人工智能AI Agent网络安全渗透测试工具调用AI 评测一条命令把低清视频放大到 4KVideo2X 实战指南一条命令把低清视频放大到 4KVideo2X 实战指南 手里一段 480P 的老录像直接放大是一片马赛克想剪慢动作低帧率又卡得没法看。Video2X 是音视频视频处理图像处理深度学习oauth2-proxy OAuth Provider 配置完全指南从 Google 到 OpenID Connect 的接入实战oauth2 proxy OAuth Provider 配置完全指南从 Google 到 OpenID Connect 的接入实战 本篇技术指南基于 oaut后端API网关认证鉴权上一篇youtube-dl-gui代码覆盖率提升计划未覆盖模块下一篇GoMock未来路线图即将发布的新特性预览创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考