6 أسباب لاختيار Claude Code لنمط توافق OpenAI بدلاً من /v1/messages (دليل استكشاف الأخطاء وإصلاحها الكامل لنسخة NPM)

ملاحظة من المؤلف: يجب أن يستخدم Claude Code المثبت عبر NPM واجهة /v1/messages الأصلية، ولكن الطلبات الفعلية تتوجه إلى /v1/chat/completions؟ سنقوم في هذا المقال بتحليل 6 أسباب محتملة بناءً على الآلية الرسمية، مع تقديم خطة تشخيص سريعة من 5 خطوات، ونموذج إعداد صحيح للاتصال عبر APIYI.

وفقاً للوثائق الرسمية، يجب أن يرسل @anthropic-ai/claude-code المثبت عبر NPM طلباته دائماً إلى نقطة النهاية /v1/messages في بيئة سطر الأوامر، وهي بروتوكول Messages API الأصلي الخاص بـ Anthropic، والذي يتضمن ترويسة anthropic-version وتنسيق messages الأصلي.

ولكن إذا رأيت في سجلات الشبكة (Packet Capture) الخاصة بك أن الطلب يتوجه إلى /v1/chat/completions (تنسيق OpenAI Chat Completions)، فهذا يعني حدوث تحويل للبروتوكول أو تداخل في أسماء الحزم في مرحلة ما. هذه ليست مشكلة برمجية (Bug) في Claude Code نفسه، بل هي واحدة من 6 فئات من مشاكل الإعداد أو البيئة الشائعة.

القيمة الجوهرية: سيقوم هذا المقال بتحليل كامل لهذه الأسباب الستة (بما في ذلك تثبيت حزم طرف ثالث عن طريق الخطأ، توجيه ANTHROPIC_BASE_URL إلى بوابة توافق، اعتراض claude-code-router للطلبات وتحويلها، إلخ)، مع توفير خطة تشخيص سريعة من 5 خطوات، ونموذج إعداد صحيح لضمان العمل عبر مسار /v1/messages الأصلي عند الاتصال عبر APIYI (apiyi.com).

أولاً: يجب أن يستخدم Claude Code افتراضياً مسار `/v1/messages`: شرح الآلية الأساسية

قبل البدء في استكشاف الأخطاء وإصلاحها، يجب أولاً توضيح السلوك المتوقع لـ Claude Code الرسمي، حتى نتمكن من تحديد مكان الخلل.

1.1 تصميم بروتوكول `@anthropic-ai/claude-code` الرسمي

تستخدم حزمة NPM الرسمية @anthropic-ai/claude-code التي تديرها Anthropic بروتوكول Anthropic Messages API الأصلي فقط في جميع إصداراتها، ويظهر ذلك في:

البعد	سلوك Claude Code الرسمي
نقطة نهاية الطلب	`POST {ANTHROPIC_BASE_URL}/v1/messages`
ترويسات الطلب	`x-api-key`، `anthropic-version: 2023-06-01`، `anthropic-beta`
تنسيق جسم الطلب	`{ "model": "...", "messages": [...], "system": "...", "max_tokens": ... }`
تنسيق الاستجابة	`{ "content": [...], "stop_reason": "...", "usage": {...} }`
الاستجابة المتدفقة	تدفق أحداث SSE، مع أنواع أحداث مثل `message_start`، `content_block_delta`

إذا رأيت في سجلات الشبكة الخاصة بك /v1/chat/completions، أو Authorization: Bearer ...، أو أن جسم الطلب يحتوي على مصفوفة choices—فكل هذه خصائص بروتوكول OpenAI، مما يعني أن الطلب لا يسلك المسار الصحيح المخصص لـ Claude Code الرسمي.

1.2 الدلالة الصحيحة لمتغيرات البيئة الأساسية

لا يتعرف Claude Code الرسمي إلا على متغيرات البيئة التالية لضبط سلوك الـ API:

# مطلوب: مفتاح API الخاص بـ Anthropic أو مفتاح خدمة متوافقة
ANTHROPIC_AUTH_TOKEN=sk-your-key
# أو المتغير المرادف:
ANTHROPIC_API_KEY=sk-your-key

# اختياري: عنوان بوابة API المخصصة (لا تضع لاحقة /v1)
ANTHROPIC_BASE_URL=https://api.anthropic.com

# اختياري: معرف النموذج المخصص
ANTHROPIC_MODEL=claude-sonnet-4-5
ANTHROPIC_SMALL_FAST_MODEL=claude-haiku-4-5

ملاحظة: لا يحتوي Claude Code الرسمي على متغيرات مثل OPENAI_BASE_URL أو CLAUDE_CODE_USE_OPENAI. إذا ظهرت هذه المتغيرات في بيئتك، فهذا يعني أنك تستخدم غلافاً (wrapper) من طرف ثالث.

