Skip to content

docs(connector): add self-hosted connector integration guide#293

Merged
BlackHole1 merged 1 commit into
mainfrom
docs/self-hosted-connector-guide
Jul 4, 2026
Merged

docs(connector): add self-hosted connector integration guide#293
BlackHole1 merged 1 commit into
mainfrom
docs/self-hosted-connector-guide

Conversation

@BlackHole1

Copy link
Copy Markdown
Member

Summary

Adds a dedicated integration guide, in both English and Simplified Chinese, for
pointing the oo CLI at a self-hosted connector server. The content is distilled
from the self-hosted connector feature (#291) and its follow-up cleanup (#292).

The command reference in docs/commands.md only records the per-command CLI
contract, so there was no single place explaining the end-to-end onboarding flow
or the HTTP contract a connector server must expose. The new guides cover both
audiences:

  • Operatorsoo connector login/logout, runtime tokens and the
    /access page, the OO_CONNECTOR_URL > OO_API_KEY > connector.toml >
    account routing precedence, headless/CI env overrides, and the OOMOL vs
    self-hosted feature differences (org identity rejected, async --wait
    unsupported, proxy dependent on server support).
  • Server implementers — the /v1/* endpoints (method, path, purpose), the
    health envelope, the Bearer auth model, and the response shapes.

Changes

  • docs/self-hosted-connector.md — English integration guide.
  • docs/self-hosted-connector.zh-CN.md — Simplified Chinese integration guide.
  • README.md / README-ZH_CN.md — link both guides from the Links section.

Notes

  • Docs-only change; no source or test files touched.
  • All documented behavior (endpoints/methods, routing precedence, login
    validation exit codes, oo auth status output shape, connector.toml format
    and paths) was cross-checked against the current implementation.

Document how to point the `oo` CLI at a self-hosted connector server
in both English and Simplified Chinese, distilled from the self-hosted
connector feature (#291) and its follow-up cleanup (#292).

The command reference in `docs/commands.md` only records the per-command
CLI contract, so there was no single place that explained the end-to-end
onboarding flow or the HTTP contract a connector server must expose. The
new guides cover both audiences: operators wiring the CLI to a server
(`oo connector login`/`logout`, runtime tokens and the `/access` page,
the `OO_CONNECTOR_URL` > `OO_API_KEY` > `connector.toml` > account
routing precedence, and the OOMOL vs self-hosted feature differences),
and server implementers (the `/v1/*` endpoints, health envelope, Bearer
auth model, and response shapes).

Link both guides from `README.md` and `README-ZH_CN.md` for discovery.

Signed-off-by: Kevin Cui <bh@bugs.cc>
@coderabbitai

coderabbitai Bot commented Jul 4, 2026

Copy link
Copy Markdown

Review Change Stack

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info
⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 8036f1b0-9b07-4c9f-9fbe-001f2bceeb50

📥 Commits

Reviewing files that changed from the base of the PR and between 8b1207c and 0088eb3.

📒 Files selected for processing (4)
  • README-ZH_CN.md
  • README.md
  • docs/self-hosted-connector.md
  • docs/self-hosted-connector.zh-CN.md

Summary by CodeRabbit

  • Documentation
    • Added a new guide for setting up and using a self-hosted connector.
    • Updated the main README links to include the new connector integration guide.
    • Added a Chinese version of the self-hosted connector documentation.

Walkthrough

This PR adds two new documentation pages, docs/self-hosted-connector.md and its Chinese counterpart docs/self-hosted-connector.zh-CN.md, describing how to configure and use a self-hosted connector with the oo CLI, including login validation, environment overrides, feature differences from the OOMOL-hosted connector, status inspection, connector.toml storage/logout behavior, the required server HTTP contract, and a troubleshooting table. README.md and README-ZH_CN.md are each updated with a new link to their respective new page.

Sequence Diagram(s)

Not applicable — this change consists solely of documentation additions and README link updates with no code or control-flow changes.

Estimated code review effort: Low-Medium

Related PRs: None identified.

Suggested labels: documentation

Suggested reviewers: None identified.

🐰 A rabbit hops through docs anew,
Self-hosted paths in black and blue,
Two tongues speak of tokens bright,
README links now guide the sight,
No code was touched, just words made right.

🚥 Pre-merge checks | ✅ 4
✅ Passed checks (4 passed)
Check name Status Explanation
Title check ✅ Passed The title follows the required type(scope): subject format and accurately reflects the documentation update.
Description check ✅ Passed The description is directly related to the docs-only self-hosted connector guide and README link updates.
Linked Issues check ✅ Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check ✅ Passed Check skipped because no linked issues were found for this pull request.
✨ Finishing Touches
✨ Simplify code
  • Create PR with simplified code
  • Commit simplified code in branch docs/self-hosted-connector-guide

Comment @coderabbitai help to get the list of available commands.

@BlackHole1 BlackHole1 merged commit 2260840 into main Jul 4, 2026
6 checks passed
@BlackHole1 BlackHole1 deleted the docs/self-hosted-connector-guide branch July 4, 2026 15:17
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant