mirror of
https://github.com/Gitlawb/openclaude.git
synced 2026-08-24 10:14:19 -05:00
259c7ec27a
* fix(ollama): preserve chat history with native context Route Ollama chat requests through the native /api/chat endpoint so OpenClaude can send request-level options.num_ctx instead of relying on Ollama's OpenAI-compatible shim. Default the Ollama request context to 32768 tokens, support OPENCLAUDE_OLLAMA_NUM_CTX and OLLAMA_CONTEXT_LENGTH overrides, and map max tokens/temperature/top_p into native Ollama options. Adapt native Ollama streaming and non-streaming responses back into the existing OpenAI-shaped conversion pipeline, including usage, text, structured tool calls, and tool_use stop reasons. Normalize native Ollama request messages for images and historical tool calls, avoiding OpenAI-only image_url/id/type payload fields in /api/chat requests. Add Ollama context diagnostics, loopback-only ollama ps status checks, regression coverage, and documentation for verifying active context length. * fix(ollama): address native routing review feedback * fix(ollama): restrict loopback host matching * fix(ollama): exclude wildcard bind address * fix(ollama): keep https localhost proxies on chat completions --------- Co-authored-by: jatmn <12479882+jatmn@users.noreply.github.com>
190 lines
4.2 KiB
Markdown
190 lines
4.2 KiB
Markdown
# OpenClaude Quick Start for macOS and Linux
|
|
|
|
This guide uses a standard shell such as Terminal, iTerm, bash, or zsh.
|
|
|
|
## 1. Install Node.js
|
|
|
|
Install Node.js 22 LTS or newer from:
|
|
|
|
- `https://nodejs.org/`
|
|
|
|
Then check it:
|
|
|
|
```bash
|
|
node --version
|
|
npm --version
|
|
```
|
|
|
|
## 2. Install OpenClaude
|
|
|
|
```bash
|
|
npm install -g @gitlawb/openclaude@latest
|
|
```
|
|
On Arch Linux, you can alternatively install OpenClaude via the community-maintained [AUR package](https://aur.archlinux.org/packages/openclaude):
|
|
|
|
```bash
|
|
paru -S openclaude
|
|
```
|
|
## 3. Pick One Provider
|
|
|
|
### Option A: OpenAI
|
|
|
|
Replace `sk-your-key-here` with your real key.
|
|
|
|
```bash
|
|
export CLAUDE_CODE_USE_OPENAI=1
|
|
export OPENAI_API_KEY=sk-your-key-here
|
|
export OPENAI_MODEL=gpt-4o
|
|
|
|
openclaude
|
|
```
|
|
|
|
### Option B: DeepSeek
|
|
|
|
```bash
|
|
export CLAUDE_CODE_USE_OPENAI=1
|
|
export OPENAI_API_KEY=sk-your-key-here
|
|
export OPENAI_BASE_URL=https://api.deepseek.com/v1
|
|
export OPENAI_MODEL=deepseek-v4-flash
|
|
|
|
openclaude
|
|
```
|
|
|
|
Use `deepseek-v4-pro` when you want the stronger model. `deepseek-chat` and `deepseek-reasoner` still work as DeepSeek's legacy API aliases.
|
|
|
|
### Option C: Ollama
|
|
|
|
Install Ollama first from:
|
|
|
|
- `https://ollama.com/download`
|
|
|
|
Then run:
|
|
|
|
```bash
|
|
ollama pull llama3.1:8b
|
|
|
|
export CLAUDE_CODE_USE_OPENAI=1
|
|
export OPENAI_BASE_URL=http://localhost:11434/v1
|
|
export OPENAI_MODEL=llama3.1:8b
|
|
|
|
openclaude
|
|
```
|
|
|
|
No API key is needed for Ollama local models.
|
|
|
|
OpenClaude asks Ollama for a 32768-token context window on each chat request.
|
|
If you need a different size, set `OPENCLAUDE_OLLAMA_NUM_CTX` before launching
|
|
OpenClaude, or start Ollama with a global context setting:
|
|
|
|
```bash
|
|
# Stop any existing Ollama app/server first, then run:
|
|
OLLAMA_CONTEXT_LENGTH=32768 ollama serve
|
|
```
|
|
|
|
After a chat request, run `ollama ps` in another terminal and check the
|
|
`CONTEXT` column. It should show the requested size. If it still shows a small
|
|
value such as `4K`, restart the Ollama app/server and try again.
|
|
|
|
### Option D: LM Studio
|
|
|
|
Install LM Studio first from:
|
|
|
|
- `https://lmstudio.ai/`
|
|
|
|
Then in LM Studio:
|
|
|
|
1. Download a model (e.g., Llama 3.1 8B, Mistral 7B)
|
|
2. Go to the "Developer" tab
|
|
3. Select your model and enable the server via the toggle
|
|
|
|
Then run:
|
|
|
|
```bash
|
|
export CLAUDE_CODE_USE_OPENAI=1
|
|
export OPENAI_BASE_URL=http://localhost:1234/v1
|
|
export OPENAI_MODEL=your-model-name
|
|
# export OPENAI_API_KEY=lmstudio # optional: some users need a dummy key
|
|
|
|
openclaude
|
|
```
|
|
|
|
Replace `your-model-name` with the model name shown in LM Studio.
|
|
|
|
No API key is needed for LM Studio local models (but uncomment the `OPENAI_API_KEY` line if you hit auth errors).
|
|
|
|
### Option E: Using a .env file (Optional)
|
|
|
|
If you prefer to keep your keys in a `.env` file instead of exporting them individually, note that OpenClaude does not load `.env` files automatically. You must explicitly pass it:
|
|
|
|
```bash
|
|
openclaude --provider-env-file .env
|
|
```
|
|
|
|
Keep `.env` out of git because it contains secrets.
|
|
The explicit loader accepts provider/setup variables. Export runtime/debug variables from your shell or launcher instead.
|
|
|
|
## 4. If `openclaude` Is Not Found
|
|
|
|
Close the terminal, open a new one, and try again:
|
|
|
|
```bash
|
|
openclaude
|
|
```
|
|
|
|
## 5. If Your Provider Fails
|
|
|
|
Check the basics:
|
|
|
|
### For OpenAI or DeepSeek
|
|
|
|
- make sure the key is real
|
|
- make sure you copied it fully
|
|
|
|
### For Ollama
|
|
|
|
- make sure Ollama is installed
|
|
- make sure Ollama is running
|
|
- make sure the model was pulled successfully
|
|
- if same-session chat history appears missing, verify the active `CONTEXT`
|
|
value with `ollama ps`; OpenClaude requests 32K by default
|
|
|
|
### For LM Studio
|
|
|
|
- make sure LM Studio is installed
|
|
- make sure LM Studio is running
|
|
- make sure the server is enabled (toggle on in the "Developer" tab)
|
|
- make sure a model is loaded in LM Studio
|
|
- make sure the model name matches what you set in `OPENAI_MODEL`
|
|
|
|
## 6. Updating OpenClaude
|
|
|
|
**Via npm:**
|
|
```bash
|
|
npm install -g @gitlawb/openclaude@latest
|
|
```
|
|
|
|
**Via AUR:**
|
|
```bash
|
|
paru
|
|
```
|
|
*(Or use your preferred AUR helper like `yay -Syu`)*
|
|
|
|
## 7. Uninstalling OpenClaude
|
|
|
|
**Via npm:**
|
|
```bash
|
|
npm uninstall -g @gitlawb/openclaude
|
|
```
|
|
|
|
**Via AUR (Arch Linux):**
|
|
```bash
|
|
paru -Rns openclaude
|
|
```
|
|
|
|
## Need Advanced Setup?
|
|
|
|
Use:
|
|
|
|
- [Advanced Setup](advanced-setup.md)
|
|
For Codex, Gemini, Mistral, LiteLLM, provider profiles, and runtime diagnostics.
|