💡 نصيحة للتحقق السريع: قم بتنفيذ الأمر which claude في الطرفية (Terminal) لعرض مسار تثبيت Claude Code، ثم نفذ cat $(which claude) | head -20. إذا رأيت عبارة @anthropic-ai/claude-code، فهذا يعني أنك قمت بتثبيت النسخة الرسمية. أما إذا رأيت كلمات مفتاحية مثل openclaude أو claudex أو cli-agent-openai-adapter، فقد وجدت السبب الجذري للمشكلة.

2. 导致 Claude Code 运行在 OpenAI 兼容模式的 6 大可能原因

按出现概率从高到低排列，建议按顺序排查。

2.1 原因一：误装了第三方 OpenAI Wrapper 包（约 35% 案例）

NPM 上存在多个名字相似但功能完全不同的 "Claude Code" 包，专门做 OpenAI 兼容转换。客户可能误装了其中之一：

包名	实际功能	默认协议
`@anthropic-ai/claude-code`	✅ 官方包	`/v1/messages`
`@gitlawb/openclaude`	OpenAI shim	`/v1/chat/completions`
`@aryanjsx/openclaude`	OpenAI shim	`/v1/chat/completions`
`cli-agent-openai-adapter`	协议转换器	`/v1/chat/completions`
`claude-code-openai-wrapper`	双协议 wrapper	两者都支持
`claudex`	Go 写的 OpenAI 代理	`/v1/chat/completions`

排查方法：

# 1. 查看实际安装路径
which claude
# 输出示例：/usr/local/bin/claude

# 2. 查看包的 package.json 中的 name
cat $(npm root -g)/@anthropic-ai/claude-code/package.json 2>/dev/null | grep '"name"'

# 3. 查看全局已安装的所有 claude 相关包
npm list -g --depth=0 | grep -i claude

如果 npm list 没有 @anthropic-ai/claude-code，但有其他类似名字的包，就是误装。

2.2 原因二：配置了 claude-code-router 等路由工具（约 25% 案例）

claude-code-router (CCR) 是社区流行的开源工具，专门拦截 Claude Code 请求并转发到不同模型（如 OpenAI、DeepSeek、智谱）。其工作原理：

启动一个本地代理服务器（默认 http://localhost:3456）
用户把 ANTHROPIC_BASE_URL 指向这个本地代理
CCR 接收到 /v1/messages 请求后，翻译成 /v1/chat/completions 转发到目标模型
抓包看到的就是 OpenAI 协议

排查方法：

# 检查环境变量
env | grep -i ANTHROPIC

# 如果看到类似 ANTHROPIC_BASE_URL=http://localhost:3456 或 http://127.0.0.1:xxx
# 大概率是 CCR / claude-code-router 等本地代理

2.3 原因三：ANTHROPIC_BASE_URL 指向 OpenAI 兼容网关（约 20% 案例）

某些 LLM 网关（如 LiteLLM Proxy、OneAPI、Bifrost）虽然支持配置 Anthropic 模型，但只暴露 /v1/chat/completions 接口。如果客户把 ANTHROPIC_BASE_URL 指向这种网关：

Claude Code 仍然按 /v1/messages 发请求
网关返回 404 或自动 rewrite 路径
网关内部转换成 OpenAI 格式调用上游
抓包工具如果是在网关之后部署，看到的就是 OpenAI 协议

排查方法：检查 ANTHROPIC_BASE_URL 是否是已知的 OpenAI 兼容网关地址，请求是否实际成功（200 还是 404）。

2.4 原因四：设置了第三方 Wrapper 的环境变量（约 10% 案例）

某些 wrapper 包通过环境变量切换协议模式，例如：

# openclaude 的切换变量
CLAUDE_CODE_USE_OPENAI=1
OPENAI_API_KEY=sk-xxx
OPENAI_MODEL=gpt-4o
OPENAI_BASE_URL=https://api.openai.com/v1

即使 npm 装的是官方包，如果 PATH 中有 wrapper 脚本（如 /usr/local/bin/claude 实际是 wrapper），这些变量也会生效。

排查方法：

# 列出所有 PATH 中名为 claude 的可执行文件
type -a claude

# 检查是否有相关环境变量
env | grep -E 'CLAUDE_CODE|OPENAI_BASE_URL|OPENAI_MODEL'

2.5 原因五：Shell alias 或 wrapper 脚本拦截（约 7% 案例）

客户可能在 ~/.bashrc / ~/.zshrc 中配置了 alias：

# 这种 alias 会让原始 claude 命令被替换
alias claude='openclaude'
alias claude='claude-code-router run'

# 或定义了同名函数
claude() {
  CCR_PROXY=http://localhost:3456 command claude "$@"
}

排查方法：

# 查看 alias
alias | grep claude

# 查看 function
type claude

# 查看 shell 启动文件
grep -nE 'claude' ~/.bashrc ~/.zshrc ~/.profile 2>/dev/null

2.6 原因六：抓包视角误判（约 3% 案例）

少数情况下，客户的抓包工具部署位置不对，看到的请求并不是 Claude Code 实际发出的。例如：

