openai-go: the version number is written into the readme, the Go floor is 1.25, and the WebSocket path defaults to no limit

The version number in the readme is written by a release tool

The readme is partly generated, and the seams are visible.

Three comment pairs bracket three blocks: the package documentation link, the import snippet, and the command that pins a version. Those markers are what a release tool looks for, and the content between them is replaced at release time. The manifest in the root confirms it, naming the release tool and carrying its own configuration file.

The block being replaced is the one that matters most to a reader, because it is the only place a version number appears:

go get -u 'github.com/openai/openai-go/[email protected]'

Right now that matches the newest release, so the file is in sync. But a version inside prose is a version that can go stale between releases, and the reader has no way to tell a hand-maintained pin from a generated one.

The import block carries the other kind of generated comment, noting that the import path carries a major version segment and is given a shorter local name in code. That short name is why every example in the readme refers to the package without the path.

A Go version floor, one named escape hatch, and no backports behind it

The requirements section is four sentences and contains the whole support policy.

From one named SDK release onward, Go 1.25 or later is required. An application that must stay on an older range of Go versions is told to pin one specific SDK release, described as the final compatible one. And then the sentence that matters most: older SDK releases receive no guaranteed fixes or security backports.

So the policy has three parts. A floor that is recent enough to be uncomfortable, a single named release for anyone who cannot take it, and an explicit statement that the versions behind that release are frozen rather than merely discouraged.

The readme points at a separate policy document for the supported release window and upgrade guidance, and the repository root carries that document alongside a code quality policy, a migration guide, and a security policy. Four policy files for one client library is unusual, and it is the clearest signal in this repository that the maintainers treat upgrade friction as something to be managed rather than mentioned once.

Above the requirements sits a warning box with a similar tone: the latest version has small and limited breaking changes, and the changelog has the details.

Six direct dependencies, two of them for reading and writing JSON

The module file is the most economical description of this library in existence.

There are six direct requirements. Two are the identity and configuration packages for one cloud provider, two are the equivalent for another, one is a WebSocket library, and two are a matched pair of JSON path libraries for reading and writing documents by path.

There is no web framework, no assertion library, no logging facade, and no code generation runtime. A library that wraps an entire API surface on six dependencies, none of them an HTTP framework, is doing its transport work with the standard library.

The two cloud SDKs are there for a reason: the examples include directories for two specific cloud deployments and for mutual TLS, so those paths are first-class rather than bolted on. The cost is that a Go developer who only wants the hosted API still resolves both cloud SDK trees, which is most of the indirect list in the file.

One entry in the indirect list is worth a second look. A library that launches a browser appears there, which is a reasonable dependency for an OAuth flow and an unusual one to find transitively under an API client.

The generated file names have no separators in them

The root directory is a naming convention, and the convention is that a file is named after the concatenation of its whole resource path.

The pattern is visible in a single family. There is a file for the admin resource, a file for the organisation resource under it, and then a file for the API key resource under the organisation under the admin resource, which is one unbroken word. Under project there are files for keys, certificates, retention settings, groups, group roles, hosted tool permissions, model permissions, rate limits, roles, and service accounts, each a single concatenated string, each with a test file beside it named the same way plus a suffix.

That is a machine-generated surface and it is honestly labelled as such by its regularity. Every resource has a test, the tests are named after their subjects, and the alphabetical order of the directory is the alphabetical order of the API. Nobody chose these names, and nobody will remember them.

What the naming costs is the thing a reader would use the directory for. If you want to know whether the library covers a particular endpoint, the answer is in a documentation file and in the module tree, not in the file list, because the file list is sorted into one long run of similar words.

The streaming transport ships with no receive limit

The WebSocket section contains the most useful warning in the readme, and it is a default rather than a bug.

The default options do not cap message size or the receive buffer. To get any limit at all you set one of three named options to a positive value, and the readme says you are opting in to a bound rather than raising one.

So a client written from the documentation with no configuration has an unbounded receive path. The guidance that follows is about how to live with that: consume incoming events promptly, or configure a buffer limit appropriate to the application.

The other defaults are specific enough to be useful. Connections start with a fixed number of pending sends and a fixed pool of lane identifiers counted over the connection's whole lifetime, including lanes that have already been closed, and a lane is reused for sequential responses. Exceeding an explicit receive bound fails the connection rather than dropping events quietly, which is the correct failure mode and worth having.

Teardown has a five second default timeout after which an unresponsive connection is torn down, and the readme asks you to close or abort explicitly when finished.

Messages are never replayed, and the transport is unavailable on the web

Two properties of the streaming transport are stated as guarantees rather than as behaviour, and both matter for anyone building on it.

The first is that application messages are never replayed. A handshake rejected over workload identity can refresh its token inside the configured retry budget, but the messages themselves are not resent, so a reconnect does not duplicate work. For an agent loop that can call tools, that is the difference between a dropped connection being cheap and being expensive.

The second is that these connections need native HTTP transport support, and they are therefore unavailable when the program is compiled for the browser. The readme adds that the rest of the library works there.

Below that is a clarification worth quoting for its precision: the streaming transport uses the same create call and the same events as the request-response interface, and not the lower-latency session interface that shares the brand name. The stream and background options are to be left unset, and a complete terminal snapshot is obtained by creating and then asking for the final response, which includes tool calls and retains the status of responses that failed or never completed.

The readme also documents where per-connection options apply: headers and similar settings bind to the opening handshake, and one option exposes the opening HTTP response itself.

Four policy documents, a migration guide, and a stats file nobody explains

The root directory tells you what this team thinks its job is.

There is a changelog, a contributing guide, a security policy, a code of quality policy, and a version support policy. There is a migration guide. There is an agent instruction file. There is a development container definition and a Brewfile for people working on macOS. There is a lint configuration and a formatter configuration.

Two files are named after something the readme never mentions. One is a ratchet configuration and the other is a statistics file, both sitting at the top level with a dot prefix. A ratchet usually means a metric that is allowed to improve and not to regress, and a statistics file beside it suggests the numbers that metric is measured against, but nothing in the visible documentation says so, and that is a real gap in a project that otherwise explains its own machinery carefully.

There is also a separate module for the examples, with its own manifest and lockfile, holding two dozen example directories. Several of those directories are named for specific cloud deployments, which is why the module resolves provider SDKs the library itself only needs for two integration paths.

Editorial conclusion

Adopt it if you want the vendor's own client rather than a generated community one, and read the requirements section before you pin, because the interpreter floor moves and there is a named last release for older toolchains with no backports behind it. Two things to decide. The readme warns that the current major carries breaking changes, so treat the version as something you choose deliberately. And the WebSocket transport ships with no receive bound, so set one before you point it at anything you do not control.

Frequently asked questions

Official sources

1. Issues
2. License: Apache-2.0
3. openai/openai-go on GitHub
4. README
5. Releases