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
- [ ] Git ≥ 2.41 installed and on
PATH. - [ ] Either Node.js (for
npm install -g) or nothing extra (for the install script / GitHub Release binary). - [ ] An API key for your chosen provider (Anthropic or OpenAI, or a custom OpenAI-compatible endpoint).
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
- [ ]
ocr llm testsucceeds. - [ ]
ocr config(no subcommand) shows the resolved provider/model without prompting.
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. |