Claude Code → 本地透明代理（如 mitmproxy）→ 远程 OpenAI 网关
抓包工具部署在网关之后，看到的是网关重写后的请求
实际上 Claude Code 发的就是 /v1/messages

排查方法：在客户机器本地用 mitmproxy 直接代理 Claude Code 进程，确认它发出的第一跳请求是什么协议。

三、5 步快速诊断 Claude Code 协议异常

按以下顺序逐项检查，绝大多数协议异常都能在前 3 步内定位。

3.1 第一步：确认安装的是官方 NPM 包

# 卸载所有可能的 wrapper
npm uninstall -g @gitlawb/openclaude @aryanjsx/openclaude cli-agent-openai-adapter claudex claude-code-router 2>/dev/null

# 卸载并重装官方包
npm uninstall -g @anthropic-ai/claude-code
npm install -g @anthropic-ai/claude-code

# 验证版本来源
claude --version
npm list -g @anthropic-ai/claude-code

通过条件：npm list -g 输出包含 @anthropic-ai/[email protected]。

3.2 第二步：清理 PATH 和 Shell alias

# 找出所有 PATH 中名为 claude 的可执行文件
type -a claude
which -a claude

# 取消同名 alias / function
unalias claude 2>/dev/null
unset -f claude 2>/dev/null

# 检查并清理 shell 启动脚本中的 claude 相关配置
grep -n 'claude' ~/.bashrc ~/.zshrc ~/.profile 2>/dev/null

通过条件：type -a claude 只输出一个路径，且指向 npm 全局目录下的官方包。

3.3 第三步：清理冲突的环境变量

# 查看所有 claude / openai 相关变量
env | grep -iE 'claude|openai|anthropic'

# 清理可能冲突的变量
unset CLAUDE_CODE_USE_OPENAI
unset OPENAI_BASE_URL
unset OPENAI_MODEL
unset CCR_PROXY

# 只保留官方需要的变量
export ANTHROPIC_BASE_URL="https://vip.apiyi.com"
export ANTHROPIC_AUTH_TOKEN="sk-your-apiyi-key"

🎯 关键提醒：ANTHROPIC_BASE_URL 应填到域名根（不带 /v1 后缀），Claude Code 会自动拼接 /v1/messages。如果填了 https://vip.apiyi.com/v1，会拼成 https://vip.apiyi.com/v1/v1/messages，导致 404。

3.4 第四步：测试 base_url 是否原生支持 /v1/messages

直接用 curl 模拟 Claude Code 的请求，验证网关是否真的支持 Anthropic 原生协议：

curl -X POST "$ANTHROPIC_BASE_URL/v1/messages" \
  -H "x-api-key: $ANTHROPIC_AUTH_TOKEN" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-4-5",
    "max_tokens": 100,
    "messages": [{"role": "user", "content": "Hello"}]
  }'

通过条件：返回 200，响应体包含 "type": "message" 和 "content": [...]。

如果返回 404 或响应体是 OpenAI 格式（含 choices），说明 ANTHROPIC_BASE_URL 指向的网关不支持原生 Anthropic 协议。这时切换到 APIYI (apiyi.com) 即可立即解决——它原生支持 /v1/messages，也兼容 /v1/chat/completions，双协议都能用。

3.5 第五步：本地抓包验证最终请求

如果前 4 步都通过但仍有问题，用 mitmproxy 本地抓包验证：

# 启动 mitmproxy（默认端口 8080）
mitmproxy --listen-port 8080

# 让 Claude Code 走本地代理
export HTTPS_PROXY=http://localhost:8080
export HTTP_PROXY=http://localhost:8080

# 启动 Claude Code
claude

通过条件：mitmproxy 抓到的第一个请求是 POST /v1/messages，请求头含 anthropic-version。

أربعة: الإعداد الكامل لربط Claude Code عبر خدمة APIYI باستخدام مسار `/v1/messages` الأصلي

تُعد خدمة APIYI (apiyi.com) واحدة من خدمات وكيل API القليلة التي تدعم بروتوكول Anthropic Messages API بشكل أصلي، مما يضمن عمل Claude Code عبر مسار /v1/messages بدلاً من /v1/chat/completions.

4.1 إعداد متغيرات البيئة (الطريقة الأبسط)

# macOS / Linux
export ANTHROPIC_BASE_URL="https://vip.apiyi.com"
export ANTHROPIC_AUTH_TOKEN="sk-your-apiyi-key"
# اختياري: تحديد النموذج الافتراضي
export ANTHROPIC_MODEL="claude-sonnet-4-5"
export ANTHROPIC_SMALL_FAST_MODEL="claude-haiku-4-5"

# Windows PowerShell
$env:ANTHROPIC_BASE_URL = "https://vip.apiyi.com"
$env:ANTHROPIC_AUTH_TOKEN = "sk-your-apiyi-key"

# تشغيل Claude Code
claude

