Complete guide to contributing to OpenClaw - from setting up your development environment to submitting your first PR. Learn code standards, PR workflow, and community guidelines.
OpenClaw thrives because of contributors like you. Whether you're fixing bugs, adding features, improving documentation, or helping others in the community, every contribution matters. This guide walks you through everything you need to know.
Before contributing, ensure you have:
```bash
```
```bash
git clone https://github.com/YOUR_USERNAME/openclaw.git
cd openclaw
```
```bash
git remote add upstream https://github.com/openclaw/openclaw.git
```
```bash
npm install
cd python-sdk
pip install -e ".[dev]"
```
```bash
npm test
pytest
```
We follow strict coding standards to maintain code quality:
```typescript
// ✅ Gar naming, proper types, error handling
async function executeAgentTask(
task: Task,
options: ExecutionOptions
): Promise
if (!task.description) {
throw new ValidationError('Task description is required')
}
try {
const result = await this.agent.execute(task, options)
return {
status: 'completed',
output: result,
timestamp: new Date()
}
} catch (error) {
logger.error('Task execution failed', { task, error })
throw new ExecutionError(`Failed to execute task: ${error.message}`)
}
}
// ❌ Bad: Unclear naming, no types, poor error handling
async function doStuff(t, opts) {
const r = await this.agent.execute(t, opts)
return r
}
```
Key principles:
```python
from typing import Optional
from openclaw.types import Task, TaskResult
from openclaw.exceptions import ValidationError, ExecutionError
async def execute_agent_task(
task: Task,
options: Optional[ExecutionOptions] = None
) -> TaskResult:
"""
Execute an agent task with the given options.
Args:
task: The task to execute
options: Optional execution configuration
Returns:
TaskResult containing execution output and metadata
Raises:
ValidationError: If task is invalid
ExecutionError: If execution fails
"""
if not task.description:
raise ValidationError("Task description is required")
try:
result = await self.agent.execute(task, options)
return TaskResult(
status="completed",
output=result,
timestamp=datetime.now()
)
except Exception as error:
logger.error(f"Task execution failed: {error}", extra={"task": task})
raise ExecutionError(f"Failed to execute task: {error}")
async def do_stuff(t, opts=None):
r = await self.agent.execute(t, opts)
return r
```
Key principles:
All contributions must include tests. We maintain 80%+ code coverage.
```typescript
// TypeScript (Vitest)
import { describe, it, expect, vi } from 'vitest'
import { Agent } from '../src/agent'
describe('Agent', () => {
it('should execute simple tasks successfully', async () => {
const mockLLM = vi.fn().mockResolvedValue({
content: 'Task completed'
})
const agent = new Agent({ llm: mockLLM })
const result = await agent.execute({ description: 'Simple task' })
expect(result.status).toBe('completed')
expect(mockLLM).toHaveBeenCalledTimes(1)
})
it('should handle execution failures gracefully', async () => {
const mockLLM = vi.fn().mockRejectedValue(new Error('API error'))
const agent = new Agent({ llm: mockLLM })
await expect(
agent.execute({ description: 'Failing task' })
).rejects.toThrow('API error')
})
})
```
```python
import pytest
from openclaw import Agent
from openclaw.exceptions import ExecutionError
@pytest.mark.asyncio
async def test_agent_executes_simple_tasks():
"""Agent should execute simple tasks successfully."""
mock_llm = AsyncMock(return_value={"content": "Task completed"})
agent = Agent(llm=mock_llm)
result = await agent.execute({"description": "Simple task"})
assert result.status == "completed"
assert mock_llm.call_count == 1
@pytest.mark.asyncio
async def test_agent_handles_failures():
"""Agent should handle execution failures gracefully."""
mock_llm = AsyncMock(side_effect=Exception("API error"))
agent = Agent(llm=mock_llm)
with pytest.raises(ExecutionError, match="API error"):
await agent.execute({"description": "Failing task"})
```
```typescript
describe('Agent Integration Tests', () => {
it('should complete real tasks end-to-end', async () => {
const agent = new Agent({
apiKey: process.env.OPENCLAW_API_KEY
})
const result = await agent.execute({
description: 'Calculate 15% tip on $50',
maxSteps: 5
})
expect(result.status).toBe('completed')
expect(result.output).toContain('7.50')
}, 30000) // Longer timeout for real API calls
})
```
```bash
git checkout -b feature/your-feature-name
git checkout -b fix/bug-description
```
```bash
npm run lint
npm run format
black .
flake8 .
mypy .
```
We use Conventional Commits:
```bash
git commit -m "feat(agent): add parallel tool execution"
git commit -m "fix(api): handle rate limit errors correctly"
git commit -m "docs(readme): update installation instructions"
git commit -m "test(agent): add tests for error handling"
```
Types:
```bash
git push origin feature/your-feature-name
```
Then visit GitHub and click "Create Pull Request".
```markdown
Brief description of what this PR does.
Closes #123
```
Tips for faster reviews:
Look for issues labeled `good-first-issue`:
Before starting major features:
Documentation is always welcome:
Found a bug? Help us fix it:
```markdown
Bug Description
Clear description of the bug.
To Reproduce
Expected Behavior
What should happen.
Actual Behavior
What actually happens.
Environment
Additional Context
Any other relevant information.
```
We are committed to providing a welcoming and inclusive environment:
Stuck? Here's how to get help:
We value all contributions:
Maintainers have commit access and help guide the project:
Requirements:
Responsibilities:
Maintainers follow this process for releases:
Contributing to OpenClaw is rewarding and helps thousands of developers worldwide. Whether you're fixing a typo or adding a major feature, your contribution matters.
Ready to contribute? Check out our good first issues and join our Discord community.
Get your free AI audit and discover optimization opportunities.
START FREE AUDIT