Hướng dẫn tích hợp công cụ

Agent lập trình có CLI và desktop, hỗ trợ đọc mã, sửa file, chạy lệnh. Tải OpenCode · Tài liệu provider.

1. Cài OpenCode và kiểm tra opencode --version.
2. Gộp provider sau vào ~/.config/opencode/opencode.jsonc (Windows: %USERPROFILE%\.config\opencode\opencode.jsonc):

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "aimodelmark": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "AI Model Mark",
      "options": {
        "baseURL": "https://aimodelmark.com/v1",
        "apiKey": "{env:AI_MODEL_MARK_KEY}"
      },
      "models": {
        "claude-haiku-4.5": {"name": "Claude Haiku 4.5", "limit": {"context": 131072, "output": 4096}, "reasoning": true, "options": {"reasoningEffort": "medium"}},
        "gpt-5.6-luna": {"name": "GPT 5.6 Luna", "limit": {"context": 131072, "output": 4096}, "reasoning": true, "options": {"reasoningEffort": "medium"}},
        "gpt-6-astra": {"name": "GPT 6 Astra Smart", "limit": {"context": 131072, "output": 2048}, "modalities": {"input": ["text", "image"], "output": ["text"]}}
      }
    }
  },
  "model": "aimodelmark/claude-haiku-4.5"
}

Hai alias Mini có context công bố 131.072 token và cho chọn mức suy luận low, medium, high trong OpenCode. Đây là mức giới hạn context của dịch vụ; mỗi request vẫn cần nằm trong quota và giới hạn output của gói. Nhà cung cấp hiện không trả riêng bản ghi quá trình suy luận để hiển thị trên client.

Thử: chọn aimodelmark/claude-haiku-4.5 trong /models, yêu cầu tạo file chứa 7 rồi đọc lại. Để đọc ảnh, chọn aimodelmark/gpt-6-astra và đính kèm một ảnh PNG/JPEG phù hợp giới hạn ở trên. CLI/WSL đã đọc đúng ảnh màu và tạo/đọc file trong một tác vụ có ảnh. OpenCode desktop trên Windows cũng đã đọc đúng ảnh mẫu sau khi khởi động lại để nạp cấu hình; lượt thử đó mất khoảng 62 giây.

Cấu hình nhanh Windows: Tải bộ cấu hình, giải nén và chạy setup-opencode.cmd. Script sao lưu cấu hình hiện có trước khi thêm AI Model Mark.

WSL/Linux: nếu OpenCode báo 401 missing api key dù đã lưu key qua opencode auth, dùng trình khởi chạy WSL: python3 aimodelmark-opencode-wsl.py run -m aimodelmark/claude-haiku-4.5 "Reply exactly OK.". Trình này đọc key đang lưu của provider khi chạy và không ghi key vào file cấu hình.

Trợ lý lập trình terminal có thể đọc repository và dùng shell. Tải/cài đặt và quickstart chính thức.

1. Cài theo quickstart, kiểm tra qwen --version.
2. Tạo profile AI Model Mark riêng tại %USERPROFILE%\.qwen-aimodelmark\settings.json trên Windows; đặt QWEN_HOME trỏ tới thư mục này khi chạy Qwen. Trên Linux/WSL dùng một thư mục profile riêng tương ứng. Không khai báo modelFallbacks sang provider khác:

{
  "modelProviders": {
    "openai": [{
      "id": "gpt-5.6-luna",
      "name": "AI Model Mark — GPT 5.6 Luna",
      "envKey": "AI_MODEL_MARK_KEY",
      "baseUrl": "https://aimodelmark.com/v1",
      "wireApi": "chat-completions",
      "generationConfig": {
        "samplingParams": {"max_tokens": 4096},
        "contextWindowSize": 131072
      }
    }]
  },
  "security": {"auth": {"selectedType": "openai"}},
  "model": {"name": "gpt-5.6-luna"}
}

Thử: chạy start-qwen-code.cmd --safe-mode -p "Đọc sample.txt bằng read_file và trả về nội dung" -o json. Bài CLI Windows đã dùng gpt-5.6-luna, gọi tool đọc file và thoát thành công; thống kê xác nhận không chuyển sang AgentGW. Desktop và tác vụ dài chưa được nghiệm thu độc lập.

Cấu hình nhanh Windows: Tải bộ cấu hình, giải nén và chạy setup-qwen-code.cmd, sau đó dùng start-qwen-code.cmd. Bộ cài tạo profile riêng, tải Node 22 portable từ trang chính thức và kiểm tra SHA-256; không thay Node hệ thống hoặc cấu hình Qwen đang dùng cho provider khác. Trên máy thử, Qwen chạy với Node 24 trả lời xong nhưng thoát bằng lỗi runtime; Node 22 đã xử lý được lỗi này.