4.2 حفظ الإعدادات بشكل دائم في ملفات بدء تشغيل Shell

# الإضافة إلى ~/.zshrc أو ~/.bashrc
cat >> ~/.zshrc <<'EOF'

# إعدادات وكيل APIYI لـ Claude Code
export ANTHROPIC_BASE_URL="https://vip.apiyi.com"
export ANTHROPIC_AUTH_TOKEN="sk-your-apiyi-key"
export ANTHROPIC_MODEL="claude-sonnet-4-5"
EOF

# إعادة تحميل الإعدادات
source ~/.zshrc

4.3 عبر أوامر الإعداد المدمجة في Claude Code (موصى به)

يوفر Claude Code واجهة سطر أوامر (CLI) خاصة به للإعداد، مما يمنع تسريب متغيرات البيئة:

# الطريقة الأولى: تفاعلية
claude /login
# اختر "Custom Endpoint"، ثم أدخل https://vip.apiyi.com ومفتاح API الخاص بك

# الطريقة الثانية: تعديل ملف الإعدادات مباشرة
cat > ~/.claude/settings.json <<'EOF'
{
  "env": {
    "ANTHROPIC_BASE_URL": "https://vip.apiyi.com",
    "ANTHROPIC_AUTH_TOKEN": "sk-your-apiyi-key"
  }
}
EOF

4.4 التحقق من مسار الطلب الفعلي بعد الإعداد

بعد تشغيل Claude Code، افتح طرفية جديدة واستخدم الأوامر التالية للتحقق:

# الطريقة الأولى: التقاط الحزم عبر mitmproxy (الأكثر دقة)
mitmproxy --listen-port 8080
# عند تشغيل Claude Code في طرفية أخرى، قم بضبط HTTPS_PROXY=http://localhost:8080

# الطريقة الثانية: تفعيل سجلات تصحيح الأخطاء (debug) في Claude Code
ANTHROPIC_LOG=debug claude
# ستعرض السجلات عنوان URL الكامل للطلب وطريقة الإرسال

النتيجة المتوقعة: يجب أن تكون جميع عناوين URL للطلبات هي https://vip.apiyi.com/v1/messages، وطريقة الإرسال POST، مع ترويسة anthropic-version: 2023-06-01.

4.5 المزايا الجوهرية للربط عبر APIYI

الميزة	الوصف
دعم أصلي لـ /v1/messages	البروتوكول الافتراضي لـ Claude Code، بدون فقدان في الأداء
دعم متزامن لـ /v1/chat/completions	مفتاح واحد يدعم بروتوكولين، مرونة عالية
الحفاظ الكامل على ترويسات anthropic-beta	دعم ميزات متقدمة مثل التخزين المؤقت للموجه (prompt caching) واستخدام الأدوات
لا حدود للتزامن	لا يتم تقييد السرعة في سيناريوهات المحادثات الطويلة لـ Claude Code
عرض خاص	شحن 100 دولار يمنحك 10% إضافية
دفع محلي	دعم الدفع المباشر عبر WeChat وAlipay

خمسة: مقارنة بين بروتوكول /v1/messages الأصلي وبروتوكول OpenAI /v1/chat/completions

إن فهم الاختلافات الجوهرية بين البروتوكولين هو السبيل الوحيد لإدراك سبب ضرورة استخدام Claude Code للبروتوكول الأصلي للاستفادة من قدراته الكاملة.

البعد	Anthropic /v1/messages	OpenAI /v1/chat/completions
ترويسة المصادقة	`x-api-key: sk-...`	`Authorization: Bearer sk-...`
ترويسة الإصدار	`anthropic-version: 2023-06-01`	لا يوجد (يتم استخدام إصدار URL)
ترويسة الميزات	`anthropic-beta: prompt-caching-...`	لا يوجد معيار موحد
حقل النظام (system)	حقل مستقل في المستوى الأعلى	يُعامل كدور `system` ضمن `messages[0]`
تنسيق الاستجابة	`{ "content": [...], "stop_reason": "..." }`	`{ "choices": [{ "message": {...} }] }`
أحداث البث (Streaming)	أحداث مهيكلة مثل `message_start` و`content_block_delta`	`data: {...}` (SSE عام)
استدعاء الأدوات	تضمين `tool_use` داخل كتل المحتوى	`choices[0].message.tool_calls`
حساب الرموز (Tokens)	`usage.input_tokens` / `usage.output_tokens`	`usage.prompt_tokens` / `usage.completion_tokens`

الخلاصة الأساسية: يستخدم Claude Code بكثافة ميزات Anthropic الحصرية (مثل التخزين المؤقت للموجه، وتدفق استدعاء الأدوات، ومحتوى التفكير)، وإذا تم تحويله قسراً إلى بروتوكول OpenAI، فستفقد هذه القدرات أو سيحدث تضارب في السلوك. ولهذا السبب يجب التأكد من عمله عبر المسار الأصلي /v1/messages.

