Hướng dẫn sử dụng Codex với mọi mô hình mã nguồn mở (Chế độ OSS)

Codex đi kèm với các mô hình OpenAI theo mặc định, nhưng nó không buộc bạn phải sử dụng chúng. CLI có chế độ OSS tích hợp sẵn cho các môi trường chạy cục bộ như Ollama và LM Studio, cùng với hệ thống nhà cung cấp tùy chỉnh cho phép tác nhân kết nối với bất kỳ điểm cuối tương thích nào bạn định nghĩa trong tệp TOML. Điều đó có nghĩa là bạn có thể chạy gpt-oss trên máy tính xách tay của mình, điều khiển Codex bằng API DeepSeek hoặc Qwen được lưu trữ, hoặc chuyển đổi giữa các nhà cung cấp cho từng dự án.

Hướng dẫn này sẽ trình bày toàn bộ thiết lập: chế độ OSS làm gì, các khóa cấu hình chính xác, công thức cho từng mô hình và những đánh đổi bạn chấp nhận khi thay thế các mô hình của OpenAI. Mọi thông tin ở đây đều đến từ tài liệu cấu hình nâng cao chính thức của Codex. Những chỗ tài liệu không rõ ràng, tôi sẽ chỉ rõ thay vì phỏng đoán.

Một lưu ý trước khi bắt đầu. Khi mô hình của bạn đang chạy bên trong Codex, mô hình chỉ là một nửa của quy trình làm việc. Nửa còn lại là xác minh các API mà tác nhân của bạn xây dựng và gọi. Đó là nơi Apidog phát huy tác dụng, và chúng ta sẽ đề cập đến sự kết hợp này ở gần cuối.

Tóm tắt (TL;DR)

Chế độ Codex OSS là một tính năng của CLI. Chạy codex --oss và Codex sẽ nói chuyện với một máy chủ Ollama hoặc LM Studio cục bộ thay vì OpenAI. Đặt oss_provider = "ollama" trong ~/.codex/config.toml để đặt nó làm mặc định, và truyền -m <model> để chọn mô hình cục bộ nào chạy. Đối với các mô hình mã nguồn mở được lưu trữ (DeepSeek, Qwen, GLM thông qua API của họ), hãy định nghĩa một khối [model_providers.<id>] với base_url và env_key, sau đó chọn nó bằng model_provider. Vấn đề là: tài liệu tham khảo cấu hình hiện tại liệt kê responses là giá trị wire_api duy nhất được hỗ trợ, vì vậy điểm cuối của bạn cần phải tuân thủ giao thức Responses API.

Chế độ OSS là gì

Chế độ OSS là lối tắt của Codex để chạy với các máy chủ mô hình mã nguồn mở cục bộ. Tài liệu mô tả hai nhà cung cấp cục bộ được hỗ trợ:

Ollama, môi trường chạy mô hình cục bộ phổ biến
LM Studio, ứng dụng máy tính để bàn với máy chủ cục bộ tích hợp

Bạn kích hoạt nó bằng cờ --oss. Từ tài liệu tham khảo lệnh nhà phát triển Codex:

--oss: Sử dụng nhà cung cấp mô hình mã nguồn mở cục bộ. Codex sử dụng --local-provider, oss_provider đã cấu hình của bạn hoặc nhắc bạn chọn giữa LM Studio và Ollama.

Có một cờ đồng hành, --local-provider, chấp nhận lmstudio hoặc ollama và ghi đè mặc định của bạn cho một lần chạy duy nhất. Nếu bạn không đặt cả cờ lẫn cấu hình mặc định, CLI tương tác sẽ nhắc bạn chọn. Lệnh codex exec không tương tác sẽ không nhắc; nó sẽ thoát với lỗi. Vì vậy, đối với các tập lệnh và CI, hãy luôn đặt nhà cung cấp một cách rõ ràng.

