Runbook: Setup & Credentials

docs / process / runbooks / setup-and-credentials

← all docs

Runbook: Setup & Credentials

Owner: Whoever is onboarding a repo to OCR | Frequency: Once per machine/CI runner Last Updated: 2026-08-14

Purpose

Install ocr and configure it to talk to an LLM provider, so ocr review/ocr scan can run. Skip this entirely if you only intend to use delegation mode — it needs no OCR-managed LLM credentials.

Prerequisites

Procedure

Step 1: Install

npm install -g @alibaba-group/open-code-review

Expected result: the ocr command is available globally (ocr version prints a version string). Alternatives (install script, GitHub Release binary, build from source) are documented at open-codereview.ai/docs/installation. If it fails: confirm npm -v works and you have global-install permissions; on managed/CI machines, prefer the install script or a Release binary instead of npm.

Step 2: Configure a provider

ocr config provider

Expected result: an interactive TUI wizard (see imgs/providers.jpg in the repo) lets you pick a built-in provider (anthropic, openai, or a custom endpoint), enter an API key, and it auto-tests connectivity. If it fails: run ocr llm test afterward to see the exact resolved endpoint and error; cross-check against docs/design/LLD.md §2 for the resolution precedence (env vars beat config.json).

Step 3: Pick a model

ocr config model

Expected result: a model list for the active provider (see internal/llm/providers.go's preset list for the built-in options); the chosen model is written to config.json.

Step 4: Verify

ocr llm test

Expected result: a successful round-trip to the configured endpoint. This is the exact same resolution path ocr review/ocr scan will use.

Verification

Troubleshooting

Symptom Likely Cause Fix
ocr llm test fails with an auth error API key env var not set, or config.json has a stale key Re-run ocr config provider; confirm which env var your protocol expects (ANTHROPIC_API_KEY / OPENAI_API_KEY).
Wrong model gets used An env var (OCR_LLM_PROTOCOL etc.) is overriding config.json Env vars always win — see LLD §2; unset the env var or intentionally use it instead of the config wizard.
npm install -g fails on a locked-down machine No global npm permission Use the install script or download a Release binary instead — see open-codereview.ai/docs/installation.

Rollback

ocr config unset <key> removes a single config key; deleting config.json (path shown by ocr config) resets everything to defaults. No credentials are ever written anywhere but that one local config file — nothing to roll back on the provider side.

Escalation

Situation Contact Method
Provider/API key issues Your LLM provider's support Provider's own support channel
OCR install/config bug OCR maintainers github.com/alibaba/open-code-review/issues

History

Date Run By Notes
2026-08-14 Onboarding kit build Verified command names against cmd/opencodereview/{config_cmd,llm_cmd}.go and the project README.