6. قائمة التحقق من استكشاف الأخطاء وإصلاحها حسب سيناريو الاستخدام

6.1 السيناريو الأول: الاستخدام المحلي للمطورين الأفراد

السبب الأكثر شيوعاً: وجود غلاف (wrapper) يحمل نفس الاسم في Shell alias أو PATH.

قائمة التحقق:

هل تحتوي npm list -g على @anthropic-ai/claude-code؟
هل يشير type -a claude إلى الحزمة الرسمية فقط؟
هل يحتوي ملف ~/.zshrc أو ~/.bashrc على alias claude=...؟
هل يحتوي env | grep -i claude على متغيرات غير قياسية؟
هل تم إلحاق لاحقة /v1 بمتغير ANTHROPIC_BASE_URL؟ (يجب أن يكون بدونها).

6.2 السيناريو الثاني: النشر في بيئة الفريق/الشركة

السبب الأكثر شيوعاً: بوابة LLM الداخلية تدعم بروتوكول OpenAI فقط.

قائمة التحقق:

هل تدعم بوابة الشركة محلياً نقطة النهاية /v1/messages؟
هل تقوم البوابة بإعادة توجيه ترويسات الطلب anthropic-version و anthropic-beta؟
هل تحتفظ البوابة بالتنسيق الأصلي لأحداث SSE؟
هل يوجد نص برمجي (wrapper) موحد للفريق؟

إذا كانت بوابة الشركة تدعم بروتوكول OpenAI فقط، يُنصح بتغيير ANTHROPIC_BASE_URL في العميل ليشير إلى APIYI (apiyi.com)، للحصول على اتصال مباشر بالبروتوكول الأصلي وتجنب فقدان الأداء بسبب التحويل.

6.3 السيناريو الثالث: استدعاء Claude Code في بيئة CI/CD

السبب الأكثر شيوعاً: وجود غلاف (wrapper) تابع لجهة خارجية مثبت مسبقاً في نصوص CI البرمجية.

قائمة التحقق:

هل يقوم ملف إعدادات CI بتنفيذ npm install -g لحزمة غير رسمية؟
هل تحتوي متغيرات بيئة CI على CLAUDE_CODE_USE_OPENAI=1؟
هل تحتوي صورة (image) بيئة تشغيل CI على غلاف مثبت مسبقاً؟

6.4 السيناريو الرابع: التشغيل داخل حاوية Docker

السبب الأكثر شيوعاً: الصورة الأساسية (base image) تحتوي على غلاف مثبت مسبقاً.

قائمة التحقق:

هل اسم الحزمة في RUN npm install -g داخل Dockerfile هو الاسم الرسمي؟
إلى أين يشير which claude داخل الحاوية؟
هل تم ضبط متغيرات بيئة الحاوية لتبديل البروتوكول؟

7. الأسئلة الشائعة حول استثناءات بروتوكول Claude Code

س1: لقد قمت بتثبيت الحزمة الرسمية `@anthropic-ai/claude-code`، فلماذا لا يزال يستخدم بروتوكول OpenAI؟

السبب الأكثر احتمالاً هو أن ANTHROPIC_BASE_URL يشير إلى بوابة متوافقة مع OpenAI. بعض البوابات تقوم بتحويل طلبات /v1/messages داخلياً إلى /v1/chat/completions عند استدعاء المصدر، وإذا كانت أداة التقاط الحزم الخاصة بك تعمل بعد البوابة، فسترى البروتوكول المحول.

الحل هو تغيير ANTHROPIC_BASE_URL ليشير إلى APIYI (apiyi.com)، حيث يدعم /v1/messages أصلياً دون أي فقدان في الأداء.

س2: كيف يمكنني إلغاء تثبيت جميع أغلفة (wrappers) Claude المحتملة تماماً؟

# سرد جميع الحزم العالمية المتعلقة بـ claude
npm list -g --depth=0 | grep -i claude

# إلغاء تثبيت الأغلفة المعروفة دفعة واحدة
npm uninstall -g \
  @gitlawb/openclaude \
  @aryanjsx/openclaude \
  cli-agent-openai-adapter \
  claudex \
  claude-code-router \
  ccr \
  2>/dev/null

# إعادة تثبيت الحزمة الرسمية
npm install -g @anthropic-ai/claude-code

# التحقق
which claude
claude --version

س3: ما هو مستوى المسار الذي يجب أن أضعه في `ANTHROPIC_BASE_URL`؟

ضعه حتى جذر النطاق (Domain root)، ولا تضف لاحقة /v1. سيقوم Claude Code داخلياً بإلحاق /v1/messages تلقائياً.

# ✅ صحيح
export ANTHROPIC_BASE_URL="https://vip.apiyi.com"

# ❌ خطأ (سيؤدي إلى مسار /v1/v1/messages)
export ANTHROPIC_BASE_URL="https://vip.apiyi.com/v1"

# ❌ خطأ (يتضمن مسار نقطة النهاية)
export ANTHROPIC_BASE_URL="https://vip.apiyi.com/v1/messages"