Một lưu ý chân thật về các giao diện: tài liệu đề cập đến chế độ OSS và các nhà cung cấp tùy chỉnh trong hệ thống config.toml của CLI. Tiện ích mở rộng IDE và Codex cloud không được đề cập là hỗ trợ các nhà cung cấp cục bộ trong bất kỳ tài liệu cấu hình nào. [XÁC MINH: liệu tiện ích mở rộng IDE của Codex có đọc model_providers từ config.toml theo cách tương tự như CLI hay không; tài liệu không nói rõ cả hai.] Hãy coi đây là một quy trình làm việc CLI cho đến khi OpenAI tài liệu hóa khác đi.

Tại sao lại chạy một mô hình mã nguồn mở bên trong Codex

Câu hỏi hợp lý, vì Codex là tác nhân của chính OpenAI. Dưới đây là một vài lý do thực tế:

Kiểm soát chi phí. Suy luận cục bộ thông qua Ollama không tốn bất kỳ chi phí nào cho mỗi token. Nếu bạn đang sử dụng hết giới hạn sử dụng trong các phiên tác nhân dài, một mô hình cục bộ sẽ xử lý công việc cơ bản trong khi bạn tiết kiệm các cuộc gọi được lưu trữ cho các vấn đề khó khăn.
Quyền riêng tư và công việc không kết nối mạng. Một số cơ sở mã không thể rời khỏi máy. Một mô hình Kimi, GLM hoặc gpt-oss cục bộ sẽ giữ mọi token trên phần cứng của bạn. Hướng dẫn của chúng tôi về chạy Kimi K3 cục bộ đề cập đến những gì cần thiết trong thực tế.
Ưu tiên mô hình. Các mô hình mã nguồn mở đã thu hẹp phần lớn khoảng cách về mã hóa. Các API được lưu trữ của DeepSeek và Qwen có giá thấp hơn so với OpenAI trong khi đạt điểm trong phạm vi trên các điểm chuẩn mã hóa, và bạn có thể đơn giản là thích cách một mô hình cụ thể viết mã.
Một hệ thống tác nhân, nhiều mô hình. Giao diện người dùng terminal, khả năng cách ly (sandboxing) và quy trình phê duyệt của Codex rất tốt. Cấu hình nhà cung cấp cho phép bạn giữ lại hệ thống đó và thay đổi "bộ não" (mô hình).

Nơi cấu hình cư trú

Codex lưu trữ trạng thái dưới CODEX_HOME, mặc định là ~/.codex. Cấu hình cấp người dùng của bạn là ~/.codex/config.toml, và một kho lưu trữ có thể chứa các ghi đè cấp dự án trong .codex/config.toml. Mọi thứ bên dưới sẽ được đặt trong một trong hai tệp này.

Bắt đầu nhanh: Codex với Ollama

Con đường nhanh nhất để có một mô hình mã nguồn mở trong Codex là Ollama.

Cài đặt Ollama từ ollama.com và khởi động nó. Nó cung cấp một API tương thích OpenAI trên cổng 11434.
Kéo một mô hình. Bản phát hành mã nguồn mở của OpenAI là lựa chọn đầu tiên tự nhiên; trang thư viện gpt-oss có các biến thể 20b và 120b. Chúng tôi đã đề cập đến thiết lập độc lập trong bài cách chạy gpt-oss bằng Ollama.

ollama pull gpt-oss:20b

Chạy Codex ở chế độ OSS và đặt tên mô hình:

codex --oss -m gpt-oss:20b

Cờ -m/--model ghi đè mô hình đã cấu hình, và kết hợp với --oss nó chọn mô hình cục bộ nào chạy. Đối với việc sử dụng không tương tác:

codex exec --oss --local-provider ollama -m gpt-oss:20b "add input validation to the signup route"

Đặt nó làm mặc định để bạn có thể bỏ qua các cờ. Trong ~/.codex/config.toml:

# Default local provider used with `--oss`
oss_provider = "ollama" # or "lmstudio"