Trợ lý agent hỗ trợ phiên làm việc, công cụ và nhiều provider. Cài đặt và tài liệu chính thức.

1. Cài Hermes; dùng hermes config path để tìm cấu hình. Có thể tạo profile riêng để giữ nguyên thiết lập cũ.
2. Thêm provider vào config.yaml:

model:
  default: gpt-5.6-luna
  provider: aimodelmark
  max_tokens: 2048
providers:
  aimodelmark:
    name: AI Model Mark
    base_url: https://aimodelmark.com/v1
    api_mode: chat_completions
    key_env: AI_MODEL_MARK_KEY
    default_model: gpt-5.6-luna
    models:
      gpt-5.6-luna: {}
      gpt-6-astra: {supports_vision: true}

Giới hạn output: đặt model.max_tokens: 2048 trong profile riêng của AI Model Mark, hoặc chạy qua start-hermes.cmd để chỉ áp giới hạn cho phiên đó. Mặc định Hermes có thể yêu cầu 65.536 output tokens và bị router từ chối.

Thử: hermes config check, rồi start-hermes.cmd -q "Trả lời đúng OK" --max-turns 1. Với ảnh, chọn gpt-6-astra và gọi hermes chat --provider aimodelmark -m gpt-6-astra --image anh.png -q "Mô tả ảnh" --max-turns 1 trong phiên đặt HERMES_MAX_TOKENS=2048. Nếu thiếu supports_vision: true, Hermes chỉ gửi đường dẫn ảnh dưới dạng chữ, không gửi nội dung ảnh. Trên Bash/WSL, đặt HERMES_MAX_TOKENS=2048 trước khi gọi hermes chat.

Cấu hình nhanh Windows: Tải bộ cấu hình, giải nén và chạy setup-hermes.cmd, sau đó mở qua start-hermes.cmd. Bộ cài tạo profile riêng %USERPROFILE%\.hermes-aimodelmark và chuẩn bị dependency lần đầu; profile Hermes/AgentGW đang dùng được giữ nguyên. Profile riêng cũng tránh lỗi đường dẫn quá dài của Python SDK trên một số máy Windows. Để thử ảnh: start-hermes.cmd -m gpt-6-astra --image anh.png -q "Mô tả ảnh" --max-turns 1. Windows CLI và WSL CLI đã đọc đúng ảnh mẫu. Hermes Desktop cũng đã gửi ảnh qua alias Fable 5.1 từ profile AI Model Mark hiện có và trả lời đúng hai màu; desktop chưa được thử với profile CLI riêng của bộ cài.

Agent mã nguồn mở có desktop/CLI và extension để thao tác file, lệnh. Tải Goose · Tài liệu custom provider.

1. Cài Goose. Trong Desktop chọn Settings → Models → Configure providers → Add Custom Provider → Anthropic Compatible; URL https://aimodelmark.com, model claude-haiku-4.5, nhập key vào kho khóa ứng dụng.
2. CLI/WSL: tạo ~/.config/goose/custom_providers/aimodelmark_mini_agent.json (Windows: %APPDATA%\Block\goose\config\custom_providers\):

{
  "name": "aimodelmark_mini_agent",
  "engine": "anthropic",
  "display_name": "AI Model Mark Mini Agent",
  "api_key_env": "AI_MODEL_MARK_KEY",
  "base_url": "https://aimodelmark.com",
  "models": [{"name": "claude-haiku-4.5", "context_limit": 131072}],
  "requires_auth": true,
  "supports_streaming": true
}

supports_streaming bật khả năng đọc định dạng SSE trong Goose; nội dung hiện được gửi sau khi model hoàn tất, chưa hiện từng token.

Thử: đặt GOOSE_MAX_TOKENS=4096 cho phiên chạy, rồi gọi goose run --provider aimodelmark_mini_agent --model claude-haiku-4.5 --with-builtin developer --no-session --max-turns 3 -t "Tạo sample.txt chứa số 7 rồi đọc lại". CLI đã đọc file qua tool và trả lời thành công. Trên Bash dùng export GOOSE_MAX_TOKENS=4096; trên PowerShell dùng $env:GOOSE_MAX_TOKENS='4096'.