س4: لماذا تطلب مني بعض الدروس تثبيت `claude-code-router`؟

claude-code-router هو أداة مجتمعية، والغرض الرئيسي منها هو تمكين Claude Code من استدعاء نماذج غير تابعة لـ Anthropic (مثل DeepSeek، Zhipu، أو Ollama المحلي). يتم ذلك من خلال تحويل البروتوكول.

إذا كنت ترغب فقط في استخدام نماذج Claude الأصلية من Anthropic (مثل Claude Sonnet 4.5 أو Opus 4.7)، فأنت لا تحتاج إلى CCR على الإطلاق، فقط اتصل بـ APIYI (apiyi.com) واستخدم /v1/messages الأصلي، للحصول على تجربة أفضل وبدون فقدان في الأداء.

س5: هل يدعم APIYI (apiyi.com) كلاً من `/v1/messages` و `/v1/chat/completions`؟

نعم، APIYI متوافق تماماً مع كلا البروتوكولين:

https://vip.apiyi.com/v1/messages —— تنسيق Anthropic الأصلي (الافتراضي لـ Claude Code)
https://vip.apiyi.com/v1/chat/completions —— تنسيق متوافق مع OpenAI

يمكن استخدام مفتاح API واحد مع كلا البروتوكولين، حيث يتكيف تلقائياً بناءً على أداة العميل.

س6: إذا كان رابط URL الذي يظهر في التقاط الحزم هو `https://vip.apiyi.com/v1/messages`، فهل هذا يعني بالضرورة أنه النمط الأصلي؟

ليس بالضرورة. يجب التحقق من الآتي:

ترويسة الطلب تحتوي على anthropic-version: 2023-06-01.
جسم الطلب يحتوي في مستواه الأعلى على مصفوفة messages وحقل system مستقل (وليس system role داخل messages).
جسم الاستجابة يحتوي على "type": "message" و content: [...] (وليس choices: [...]).

إذا كان الرابط هو /v1/messages ولكن جسم الطلب بتنسيق OpenAI (يحتوي على system role داخل messages)، فهذا يعني أن العميل لديه طبقة تحويل خاصة به.

س7: ما هو متغير البيئة لتفعيل سجلات تصحيح الأخطاء (debug logs) في Claude Code؟

# إخراج سجلات مفصلة لطلبات/استجابات HTTP
ANTHROPIC_LOG=debug claude

# أو استخدام وضع verbose
claude --verbose

# عرض معلومات التشخيص الخاصة بـ Claude Code
claude /doctor

سجلات تصحيح الأخطاء ستعرض الرابط الكامل، الترويسات، وجسم الطلب (سيتم إخفاء الحقول الحساسة)، وهي الطريقة الأكثر مباشرة لتحديد مشاكل البروتوكول.

س8: كان Claude Code يعمل بشكل طبيعي، وفجأة تحول إلى بروتوكول OpenAI، ما السبب؟

الأسباب الأكثر شيوعاً لهذا التغيير المفاجئ:

تحديث Claude Code مع تثبيت حزمة طرف ثالث تحمل نفس الاسم عن طريق الخطأ عبر npm install -g.
قيام الفريق مؤخراً بنشر بوابة LLM وتعيين ANTHROPIC_BASE_URL جديد.
تفعيل بعض الأسماء المستعارة (alias) مجدداً بعد تحديث macOS.
قيام الشركة بتفعيل وكيل شفاف (transparent proxy) لإجراء تدقيق تحويل البروتوكول.

عند استكشاف الأخطاء، ابحث أولاً عن أي تغييرات حديثة في البيئة (سجلات تثبيت npm، تغييرات في إعدادات shell، إشعارات تغيير البوابة).

ثامناً. النقاط الجوهرية (Key Takeaways)

✅ الأداة الرسمية @anthropic-ai/claude-code تستخدم دائماً المسار /v1/messages، ولا يوجد وضع توافق رسمي مع OpenAI.
✅ هناك 6 أسباب محتملة للمشكلة (مرتبة حسب الاحتمالية): تثبيت حزمة طرف ثالث عن طريق الخطأ / اعتراض الطلبات بواسطة claude-code-router / توجيه base_url إلى بوابة OpenAI / متغيرات بيئة من طرف ثالث / اختصارات Shell (alias) / خطأ في تفسير بيانات فحص الشبكة.
✅ خمس خطوات للتشخيص السريع: التأكد من اسم الحزمة → تنظيف PATH/alias → تنظيف متغيرات البيئة → اختبار base_url عبر curl → التحقق من خلال فحص الشبكة محلياً.
✅ لا تضف لاحقة /v1 إلى ANTHROPIC_BASE_URL، حيث يقوم Claude Code بإضافتها تلقائياً.
✅ منصة APIYI (apiyi.com) تدعم بروتوكول /v1/messages أصلياً، وتتوافق أيضاً مع /v1/chat/completions؛ مفتاح واحد يدعم البروتوكولين.
✅ مزايا استخدام البروتوكول الأصلي: دعم كامل لميزات Anthropic الحصرية مثل التخزين المؤقت للموجهات (prompt caching)، استخدام الأدوات (tool_use)، ومحتوى الاستدلال (reasoning content).
✅ طريقة التحقق السريع: استخدم الأمر ANTHROPIC_LOG=debug claude لعرض رابط الطلب الفعلي وطريقة الاستدعاء.

