Oh My Pi 接入 MoxAI 教程：配置终端 AI 编程 Agent

本文整理自 MoxAI 帮助中心，并改写为博客教程，适合希望把 AI Agent、AI 编程助手或桌面客户端接入 MoxAI 的用户参考。

项目介绍

Oh My Pi 是一款终端 AI 编程 Agent，通过 models.yml 配置文件添加自定义模型供应商。支持思考模式（reasoning effort）、工具调用和完整的上下文管理。

• GitHub：https://github.com/can1357/oh-my-pi
• 安装指南：https://github.com/can1357/oh-my-pi#installation

📦 接入前准备

准备信息

• 已安装 Oh My Pi（omp 命令可用）
• 一个可用的 MoxAI 地址（本工具配置时 不要加 /v1 后缀，见下文说明）
• 一个可用的 MoxAI API Key（在控制台生成）
• 想使用的模型名称（如 claude-sonnet-4-6、gemini-2.5-flash 等，需与 MoxAI 控制台中的模型 ID 完全一致）

🔑 第一步：设置环境变量

export MoxAI_API_KEY=your-moxai-api-key

🔧 第二步：创建配置文件

创建 ~/.omp/agent/models.yml，添加 MoxAI 供应商：

providers:
  moxai:
    baseUrl: https://api.moxai.ai
    api: openai-completions
    apiKey: MoxAI_API_KEY
    authHeader: true
    models:
      - id: claude-sonnet-4-6
        name: Claude Sonnet 4.6
        reasoning: true
        thinking:
          minLevel: high
          maxLevel: xhigh
          mode: effort
        input: [text]
        contextWindow: 200000
        maxTokens: 128000
        compat:
          supportsDeveloperRole: false
          supportsReasoningEffort: true
          maxTokensField: max_tokens
          reasoningEffortMap:
            high: high
            xhigh: max
          supportsToolChoice: false
          requiresReasoningContentForToolCalls: true
          requiresAssistantContentForToolCalls: true
        extraBody:
          thinking:
            type: enabled
      - id: gemini-2.5-flash
        name: Gemini 2.5 Flash
        reasoning: false
        input: [text]
        contextWindow: 1000000
        maxTokens: 65536
        compat:
          supportsDeveloperRole: false
          maxTokensField: max_tokens

关键配置说明 配置项说明baseUrlMoxAI 地址，按 MoxAI 标准写 /v1（Oh My Pi 内部会处理路径拼接）authHeader: true发送 Authorization: Bearer $MoxAI_API_KEYsupportsDeveloperRole: false以 system 角色发系统提示词maxTokensField: max_tokens输出限制字段使用 max_tokenssupportsToolChoice: falsethinking mode 下不接受 tool_choice 参数requiresReasoningContentForToolCalls: truetool call 对话的历史消息中必须保留 reasoning_contentrequiresAssistantContentForToolCalls: true确保 tool call 消息的 content 字段不为空

重要

models.yml 中的 compat 字段是 整块替换，不会与内置条目合并。必须写全所有需要的字段，缺失的字段会被当作默认值处理。

✅ 第三步：启动并验证

进入你的项目目录，带参数启动：

cd /path/to/your-project
omp --model moxai/claude-sonnet-4-6

需要更快响应时，切换到非推理模型：

omp --model moxai/gemini-2.5-flash

在 Oh My Pi 内随时按 Ctrl+L 或输入 /model 切换模型。

❓ 常见问题

问题解决方案启动后提示找不到 provider检查 ~/.omp/agent/models.yml 路径是否正确401 Unauthorized确认 MoxAI_API_KEY 已导出到当前 shell推理模型 tool call 报错确认 requiresReasoningContentForToolCalls: true 已启用切换模型后行为异常非推理模型请关闭 reasoning: true 和 extraBody.thinking

更多配置细节可参考 MoxAI 帮助中心原文。