Cấu hình nhanh Windows: Tải bộ cấu hình, giải nén và chạy setup-goose.cmd, sau đó mở Goose CLI bằng start-goose.cmd để áp giới hạn output cho riêng phiên này. Script sao lưu cấu hình hiện có trước khi thêm AI Model Mark.

Agent lập trình có terminal, web và chế độ headless. Tải OpenHands CLI và tài liệu.

1. Cài OpenHands CLI.
2. Trong Bash/WSL đặt biến và chạy một tác vụ ở thư mục mẫu:

export LLM_MODEL="openai/claude-haiku-4.5"
export LLM_BASE_URL="https://aimodelmark.com/v1"
export LLM_API_KEY="$AI_MODEL_MARK_KEY"
openhands --headless --json --override-with-envs -t "Tạo sample.txt chứa số 7 rồi đọc lại"

Tiền tố openai/ chỉ chọn giao thức client; model gửi đến dịch vụ là claude-haiku-4.5. CLI đã tạo file, thực hiện thêm một tool call và kết thúc với câu trả lời.

GPT-6 Sol trong OpenHands CLI

Đã thử trên OpenHands CLI 1.16.0 / SDK 1.21.0: trả lời văn bản, đọc file bằng terminal tool, sửa lỗi Python và chạy lại unit test. OpenHands chỉ nhận LLM_MODEL, LLM_BASE_URL, LLM_API_KEY qua --override-with-envs; biến LLM_MAX_OUTPUT_TOKENS không đặt giới hạn output. Nếu không có profile, client có thể gửi max_completion_tokens=128000 và router sẽ từ chối.

1. Trong WSL/Linux, tải script cấu hình GPT-6 Sol, xem nội dung rồi chạy từ thư mục dự án. Script tạo profile riêng ~/.openhands-aimodelmark-sol/agent_settings.json với max_output_tokens: 8192; không ghi API key vào file và không đổi profile OpenHands hiện có.
2. Chạy thử:

bash setup-openhands-sol.sh --headless --json --exit-without-confirmation \
  -t "Đọc file sample.txt bằng terminal tool và cho biết nội dung"

Script hỏi API key nếu chưa có biến AI_MODEL_MARK_KEY. Trên Windows, chạy script này trong WSL đã cài OpenHands. Khi muốn mở giao diện tương tác, dùng bash setup-openhands-sol.sh. Profile đặt openai/gpt-6-sol, https://aimodelmark.com/v1 và output tối đa 8.192 tokens; tiền tố openai/ chỉ định giao thức, API nhận model gpt-6-sol. Bài test thực tế xác nhận yêu cầu gửi max_completion_tokens=8192 và được HTTP 200.

Cấu hình nhanh Windows: Tải bộ cấu hình, giải nén và chạy start-openhands.cmd. File này mở công cụ với biến môi trường đúng cho phiên chạy; không đổi thiết lập provider mặc định.

Thư viện xây workflow/agent có trạng thái bằng đồ thị, phù hợp khi muốn tự kiểm soát từng bước model → tool → model. Tài liệu và cài đặt chính thức.

1. Tạo môi trường Python, cài python -m pip install langgraph openai.
2. Tạo client với base URL và key của dịch vụ:

import os
from openai import OpenAI
client = OpenAI(
    api_key=os.environ["AI_MODEL_MARK_KEY"],
    base_url="https://aimodelmark.com/v1",
)
model = "gpt-5.6-luna"

Trong node model, truyền messages và định nghĩa tool cho client.chat.completions.create(..., tools=[...]). Khi model yêu cầu gọi tool, nối assistant message chứa tool_calls, chạy hàm ở ứng dụng, nối một message role="tool" với đúng tool_call_id, rồi gọi model lần hai. Giữ nguyên history của phiên trong trạng thái graph, không chỉ gửi câu hỏi cuối.

Thử: tạo tool add(a,b), hỏi 2 + 5 và kiểm tra câu trả lời cuối là 7. Chu trình model → tool → model đã qua bài thử Chat Completions.

Codex CLI là agent lập trình chạy trong terminal: đọc repository, giải thích code, sửa lỗi, viết tính năng và chạy lệnh kiểm thử. Dịch vụ được kết nối bằng API key AI Model Mark qua /v1/responses. Codex CLI chính thức · Node.js · Tài liệu kết nối gateway.

Cấu hình đã kiểm thử: Codex CLI 0.160.0, Responses qua HTTPS, gọi công cụ tự động, reasoning medium, profile riêng và catalog tương thích. Chọn gpt-6.1-sol, gpt-5.6-sol hoặc gpt-5.6-luna; đây là các alias Smart của AI Model Mark. Cấu hình không yêu cầu đăng nhập ChatGPT và không thay profile Codex/OAuth hiện có.

