OGX 与 Claude Code 集成实战用ogx connect claude一条命令接入自托管与 SaaS 混合模型【免费下载链接】ogxOpen GenAI Stack项目地址: https://gitcode.com/GitHub_Trending/ll/ogxOGXOpen GenAI Stack为 Anthropic 出品的 AI 编程工具 Claude Code 提供了开箱即用的接入支持通过ogx connect claude一条命令即可让 Claude Code 直接消费 OGX 服务器上暴露的模型并支持将 haiku/sonnet/opus 三个模型层级分别映射到来自不同提供方的模型。读完本文你将掌握从安装 Claude Code、校验 OGX 模型清单到按层级配置混合模型并完成启动与排障的完整流程。本文以 OGX 官方博客OGX ❤️ Claude Codedocs/blog/2026-06-16-claude-code-blog.md为骨架并结合仓库内ogx connect claude的实际源码实现src/ogx/cli/connect/claude.py与单元测试tests/unit/cli/test_connect_claude.py进行纵深讲解。为什么用 OGX 作为 Claude Code 的后端Claude Code 本身默认直连 Anthropic 的官方服务而通过 OGX 作为统一后端接入后可以获得三个显著优势也是官方博客明确列出的价值点预算可控可以在一个 OGX 服务器上混合接入不同来源的模型自托管 SaaS按任务成本灵活调度而不必被单一后端提供商绑定。无缝切换借助 Claude Code 的模型层级tier映射机制可以在自托管模型与 SaaS 模型之间自由切换全程无需手动干预服务器交互。高可用冗余不依赖单一 SaaS 后端即使某个云端服务不可用OGX 服务器的用户依然可以持续使用 Claude Code。在下文中我们将以一个运行在远程主机上的 OGX 服务器为例同时启用了自托管与 SaaS 模型演示完整的接入流程。前置条件准备一台启用混合模型的 OGX 服务器本教程假设你已有一台运行中的 OGX 服务器地址为myremoteserver.com:8321并且满足以下配置假设与官方博客一致remote::vllm提供方已启用服务Qwen/Qwen3-8B模型remote::gemini提供方已启用提供gemini-2.5-pro模型remote::openai提供方已启用提供gpt-4o模型尚未配置任何认证--url直连即可。如果还没有启动服务器可先参考仓库内的 Getting Started 快速入门 完成搭建。在连接 Claude Code 之前建议先用 curl 校验服务器上实际可用的模型清单curl http://myremoteserver.com:8321/v1/models该命令返回 OGX 服务器的 OpenAI 兼容模型列表其中的模型 ID如vllm/Qwen/Qwen3-8B、gemini/models/gemini-2.5-pro、openai/gpt-4o将作为后续层级映射的参数值使用。第一步下载并安装 Claude CodeClaude Code 是 Anthropic 维护的 AI 编程工具官方提供了多种安装方式。在绝大多数 Linux/macOS 环境下以下 curl 命令即可完成安装curl -fsSL https://claude.ai/install.sh | bash安装完成后需要确保claude可执行文件已加入系统的PATH。这一点在ogx connect claude的源码中会被实际校验当未使用--print-env模式时命令会通过shutil.which(claude)检查claude是否存在于 PATH找不到会直接报错并退出见 src/ogx/cli/connect/claude.py。因此安装后建议先执行claude --version确认可用。第二步用ogx connect claude启动 Claude Code现在到了最关键的一步——用一条命令把 Claude Code 连上 OGX 服务器并将三个模型层级分别映射到你想要的模型ogx connect claude \ --haiku-model vllm/Qwen/Qwen3-8B \ --sonnet-model gemini/models/gemini-2.5-pro \ --opus-model openai/gpt-4o \ --url http://myremoteserver.com:8321/v1执行成功后你会看到 Claude Code 的 TUI 界面启动在 TUI 中执行/model命令可以看到刚刚配置的三个层级模型已按预期生效命令参数说明ogx connect claude是ogx connect命令组下的子命令之一命令组还包含opencode、codex见 src/ogx/cli/connect/connect.py。其核心参数如下参数定义见 claude.py 的参数解析参数默认值说明--model MODEL服务器第一个可用 LLM将同一模型映射到 haiku/sonnet/opus 全部三个层级--haiku-model MODEL继承--modelhaiku快速层级使用的模型 ID优先级高于--model--sonnet-model MODEL继承--modelsonnet均衡层级使用的模型 ID优先级高于--model--opus-model MODEL继承--modelopus最强层级使用的模型 ID优先级高于--model--url URLhttp://localhost:8321/v1OGX 服务器地址端口同时受OGX_PORT环境变量影响见 claude.py L68-L74--print-env关闭不启动 Claude Code改为打印环境变量export/unset语句-- CLAUDE_ARGS无--之后的参数原样透传给claude命令模型 ID 的格式为provider_id/model_id例如vllm/Qwen/Qwen3-8B、openai/gpt-4o与/v1/models返回的 ID 保持一致。背后发生了什么ogx connect claude的执行原理理解这条命令的内部流程有助于你在遇到问题时快速定位。整个执行过程可以概括为下图流程与 claude.py 的_run_connect_claude_cmd实现一致ogx connect claude | v GET /v1/models 发现服务器可用模型 | v 过滤掉非 LLM 模型embedding 等 | v 将模型映射到 haiku/sonnet/opus 三个层级 | v 设置 ANTHROPIC_BASE_URL 层级环境变量 | v 启动 claudeClaude Code 直连 OGX1. 模型发现与过滤命令通过 OpenAI SDK 向--url指定的地址发起GET /v1/models请求遍历返回的模型列表并利用模型的custom_metadata.model_type字段过滤掉embedding类型的模型只保留 LLM见 claude.py 的_fetch_models。对应单元测试test_filters_out_embedding_models验证了这一行为tests/unit/cli/test_connect_claude.py。2. 层级模型解析三种策略_resolve_model_mapping按以下优先级为每个层级确定模型见 claude.py L167-L195显式的层级参数--haiku-model/--sonnet-model/--opus-model统一的--model参数自动探测_detect_tier_models会在模型 ID 中按haiku、sonnet、opus关键字匹配不区分大小写并取首个命中项见 claude.py L207-L214兜底服务器返回的第一个可用 LLM 模型。每个层级最终解析出的模型 ID 必须存在于服务器模型清单中否则命令会打印可用模型列表并报错退出。测试用例test_auto_detects_tiers_from_model_names、test_model_flag_sets_all_tiers、test_per_tier_overrides_model_flag、test_exits_when_tier_model_not_available分别覆盖了这些分支tests/unit/cli/test_connect_claude.py。3. 环境变量注入_build_env会构建并返回启动 Claude Code 所需的环境变量见 claude.py L197-L204ANTHROPIC_BASE_URL设置为服务器地址并去掉/v1后缀Claude Code 会自动拼接/v1/messages例如--url http://myremoteserver.com:8321/v1会变成http://myremoteserver.com:8321ANTHROPIC_AUTH_TOKEN固定为占位令牌ogx无需真实密钥因为假设服务器未开启认证ANTHROPIC_DEFAULT_HAIKU_MODEL/ANTHROPIC_DEFAULT_SONNET_MODEL/ANTHROPIC_DEFAULT_OPUS_MODEL三个层级的模型映射同时清除_VARS_TO_UNSET中列出的 Vertex/Bedrock 相关变量CLAUDE_CODE_USE_VERTEX、ANTHROPIC_VERTEX_PROJECT_ID、CLAUDE_CODE_USE_BEDROCK、ANTHROPIC_BEDROCK_SESSION_TOKEN见 claude.py L21-L26。这一步至关重要——一旦这些变量残留Claude Code 会绕过ANTHROPIC_BASE_URL直接连向 Vertex AI 或 Bedrock导致连接失效。测试用例test_sets_model_tier_env_vars与test_preserves_existing_env_vars验证了环境变量的注入与保留逻辑tests/unit/cli/test_connect_claude.py。4. 启动 Claude Code最后命令以注入后的环境变量调用subprocess.run([claude, *claude_args], envenv)启动 Claude Code并将其退出码透传给 shell见 claude.py L138-L139。启动后Claude Code 通过 Anthropic Messages API/v1/messages与 OGX 通信OGX 接收请求后在内部完成格式转换再转发给 vLLM、Gemini、OpenAI 等具体提供方。这一协议层能力在 docs/docs/building_applications/claude_code_integration.mdx 中有更完整的说明。模型映射的三种典型用法单一模型映射到全部层级如果服务器上只有一个想用的模型或想让所有任务都走同一个模型ogx connect claude --model openai/gpt-4o按层级差异化映射本文核心场景这是最实用的用法——快速任务走廉价的自托管模型复杂推理走云端强模型ogx connect claude \ --haiku-model vllm/Qwen/Qwen3-8B \ --sonnet-model gemini/models/gemini-2.5-pro \ --opus-model openai/gpt-4o \ --url http://myremoteserver.com:8321/v1完全自动探测不带任何模型参数时命令会自动探测服务器模型优先按模型名中的haiku/sonnet/opus关键字匹配找不到则三个层级统一回落到第一个可用 LLMogx connect claude更多实用技巧--print-env只打印环境变量手动接管如果不想让命令直接拉起 Claude Code例如需要注入到其他 shell 会话或 CI 场景可以使用--print-env模式eval $(ogx connect claude --print-env --model openai/gpt-4o) claude Hello world此时命令不会检查claude是否安装只会打印export/unset语句见 claude.py L113-L125。向 Claude Code 透传参数--之后的所有参数都会原样转发给claude命令例如以打印模式print mode执行一次请求ogx connect claude -- -p Write a hello world function连接远程服务器默认地址是http://localhost:8321/v1指向远程服务器时通过--url覆盖即可如本文主流程所示。单元测试test_url_override验证了该参数的解析tests/unit/cli/test_connect_claude.py。常见问题与注意事项连接失败Failed to connect to OGX serverOGX 服务器未启动或地址不可达。先确认服务器已通过ogx run启动再检查--url的主机名与端口是否正确。源码中对连接错误APIConnectionError和 HTTP 错误APIStatusError分别给出了明确报错与退出码见 claude.py L145-L158。找不到 LLM 模型Failed to find any LLM models服务器在运行但模型清单为空或所有模型都被识别为 embedding 类型。请检查分布配置确保至少启用了一个推理提供方并用curl http://host:8321/v1/models复查清单。指定模型不在清单中--haiku-model等参数的值必须与服务器/v1/models返回的 ID 完全一致含 provider 前缀。命令会打印服务器全部可用模型以辅助排查见 claude.py L185-L192。max_tokens报错常见于 OpenAI 模型Claude Code 会按 Claude 模型规格请求较高的 token 上限可能超出后端模型支持范围。此时应选用支持更高 token 上限的模型或利用分层映射将不同负载路由到不同模型。Claude Code 绕过 OGX 直连官方/Vertex/Bedrock通常是环境中残留了CLAUDE_CODE_USE_VERTEX、CLAUDE_CODE_USE_BEDROCK等变量。ogx connect claude会自动清除它们见 claude.py L21-L26若手动配置环境变量则需自行unset。工具调用Tool use不生效工具执行发生在 Claude Code 自己的运行时内文件操作、shell 命令等并不经过 OGX。请检查 Claude Code 的权限设置以及所选模型是否支持工具调用。小结ogx connect claude把「Claude Code 任意模型」的集成压缩成了一条命令它负责发现模型、过滤非 LLM、按 haiku/sonnet/opus 三层映射模型并通过环境变量注入与 Vertex/Bedrock 变量清理确保 Claude Code 可靠地直连 OGX 服务器。无论是单模型、多模型分层路由还是远程服务器场景你都可以基于本文的配置与排障方法快速落地让 Claude Code 同时享用自托管与 SaaS 混合模型带来的成本、灵活性与冗余收益。【免费下载链接】ogxOpen GenAI Stack项目地址: https://gitcode.com/GitHub_Trending/ll/ogx创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 OGX 与 Claude Code 集成实战：用 `ogx connect claude` 一条命令接入自托管与 SaaS 混合模型
OGX 与 Claude Code 集成实战用ogx connect claude一条命令接入自托管与 SaaS 混合模型【免费下载链接】ogxOpen GenAI Stack项目地址: https://gitcode.com/GitHub_Trending/ll/ogxOGXOpen GenAI Stack为 Anthropic 出品的 AI 编程工具 Claude Code 提供了开箱即用的接入支持通过ogx connect claude一条命令即可让 Claude Code 直接消费 OGX 服务器上暴露的模型并支持将 haiku/sonnet/opus 三个模型层级分别映射到来自不同提供方的模型。读完本文你将掌握从安装 Claude Code、校验 OGX 模型清单到按层级配置混合模型并完成启动与排障的完整流程。本文以 OGX 官方博客OGX ❤️ Claude Codedocs/blog/2026-06-16-claude-code-blog.md为骨架并结合仓库内ogx connect claude的实际源码实现src/ogx/cli/connect/claude.py与单元测试tests/unit/cli/test_connect_claude.py进行纵深讲解。为什么用 OGX 作为 Claude Code 的后端Claude Code 本身默认直连 Anthropic 的官方服务而通过 OGX 作为统一后端接入后可以获得三个显著优势也是官方博客明确列出的价值点预算可控可以在一个 OGX 服务器上混合接入不同来源的模型自托管 SaaS按任务成本灵活调度而不必被单一后端提供商绑定。无缝切换借助 Claude Code 的模型层级tier映射机制可以在自托管模型与 SaaS 模型之间自由切换全程无需手动干预服务器交互。高可用冗余不依赖单一 SaaS 后端即使某个云端服务不可用OGX 服务器的用户依然可以持续使用 Claude Code。在下文中我们将以一个运行在远程主机上的 OGX 服务器为例同时启用了自托管与 SaaS 模型演示完整的接入流程。前置条件准备一台启用混合模型的 OGX 服务器本教程假设你已有一台运行中的 OGX 服务器地址为myremoteserver.com:8321并且满足以下配置假设与官方博客一致remote::vllm提供方已启用服务Qwen/Qwen3-8B模型remote::gemini提供方已启用提供gemini-2.5-pro模型remote::openai提供方已启用提供gpt-4o模型尚未配置任何认证--url直连即可。如果还没有启动服务器可先参考仓库内的 Getting Started 快速入门 完成搭建。在连接 Claude Code 之前建议先用 curl 校验服务器上实际可用的模型清单curl http://myremoteserver.com:8321/v1/models该命令返回 OGX 服务器的 OpenAI 兼容模型列表其中的模型 ID如vllm/Qwen/Qwen3-8B、gemini/models/gemini-2.5-pro、openai/gpt-4o将作为后续层级映射的参数值使用。第一步下载并安装 Claude CodeClaude Code 是 Anthropic 维护的 AI 编程工具官方提供了多种安装方式。在绝大多数 Linux/macOS 环境下以下 curl 命令即可完成安装curl -fsSL https://claude.ai/install.sh | bash安装完成后需要确保claude可执行文件已加入系统的PATH。这一点在ogx connect claude的源码中会被实际校验当未使用--print-env模式时命令会通过shutil.which(claude)检查claude是否存在于 PATH找不到会直接报错并退出见 src/ogx/cli/connect/claude.py。因此安装后建议先执行claude --version确认可用。第二步用ogx connect claude启动 Claude Code现在到了最关键的一步——用一条命令把 Claude Code 连上 OGX 服务器并将三个模型层级分别映射到你想要的模型ogx connect claude \ --haiku-model vllm/Qwen/Qwen3-8B \ --sonnet-model gemini/models/gemini-2.5-pro \ --opus-model openai/gpt-4o \ --url http://myremoteserver.com:8321/v1执行成功后你会看到 Claude Code 的 TUI 界面启动在 TUI 中执行/model命令可以看到刚刚配置的三个层级模型已按预期生效命令参数说明ogx connect claude是ogx connect命令组下的子命令之一命令组还包含opencode、codex见 src/ogx/cli/connect/connect.py。其核心参数如下参数定义见 claude.py 的参数解析参数默认值说明--model MODEL服务器第一个可用 LLM将同一模型映射到 haiku/sonnet/opus 全部三个层级--haiku-model MODEL继承--modelhaiku快速层级使用的模型 ID优先级高于--model--sonnet-model MODEL继承--modelsonnet均衡层级使用的模型 ID优先级高于--model--opus-model MODEL继承--modelopus最强层级使用的模型 ID优先级高于--model--url URLhttp://localhost:8321/v1OGX 服务器地址端口同时受OGX_PORT环境变量影响见 claude.py L68-L74--print-env关闭不启动 Claude Code改为打印环境变量export/unset语句-- CLAUDE_ARGS无--之后的参数原样透传给claude命令模型 ID 的格式为provider_id/model_id例如vllm/Qwen/Qwen3-8B、openai/gpt-4o与/v1/models返回的 ID 保持一致。背后发生了什么ogx connect claude的执行原理理解这条命令的内部流程有助于你在遇到问题时快速定位。整个执行过程可以概括为下图流程与 claude.py 的_run_connect_claude_cmd实现一致ogx connect claude | v GET /v1/models 发现服务器可用模型 | v 过滤掉非 LLM 模型embedding 等 | v 将模型映射到 haiku/sonnet/opus 三个层级 | v 设置 ANTHROPIC_BASE_URL 层级环境变量 | v 启动 claudeClaude Code 直连 OGX1. 模型发现与过滤命令通过 OpenAI SDK 向--url指定的地址发起GET /v1/models请求遍历返回的模型列表并利用模型的custom_metadata.model_type字段过滤掉embedding类型的模型只保留 LLM见 claude.py 的_fetch_models。对应单元测试test_filters_out_embedding_models验证了这一行为tests/unit/cli/test_connect_claude.py。2. 层级模型解析三种策略_resolve_model_mapping按以下优先级为每个层级确定模型见 claude.py L167-L195显式的层级参数--haiku-model/--sonnet-model/--opus-model统一的--model参数自动探测_detect_tier_models会在模型 ID 中按haiku、sonnet、opus关键字匹配不区分大小写并取首个命中项见 claude.py L207-L214兜底服务器返回的第一个可用 LLM 模型。每个层级最终解析出的模型 ID 必须存在于服务器模型清单中否则命令会打印可用模型列表并报错退出。测试用例test_auto_detects_tiers_from_model_names、test_model_flag_sets_all_tiers、test_per_tier_overrides_model_flag、test_exits_when_tier_model_not_available分别覆盖了这些分支tests/unit/cli/test_connect_claude.py。3. 环境变量注入_build_env会构建并返回启动 Claude Code 所需的环境变量见 claude.py L197-L204ANTHROPIC_BASE_URL设置为服务器地址并去掉/v1后缀Claude Code 会自动拼接/v1/messages例如--url http://myremoteserver.com:8321/v1会变成http://myremoteserver.com:8321ANTHROPIC_AUTH_TOKEN固定为占位令牌ogx无需真实密钥因为假设服务器未开启认证ANTHROPIC_DEFAULT_HAIKU_MODEL/ANTHROPIC_DEFAULT_SONNET_MODEL/ANTHROPIC_DEFAULT_OPUS_MODEL三个层级的模型映射同时清除_VARS_TO_UNSET中列出的 Vertex/Bedrock 相关变量CLAUDE_CODE_USE_VERTEX、ANTHROPIC_VERTEX_PROJECT_ID、CLAUDE_CODE_USE_BEDROCK、ANTHROPIC_BEDROCK_SESSION_TOKEN见 claude.py L21-L26。这一步至关重要——一旦这些变量残留Claude Code 会绕过ANTHROPIC_BASE_URL直接连向 Vertex AI 或 Bedrock导致连接失效。测试用例test_sets_model_tier_env_vars与test_preserves_existing_env_vars验证了环境变量的注入与保留逻辑tests/unit/cli/test_connect_claude.py。4. 启动 Claude Code最后命令以注入后的环境变量调用subprocess.run([claude, *claude_args], envenv)启动 Claude Code并将其退出码透传给 shell见 claude.py L138-L139。启动后Claude Code 通过 Anthropic Messages API/v1/messages与 OGX 通信OGX 接收请求后在内部完成格式转换再转发给 vLLM、Gemini、OpenAI 等具体提供方。这一协议层能力在 docs/docs/building_applications/claude_code_integration.mdx 中有更完整的说明。模型映射的三种典型用法单一模型映射到全部层级如果服务器上只有一个想用的模型或想让所有任务都走同一个模型ogx connect claude --model openai/gpt-4o按层级差异化映射本文核心场景这是最实用的用法——快速任务走廉价的自托管模型复杂推理走云端强模型ogx connect claude \ --haiku-model vllm/Qwen/Qwen3-8B \ --sonnet-model gemini/models/gemini-2.5-pro \ --opus-model openai/gpt-4o \ --url http://myremoteserver.com:8321/v1完全自动探测不带任何模型参数时命令会自动探测服务器模型优先按模型名中的haiku/sonnet/opus关键字匹配找不到则三个层级统一回落到第一个可用 LLMogx connect claude更多实用技巧--print-env只打印环境变量手动接管如果不想让命令直接拉起 Claude Code例如需要注入到其他 shell 会话或 CI 场景可以使用--print-env模式eval $(ogx connect claude --print-env --model openai/gpt-4o) claude Hello world此时命令不会检查claude是否安装只会打印export/unset语句见 claude.py L113-L125。向 Claude Code 透传参数--之后的所有参数都会原样转发给claude命令例如以打印模式print mode执行一次请求ogx connect claude -- -p Write a hello world function连接远程服务器默认地址是http://localhost:8321/v1指向远程服务器时通过--url覆盖即可如本文主流程所示。单元测试test_url_override验证了该参数的解析tests/unit/cli/test_connect_claude.py。常见问题与注意事项连接失败Failed to connect to OGX serverOGX 服务器未启动或地址不可达。先确认服务器已通过ogx run启动再检查--url的主机名与端口是否正确。源码中对连接错误APIConnectionError和 HTTP 错误APIStatusError分别给出了明确报错与退出码见 claude.py L145-L158。找不到 LLM 模型Failed to find any LLM models服务器在运行但模型清单为空或所有模型都被识别为 embedding 类型。请检查分布配置确保至少启用了一个推理提供方并用curl http://host:8321/v1/models复查清单。指定模型不在清单中--haiku-model等参数的值必须与服务器/v1/models返回的 ID 完全一致含 provider 前缀。命令会打印服务器全部可用模型以辅助排查见 claude.py L185-L192。max_tokens报错常见于 OpenAI 模型Claude Code 会按 Claude 模型规格请求较高的 token 上限可能超出后端模型支持范围。此时应选用支持更高 token 上限的模型或利用分层映射将不同负载路由到不同模型。Claude Code 绕过 OGX 直连官方/Vertex/Bedrock通常是环境中残留了CLAUDE_CODE_USE_VERTEX、CLAUDE_CODE_USE_BEDROCK等变量。ogx connect claude会自动清除它们见 claude.py L21-L26若手动配置环境变量则需自行unset。工具调用Tool use不生效工具执行发生在 Claude Code 自己的运行时内文件操作、shell 命令等并不经过 OGX。请检查 Claude Code 的权限设置以及所选模型是否支持工具调用。小结ogx connect claude把「Claude Code 任意模型」的集成压缩成了一条命令它负责发现模型、过滤非 LLM、按 haiku/sonnet/opus 三层映射模型并通过环境变量注入与 Vertex/Bedrock 变量清理确保 Claude Code 可靠地直连 OGX 服务器。无论是单模型、多模型分层路由还是远程服务器场景你都可以基于本文的配置与排障方法快速落地让 Claude Code 同时享用自托管与 SaaS 混合模型带来的成本、灵活性与冗余收益。【免费下载链接】ogxOpen GenAI Stack项目地址: https://gitcode.com/GitHub_Trending/ll/ogx创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考