تاسعاً. الخلاصة

يجب أن تستخدم أداة Claude Code المثبتة عبر NPM في بيئة سطر الأوامر دائماً بروتوكول /v1/messages الأصلي، فهذا سلوك مبرمج مسبقاً في حزمة @anthropic-ai/claude-code الرسمية، ولا يوجد مفتاح رسمي للتبديل إلى وضع التوافق مع OpenAI. إذا لاحظ العميل عند فحص الشبكة أن الطلبات تتوجه إلى /v1/chat/completions، فإن المشكلة تكمن حتماً في إعدادات بيئة العميل: إما تثبيت حزمة وسيطة (wrapper) غير رسمية، أو توجيه ANTHROPIC_BASE_URL إلى بوابة تدعم بروتوكول OpenAI فقط، أو وجود اعتراض من خلال اختصارات Shell أو متغيرات البيئة.

باتباع خطوات التشخيص الخمس المذكورة في الفصل الثالث من هذا المقال، يمكن تحديد معظم المشكلات وحلها في أقل من 10 دقائق. الحل الأكثر شيوعاً هو: إلغاء تثبيت جميع الحزم غير الرسمية ← إعادة تثبيت @anthropic-ai/claude-code ← توجيه ANTHROPIC_BASE_URL إلى خدمة وكيل API تدعم /v1/messages أصلياً.

تم تصميم منصة APIYI (apiyi.com) خصيصاً لهذه السيناريوهات؛ فهي تدعم Anthropic Messages API أصلياً (مع تمرير كامل لترويسات anthropic-version و anthropic-beta)، وتتوافق في الوقت نفسه مع OpenAI Chat Completions (مفتاح واحد لبروتوكولين)، مع عدم وجود قيود على التزامن (لضمان عدم تقييد جلسات Claude Code الطويلة)، بالإضافة إلى عرض خاص (اشحن 100 دولار واحصل على 10% إضافية)، ودعم الدفع بالعملة الصينية (عبر WeChat/Alipay). للإعداد، ما عليك سوى ضبط ANTHROPIC_BASE_URL على https://vip.apiyi.com دون الحاجة لأي تعديلات برمجية.

🎯 الخطوة التالية المقترحة: اطلب من العميل اتباع خطوات التشخيص من 3.1 إلى 3.3، وتغيير ANTHROPIC_BASE_URL إلى https://vip.apiyi.com، ثم إعادة تشغيل Claude Code واستخدام ANTHROPIC_LOG=debug claude للتحقق مما إذا كان رابط الطلب قد عاد إلى /v1/messages.

مراجع إضافية

وثائق Claude Code الرسمية: شرح إعداد بوابة نماذج اللغة الكبيرة (LLM Gateway)
- الرابط: code.claude.com/docs/en/llm-gateway
- ملاحظة: توضح الوثائق الرسمية أن Claude Code يستخدم تنسيق Anthropic Messages API.
حزمة NPM الخاصة بـ @anthropic-ai/claude-code: صفحة حزمة NPM الرسمية
- الرابط: npmjs.com/package/@anthropic-ai/claude-code
- ملاحظة: تأكد من تثبيت الحزمة الرسمية.
وثائق Anthropic Messages API الرسمية: مواصفات البروتوكول الأصلي
- الرابط: docs.anthropic.com/en/api/messages
- ملاحظة: تحتوي على الحقول الكاملة، رؤوس الطلبات (Headers)، وتنسيق الاستجابة لنقطة النهاية /v1/messages.
موقع APIYI الرسمي: خدمة وكيل API المتوافقة مع بروتوكول Anthropic الأصلي
- الرابط: apiyi.com
- ملاحظة: تدعم /v1/messages الأصلي + توافق مع /v1/chat/completions، لا قيود على التزامن، واحصل على 10% إضافية عند شحن رصيد بقيمة 100 دولار.

الكاتب: الفريق التقني
آخر تحديث: 2026-05-02
نبذة عن APIYI: تُعد APIYI (apiyi.com) مزوداً محترفاً لخدمة وكيل API الخاص بـ Claude، حيث تدعم بشكل أصلي Anthropic Messages API (بما في ذلك /v1/messages مع تمرير كامل لـ anthropic-version و anthropic-beta)، كما أنها متوافقة مع OpenAI Chat Completions (/v1/chat/completions). نوفر وصولاً مستقراً لكامل سلسلة Claude Sonnet 4.5، وClaude Opus 4.7، وClaude Haiku 4.5، مع مكافأة 10% عند شحن 100 دولار (ما يعادل خصم 15% مقارنة بالموقع الرسمي)، بدون قيود على التزامن، ودعم فني سريع الاستجابة.