Windows: tải một file và chạy

1. Cài Node.js 22 LTS nếu chưa có, rồi mở lại terminal. Tạo API key trong mục API key của tài khoản AI Model Mark.
2. Tải file cấu hình Codex (.cmd) và mở file. Bộ cài chứa sẵn script và catalog; không cần tải thêm file cấu hình. Nếu trình duyệt đổi đuôi thành .txt, đổi lại thành .cmd. Có thể tải bộ ZIP để xem script trước khi chạy.
3. Nhập API key khi được hỏi (key không hiện trên màn hình), chọn model và chờ cài xong. Key được mã hóa bằng DPAPI cho tài khoản Windows hiện tại; cấu hình cũ trong profile AI Model Mark được sao lưu trước khi ghi.
4. Mở terminal tại thư mục dự án và chạy:

"%LOCALAPPDATA%\AIModelMark\Codex\start.cmd"

Trong PowerShell, dùng:

& "$env:LOCALAPPDATA\AIModelMark\Codex\start.cmd"

Bộ cài dùng thư mục %LOCALAPPDATA%\AIModelMark\Codex, cài Codex riêng và không lưu API key vào biến môi trường User. Không chia sẻ thư mục profile hoặc file key mã hóa.

Ubuntu, VPS và WSL

1. Chuẩn bị Node.js 22 LTS, npm, unzip và bộ chứng chỉ ca-certificates. Nên chạy Codex bằng tài khoản người dùng thông thường và trong thư mục dự án riêng.
2. Tải bộ cài từ website:

mkdir -p ~/aimodelmark-codex-setup
cd ~/aimodelmark-codex-setup
curl -fL https://aimodelmark.com/downloads/aimodelmark-codex-setup.zip -o setup.zip
unzip -o setup.zip
bash setup-codex-aimodelmark.sh

Mở terminal tại repository của bạn rồi chạy:

~/.local/share/aimodelmark-codex/start.sh

Trình khởi chạy hỏi API key ở mỗi lần mở và chỉ truyền key cho tiến trình hiện tại. Không ghi key vào cấu hình hoặc lịch sử lệnh. Profile riêng giữ lại các phiên để có thể tiếp tục công việc. Nếu đã đặt XDG_DATA_HOME, dùng đường dẫn start.sh mà bộ cài in ra.

Thông số kết nối

Bộ cài thiết lập đầy đủ catalog và các tùy chọn tương thích. Đoạn sau minh họa phần provider; chỉ sao chép đoạn này không thay thế được bộ cấu hình đầy đủ:

model = "gpt-6.1-sol"
model_provider = "aimodelmark"
model_reasoning_effort = "medium"
web_search = "disabled"
approval_policy = "on-request"
sandbox_mode = "workspace-write"

[model_providers.aimodelmark]
name = "AI Model Mark"
base_url = "https://aimodelmark.com/v1"
wire_api = "responses"
env_key = "AI_MODEL_MARK_KEY"
requires_openai_auth = false
supports_websockets = false

Catalog đi kèm dùng function tools phù hợp với tuyến API. Codex đọc, ghi file và chạy test qua công cụ shell; lựa chọn công cụ giữ ở chế độ tự động. Bộ cài cố định phiên bản đã nghiệm thu để tránh thay đổi định dạng công cụ khi cập nhật. Khi có bản mới đã kiểm thử, chạy lại bộ cài từ website.

Chạy thử với dự án của bạn

1. Đọc code: “Đọc README và các file cấu hình. Giải thích cấu trúc dự án, cách chạy test và ba điểm cần lưu ý. Chưa sửa file.”
2. Sửa lỗi: “Chạy bộ test hiện có, tìm nguyên nhân test thất bại, sửa phần triển khai liên quan. Không sửa test để né lỗi. Chạy lại test và báo kết quả.”
3. Viết tính năng: “Thêm hàm phân trang có kiểm tra tham số, giữ nguyên dữ liệu đầu vào. Viết test cho trang bình thường, dữ liệu rỗng, vượt trang và tham số sai. Chạy toàn bộ test.”

Kiểm tra lệnh và thay đổi code trước khi đồng ý chạy. Bộ cài giữ chế độ xin phép on-request và vùng ghi workspace-write; không bật chế độ bỏ qua bảo vệ.

Đổi model cho một phiên hoặc tiếp tục phiên trước (ví dụ trên Linux):

~/.local/share/aimodelmark-codex/start.sh -m gpt-5.6-sol
~/.local/share/aimodelmark-codex/start.sh resume --last