Đó là toàn bộ tính năng dành cho các mô hình cục bộ. Không cần khóa API, không cần khối nhà cung cấp tùy chỉnh. LM Studio hoạt động tương tự: tải một mô hình vào ứng dụng, khởi động máy chủ cục bộ của nó và chạy codex --oss --local-provider lmstudio. Xem lmstudio.ai để biết thiết lập máy chủ.

Các nhà cung cấp tùy chỉnh: kết nối Codex với bất kỳ điểm cuối tương thích nào

Chế độ OSS bao gồm Ollama và LM Studio. Đối với tất cả những thứ khác, như API DeepSeek hoặc Qwen được lưu trữ, một proxy, một máy chủ vLLM trên mạng LAN của bạn, Codex có các nhà cung cấp mô hình tùy chỉnh. Tài liệu định nghĩa nhà cung cấp là “cách Codex kết nối với một mô hình (URL cơ sở, API giao thức, xác thực và các tiêu đề HTTP tùy chọn).”

Mẫu từ tài liệu chính thức:

model = "gpt-5.6-terra"
model_provider = "proxy"

[model_providers.proxy]
name = "OpenAI using LLM proxy"
base_url = "http://proxy.example.com"
env_key = "OPENAI_API_KEY"

[model_providers.local_ollama]
name = "Ollama"
base_url = "http://localhost:11434/v1"

[model_providers.mistral]
name = "Mistral"
base_url = "https://api.mistral.ai/v1"
env_key = "MISTRAL_API_KEY"

Các khóa quan trọng:

Khóa	Chức năng
`model_provider`	ID nhà cung cấp mà Codex sử dụng (mặc định: `openai`)
`model`	Tên mô hình được gửi đến nhà cung cấp đó
`name`	Tên hiển thị của nhà cung cấp
`base_url`	URL cơ sở của API
`env_key`	Biến môi trường chứa khóa API
`wire_api`	Giao thức được sử dụng bởi nhà cung cấp
`query_params`	Các tham số truy vấn bổ sung được thêm vào các yêu cầu
`http_headers` / `env_http_headers`	Các tiêu đề tĩnh, hoặc các tiêu đề được điền từ biến môi trường

Điều chỉnh mạng cho từng nhà cung cấp cũng có sẵn: request_max_retries (mặc định 4), stream_max_retries (mặc định 5) và stream_idle_timeout_ms (mặc định 300000). Phần cứng cục bộ chậm sẽ hưởng lợi từ thời gian chờ không hoạt động lâu hơn, vì một mô hình 120b trên máy tính xách tay có thể nằm im một lúc giữa các token.

Hai quy tắc được tài liệu trực tiếp nêu ra. Thứ nhất, các ID openai, ollama và lmstudio được bảo lưu; bạn không thể ghi đè các nhà cung cấp tích hợp sẵn. Để thay đổi URL cơ sở của nhà cung cấp OpenAI tích hợp sẵn, hãy đặt openai_base_url thay vì tạo [model_providers.openai]. Thứ hai, và điều này định hình mọi thứ: tài liệu tham khảo cấu hình nêu rõ rằng đối với wire_api, “responses là giá trị duy nhất được hỗ trợ, và đó là giá trị mặc định khi bị bỏ qua.”

Đó là một ràng buộc thực sự. Các phiên bản Codex trước đây chấp nhận wire_api = "chat" cho các điểm cuối Chat Completions, và trang tổng quan mô hình vẫn nói rằng bạn có thể kết nối Codex với các nhà cung cấp hỗ trợ “API Chat Completions hoặc Responses.” Tài liệu tham khảo và trang tổng quan không thống nhất. [XÁC MINH: liệu wire_api = "chat" vẫn hoạt động trong bản phát hành CLI hiện tại hay không; tài liệu tham khảo cấu hình nói chỉ hỗ trợ responses, trang mô hình ngụ ý rằng chat vẫn hoạt động. Hãy kiểm tra với một điểm cuối chỉ hỗ trợ chat trước khi xuất bản.] Nếu chỉ hỗ trợ responses là đúng, thì nhà cung cấp của bạn cần một điểm cuối Responses API, điều mà hầu hết các máy chủ tương thích OpenAI hiện nay đều cung cấp nhưng một số API được lưu trữ vẫn chưa.