أولاً: يجب أن يستخدم Claude Code افتراضياً مسار /v1/messages: شرح الآلية الأساسية

1.1 تصميم بروتوكول @anthropic-ai/claude-code الرسمي

1.2 الدلالة الصحيحة لمتغيرات البيئة الأساسية

2. 导致 Claude Code 运行在 OpenAI 兼容模式的 6 大可能原因

2.1 原因一：误装了第三方 OpenAI Wrapper 包（约 35% 案例）

2.2 原因二：配置了 claude-code-router 等路由工具（约 25% 案例）

2.3 原因三：ANTHROPIC_BASE_URL 指向 OpenAI 兼容网关（约 20% 案例）

2.4 原因四：设置了第三方 Wrapper 的环境变量（约 10% 案例）

2.5 原因五：Shell alias 或 wrapper 脚本拦截（约 7% 案例）

2.6 原因六：抓包视角误判（约 3% 案例）

三、5 步快速诊断 Claude Code 协议异常

3.1 第一步：确认安装的是官方 NPM 包

3.2 第二步：清理 PATH 和 Shell alias

3.3 第三步：清理冲突的环境变量

3.4 第四步：测试 base_url 是否原生支持 /v1/messages

3.5 第五步：本地抓包验证最终请求

أربعة: الإعداد الكامل لربط Claude Code عبر خدمة APIYI باستخدام مسار /v1/messages الأصلي

4.1 إعداد متغيرات البيئة (الطريقة الأبسط)

4.2 حفظ الإعدادات بشكل دائم في ملفات بدء تشغيل Shell

4.3 عبر أوامر الإعداد المدمجة في Claude Code (موصى به)

4.4 التحقق من مسار الطلب الفعلي بعد الإعداد

4.5 المزايا الجوهرية للربط عبر APIYI

خمسة: مقارنة بين بروتوكول /v1/messages الأصلي وبروتوكول OpenAI /v1/chat/completions

6. قائمة التحقق من استكشاف الأخطاء وإصلاحها حسب سيناريو الاستخدام

6.1 السيناريو الأول: الاستخدام المحلي للمطورين الأفراد

6.2 السيناريو الثاني: النشر في بيئة الفريق/الشركة

6.3 السيناريو الثالث: استدعاء Claude Code في بيئة CI/CD

6.4 السيناريو الرابع: التشغيل داخل حاوية Docker

7. الأسئلة الشائعة حول استثناءات بروتوكول Claude Code

س1: لقد قمت بتثبيت الحزمة الرسمية @anthropic-ai/claude-code، فلماذا لا يزال يستخدم بروتوكول OpenAI؟

س2: كيف يمكنني إلغاء تثبيت جميع أغلفة (wrappers) Claude المحتملة تماماً؟

س3: ما هو مستوى المسار الذي يجب أن أضعه في ANTHROPIC_BASE_URL؟

س4: لماذا تطلب مني بعض الدروس تثبيت claude-code-router؟

س5: هل يدعم APIYI (apiyi.com) كلاً من /v1/messages و /v1/chat/completions؟

س6: إذا كان رابط URL الذي يظهر في التقاط الحزم هو https://vip.apiyi.com/v1/messages، فهل هذا يعني بالضرورة أنه النمط الأصلي؟

س7: ما هو متغير البيئة لتفعيل سجلات تصحيح الأخطاء (debug logs) في Claude Code؟

س8: كان Claude Code يعمل بشكل طبيعي، وفجأة تحول إلى بروتوكول OpenAI، ما السبب؟

ثامناً. النقاط الجوهرية (Key Takeaways)

تاسعاً. الخلاصة

مراجع إضافية

موضوعات ذات صلة

أولاً: يجب أن يستخدم Claude Code افتراضياً مسار `/v1/messages`: شرح الآلية الأساسية

1.1 تصميم بروتوكول `@anthropic-ai/claude-code` الرسمي

أربعة: الإعداد الكامل لربط Claude Code عبر خدمة APIYI باستخدام مسار `/v1/messages` الأصلي

س1: لقد قمت بتثبيت الحزمة الرسمية `@anthropic-ai/claude-code`، فلماذا لا يزال يستخدم بروتوكول OpenAI؟

س3: ما هو مستوى المسار الذي يجب أن أضعه في `ANTHROPIC_BASE_URL`؟

س4: لماذا تطلب مني بعض الدروس تثبيت `claude-code-router`؟

س5: هل يدعم APIYI (apiyi.com) كلاً من `/v1/messages` و `/v1/chat/completions`؟

س6: إذا كان رابط URL الذي يظهر في التقاط الحزم هو `https://vip.apiyi.com/v1/messages`، فهل هذا يعني بالضرورة أنه النمط الأصلي؟