Windows: thêm các tham số tương tự sau start.cmd. Dùng cùng profile và thư mục dự án để tiếp tục đúng phiên. History được lưu ở client và được gửi lại trong hội thoại; không cần bật store=true hoặc phụ thuộc previous_response_id tại một nguồn duy nhất.

Kết quả và phạm vi đã kiểm thử

Kiểm thử trên VPS với API key gói Mini: ba alias trên đã đọc file và sao chép chính xác nội dung, sửa lỗi tính phí cache qua bộ test độc lập, viết hàm phân trang rồi vượt kiểm tra độc lập. Các thao tác diễn ra bằng Codex CLI thật, gồm nhiều lượt gọi model → công cụ → model. Đây là bài kiểm tra khả năng làm việc với code; không phải chứng nhận chất lượng ngang model gốc hoặc cam kết mọi tác vụ đều hoàn thành.

Cấu hình này phục vụ tác vụ lập trình văn bản và function tools. Web search do nhà cung cấp lưu trữ, apps, code mode với công cụ namespace/custom và tác vụ ảnh/video chưa được nghiệm thu trong cấu hình Codex này. Những khả năng đó của dịch vụ có hướng dẫn riêng; không bật thêm tùy chọn Codex chỉ dựa vào tên model.

Xử lý lỗi thường gặp

• 401: kiểm tra API key AI Model Mark, chạy lại bộ cài để thay key; không dùng key ChatGPT hoặc key nguồn khác.
• 402: kiểm tra số dư khả dụng và thời hạn credit trong Dashboard.
• 400 về tool registry hoặc payload: dùng trọn bộ cấu hình và catalog đi kèm, kiểm tra phiên bản 0.160.0; không đổi wire_api sang chat.
• 503: có thể không còn tuyến đủ điều kiện tại thời điểm gọi. Router có fallback nhưng không thể bảo đảm kết nối khi mọi tuyến đều lỗi hoặc bị chặn. Gửi mã lỗi, model và thời điểm cho hỗ trợ; không cần nạp thêm tiền khi số dư vẫn đủ.
• Lỗi TLS trong container Ubuntu: kiểm tra đã cài/bind bộ ca-certificates. Giữ xác minh TLS, không tắt kiểm tra chứng chỉ.
• Mở nhầm phiên Codex/OAuth: khởi chạy bằng start.cmd hoặc start.sh của profile AI Model Mark.

Trợ lý tự động hóa có thể kết nối nhiều kênh và công cụ. Cài đặt chính thức · Tài liệu custom provider.

1. Cài và khởi tạo OpenClaw.
2. Gộp provider riêng vào phần models.providers của cấu hình; tham chiếu biến môi trường thay vì lưu key thật:

{
  models: {
    mode: "merge",
    providers: {
      aimodelmark: {
        baseUrl: "https://aimodelmark.com/v1",
        apiKey: "${AI_MODEL_MARK_KEY}",
        api: "openai-completions",
        models: [{id: "claude-haiku-4.5", name: "Claude Haiku 4.5"}]
      }
    }
  },
  agents: {defaults: {model: {primary: "aimodelmark/claude-haiku-4.5"}}}
}

Sau khi khởi động lại gateway, kiểm tra chat văn bản rồi thử tool trong workspace mẫu trước khi nối kênh thật.

Cấu hình này chưa được kiểm tra end-to-end với OpenClaw; chưa cam kết workflow agent nhiều vòng.

Orca của StablyAI điều phối nhiều coding agent trong terminal/worktree, không phải một model provider riêng. Giới thiệu chính thức · Tải bản Windows/macOS/Linux.

1. Cài Orca, chọn agent CLI như Claude Code hoặc OpenCode.
2. Cấu hình AI Model Mark cho agent con theo mục tương ứng ở trang này; bảo đảm terminal hoặc WSL do Orca mở có biến AI_MODEL_MARK_KEY.
3. Chạy bài đọc file mẫu và xác nhận agent con dùng đúng model.

Không tìm một trường “provider Orca” để nhập base URL. Phiên Orca hoàn chỉnh chưa được kiểm tra độc lập với dịch vụ.

Công cụ chạy worker/agent trên máy cá nhân. Tải và đọc tài liệu chính thức.

Nếu phiên bản của bạn có mục Add custom OpenAI-compatible provider độc lập, dùng https://aimodelmark.com/v1, key riêng và alias trong /v1/models; thử chat → tool → file trong workspace mẫu. Chỉ coi là dùng được khi đủ chu trình thành công.