Công thức cấu hình từng mô hình

Mỗi công thức dưới đây là một khối cấu hình cộng với lệnh để chạy. Đặt biến môi trường khóa API trước khi khởi chạy.

DeepSeek (API được lưu trữ)

DeepSeek đã thêm hỗ trợ Responses API cùng với bản beta V4 Flash của họ, đây chính xác là những gì giao thức của Codex mong muốn. Chúng tôi đã đề cập đến việc triển khai đó trong bài viết DeepSeek V4 Flash, Responses API và Codex.

model = "deepseek-chat"
model_provider = "deepseek"

[model_providers.deepseek]
name = "DeepSeek"
base_url = "https://api.deepseek.com"
env_key = "DEEPSEEK_API_KEY"

export DEEPSEEK_API_KEY="sk-..."
codex

Kiểm tra tài liệu API của DeepSeek để biết các ID mô hình hiện tại. [XÁC MINH: đường dẫn base_url chính xác mà DeepSeek tài liệu hóa để truy cập giao thức Responses; đường dẫn /v1 chat có thể khác với đường dẫn Responses.]

Qwen (được lưu trữ qua Model Studio)

Model Studio (DashScope) của Alibaba cung cấp chế độ tương thích OpenAI cho dòng Qwen 3.8. Điểm cuối chế độ tương thích này theo lịch sử có dạng Chat Completions. [XÁC MINH: liệu chế độ tương thích của DashScope hiện có phục vụ giao thức Responses hay không; nếu không, công thức này phụ thuộc vào câu hỏi wire_api = "chat" ở trên.]

model = "qwen3.8-max"
model_provider = "qwen"

[model_providers.qwen]
name = "Qwen via Model Studio"
base_url = "https://dashscope-intl.aliyuncs.com/compatible-mode/v1"
env_key = "DASHSCOPE_API_KEY"

Hướng dẫn API Qwen 3.8 của chúng tôi đề cập đến các khóa, ID mô hình và giá cả cho tuyến đường được lưu trữ.

Kimi, GLM và các mô hình mã nguồn mở khác (cục bộ qua Ollama)

Bất cứ thứ gì bạn có thể kéo vào Ollama đều hoạt động qua chế độ OSS đơn giản, không cần khối nhà cung cấp:

ollama pull <model>
codex --oss -m <model>

Điều đó bao gồm các mô hình mã nguồn mở GLM và Qwen, cộng với Kimi K3 nếu phần cứng của bạn chịu đựng được (trọng lượng K3 là 594 GB ở MXFP4, vì vậy hầu hết mọi người nên đọc chạy Kimi K3 cục bộ trước khi thử). Đối với các máy tầm trung, gpt-oss:20b hoặc bản dựng Qwen coder được lượng tử hóa là lựa chọn thực tế.

vLLM tự lưu trữ hoặc máy chủ LAN

Một máy chủ vLLM hoặc máy chủ tương thích OpenAI tương tự trên một máy khác là một nhà cung cấp tùy chỉnh, không phải chế độ OSS:

model_provider = "lan_vllm"

[model_providers.lan_vllm]
name = "vLLM on the workstation"
base_url = "http://192.168.1.50:8000/v1"
env_key = "VLLM_API_KEY"

Hồ sơ: thay đổi "bộ não" theo từng tác vụ

Bạn không cần phải chọn một thiết lập duy nhất. Các hồ sơ của Codex là các tệp TOML riêng biệt tại ~/.codex/<profile-name>.config.toml, được xếp chồng lên cấu hình cơ sở của bạn khi bạn truyền --profile. Một hồ sơ mô hình cục bộ trông như thế này:

# ~/.codex/oss-local.config.toml
oss_provider = "ollama"
model = "gpt-oss:20b"

codex --profile oss-local
codex exec --profile oss-local "write unit tests for utils/dates.ts"

Giữ cấu hình mặc định của bạn cho các mô hình OpenAI để tái cấu trúc khó khăn và bật --profile oss-local để sửa lỗi cú pháp, xây dựng khung kiểm thử và viết tài liệu. Các ghi đè một lần cũng hoạt động mà không cần hồ sơ: codex -c model='"deepseek-chat"' -c model_provider='"deepseek"'.

Sự đánh đổi so với các mô hình OpenAI

Hãy thành thật với bản thân về những gì bạn đang đánh đổi:

Khả năng. gpt-oss:20b không phải là gpt-5.6-terra. Các mô hình cục bộ thường thất bại nhiều hơn trong các chỉnh sửa nhiều tệp dài, và các vòng lặp tác nhân khuếch đại điểm yếu của mô hình vì mỗi bước đều dựa trên bước trước đó.
Tốc độ. Các API được lưu trữ truyền tải nhanh chóng. Một mô hình cục bộ lớn trên phần cứng tiêu dùng có thể đủ chậm để thay đổi cách bạn làm việc.
Độ trung thực của công cụ. Các lời nhắc và cuộc gọi công cụ của Codex được điều chỉnh cho các mô hình OpenAI. Các mô hình mã nguồn mở thay đổi về độ tin cậy trong việc tạo ra các cuộc gọi công cụ, và giao thức chỉ hỗ trợ responses thu hẹp các điểm cuối nào đủ điều kiện.
Bề mặt hỗ trợ. Chế độ OSS là một đường dẫn CLI được tài liệu hóa, nhưng các nhà cung cấp bên thứ ba là trách nhiệm của bạn: ID mô hình, giới hạn tốc độ và những điều kỳ quặc của giao thức là giữa bạn và nhà cung cấp.

Sự phân chia thực tế: các mô hình cục bộ hoặc được lưu trữ giá rẻ cho công việc khối lượng lớn, ít rủi ro; các mô hình tiên tiến cho các tác vụ mà một lần chạy thất bại sẽ khiến bạn mất cả buổi chiều.

Xác minh các API mà tác nhân của bạn tương tác

Bất kể mô hình nào chạy bên trong Codex, đầu ra thường là mã gọi hoặc định nghĩa API, và các mô hình mã nguồn mở thường xuyên tạo ra các điểm cuối và lược đồ không có thật hơn so với các mô hình tiên tiến. Hãy phát hiện điều đó ở lớp API thay vì trong môi trường sản xuất.

Apidog bao quát phía đó của quy trình làm việc. Hãy trỏ máy chủ Apidog MCP vào dự án của bạn và tác nhân Codex của bạn có thể đọc đặc tả API thực tế trong khi nó viết mã, thay vì tự ý tạo tên trường. Sau đó, sử dụng Apidog CLI bên trong Codex để cho phép tác nhân chạy các kịch bản kiểm thử của bạn từ terminal sau mỗi thay đổi: nó chỉnh sửa, nó kiểm thử, bạn xem xét một bản diff đã vượt qua. Vòng lặp đó càng quan trọng hơn, chứ không phải ít hơn, khi một mô hình nhỏ hơn viết mã. Tải xuống Apidog để kết nối nó; CLI và máy chủ MCP hoạt động với bất kỳ mô hình nào bạn đã cấu hình.

Khắc phục sự cố

codex exec báo lỗi ngay lập tức ở chế độ OSS. Bạn chưa đặt nhà cung cấp. Các lần chạy không tương tác không bao giờ nhắc, vì vậy hãy truyền --local-provider ollama hoặc đặt oss_provider trong cấu hình.
Kết nối bị từ chối trên cổng 11434. Ollama không chạy, hoặc nó được ràng buộc với một địa chỉ khác. Khởi động ứng dụng hoặc ollama serve, và xác nhận bằng curl http://localhost:11434/v1/models.
Lỗi 404 hoặc giao thức từ một nhà cung cấp được lưu trữ. Định dạng base_url sai, hoặc điểm cuối không tuân thủ giao thức Responses. Kiểm tra xem nhà cung cấp có tài liệu về đường dẫn tương thích Responses hay không.
Lỗi xác thực. env_key đặt tên một biến môi trường; Codex đọc khóa từ môi trường shell của bạn khi khởi chạy. Hãy xuất nó trong cùng một shell, và nhớ rằng launchd hoặc CI shells có thể không tải các tệp dotfile của bạn.
Các luồng dữ liệu bị dừng giữa chừng khi tạo ra trên một mô hình cục bộ chậm. Tăng stream_idle_timeout_ms và stream_max_retries trong khối nhà cung cấp.
Các chỉnh sửa cấu hình bị bỏ qua. Kiểm tra xem có tệp .codex/config.toml cấp dự án nào đang ghi đè cấu hình người dùng của bạn không, và nhớ rằng các hồ sơ được xếp chồng lên trên cả hai.

Câu hỏi thường gặp (FAQ)

Chế độ OSS của Codex có hoạt động trong tiện ích mở rộng IDE hoặc Codex cloud không?

Các tài liệu mô tả chế độ OSS và các nhà cung cấp tùy chỉnh như một phần của hệ thống cấu hình CLI. Hỗ trợ IDE hoặc đám mây cho các nhà cung cấp cục bộ không được tài liệu hóa, vì vậy hãy coi đây là một tính năng của CLI. [XÁC MINH trước khi dựa vào hỗ trợ IDE.]

Những mô hình nào hoạt động tốt nhất với Codex ở chế độ OSS?

Bất cứ điều gì Ollama hoặc LM Studio có thể phục vụ trên phần cứng của bạn. gpt-oss:20b là mặc định ít ma sát. Các tùy chọn mã hóa mã nguồn mở mạnh mẽ bao gồm dòng Qwen 3.8 và GLM; đối với các mô hình khổng lồ như Kimi K3, hãy kiểm tra tính toán phần cứng trong hướng dẫn Kimi K3 cục bộ của chúng tôi trước.

Tôi có thể sử dụng OpenRouter hoặc một trình tổng hợp khác với Codex không?

Bất kỳ trình tổng hợp nào cung cấp một điểm cuối tương thích đều phù hợp với mẫu [model_providers.<id>]: đặt base_url và env_key, sau đó chọn nó bằng model_provider. Câu hỏi mở là về giao thức: tài liệu tham khảo cấu hình liệt kê responses là wire_api duy nhất được hỗ trợ, vì vậy hãy xác nhận rằng trình tổng hợp của bạn phục vụ Responses API.

Tôi có cần khóa API OpenAI để chạy Codex với một mô hình mã nguồn mở không?

Không cần khóa nào cho chế độ OSS với máy chủ Ollama hoặc LM Studio cục bộ. Các nhà cung cấp được lưu trữ tùy chỉnh sử dụng khóa riêng của họ thông qua env_key. Bạn vẫn đăng nhập vào Codex như bình thường đối với bất kỳ thứ gì liên quan đến dịch vụ của OpenAI.

Hãy thiết lập phù hợp với tác vụ. Một gpt-oss cục bộ cho các vòng lặp chi phí thấp, DeepSeek hoặc Qwen khi bạn muốn tốc độ được lưu trữ với chi phí thấp hơn, và các mô hình tiên tiến của OpenAI khi vấn đề khó. Cấu hình của Codex làm cho cả ba chỉ cách nhau một cờ, và với Apidog xử lý xác minh ở phía API, mô hình trở thành một phần có thể thay thế được thay vì một cam kết.